Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

This commit was manufactured by cvs2svn to create tag

'POST_APR_SPLIT'.

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/tags/POST_APR_SPLIT@87039 13f79535-47bb-0310-9956-ffa450edef68
  • Loading branch information...
commit f1e53895956e742680d6f725ae5a4be03e1854d9 1 parent dab7ff0
No Author authored
Showing with 0 additions and 13,065 deletions.
  1. +0 −300 build/binbuild.sh
  2. BIN  docs/docroot/apache_pb.gif
  3. +0 −135 docs/manual/bind.html.en
  4. +0 −93 docs/manual/cgi_path.html.en
  5. +0 −242 docs/manual/configuring.html.en
  6. +0 −588 docs/manual/content-negotiation.html.en
  7. +0 −177 docs/manual/custom-error.html.en
  8. +0 −1,153 docs/manual/developer/API.html
  9. +0 −200 docs/manual/developer/modules.html.en
  10. +0 −393 docs/manual/dso.html.en
  11. +0 −156 docs/manual/handler.html.en
  12. +0 −174 docs/manual/index.html.en
  13. +0 −270 docs/manual/install.html.en
  14. +0 −144 docs/manual/invoking.html.en
  15. +0 −265 docs/manual/mod/directive-dict.html.en
  16. +0 −144 docs/manual/mod/module-dict.html.en
  17. +0 −96 docs/manual/mpm.html.en
  18. +0 −79 docs/manual/new_features_2_0.html.en
  19. +0 −278 docs/manual/platform/netware.html
  20. +0 −254 docs/manual/platform/perf-bsd44.html
  21. +0 −285 docs/manual/platform/perf-dec.html
  22. +0 −122 docs/manual/platform/perf-hp.html
  23. +0 −175 docs/manual/platform/perf.html
  24. +0 −208 docs/manual/platform/readme-tpf.html
  25. +0 −62 docs/manual/platform/unixware.html
  26. +0 −182 docs/manual/platform/win_compiling.html
  27. +0 −325 docs/manual/platform/win_service.html
  28. +0 −511 docs/manual/platform/windows.html
  29. +0 −170 docs/manual/sections.html.en
  30. +0 −217 docs/manual/server-wide.html.en
  31. +0 −183 docs/manual/stopping.html.en
  32. +0 −518 docs/manual/suexec.html.en
  33. +0 −94 docs/manual/upgrading.html.en
  34. +0 −59 docs/manual/vhosts/fd-limits.html.en
  35. +0 −65 docs/manual/vhosts/index.html.en
  36. +0 −169 docs/manual/vhosts/name-based.html.en
  37. +0 −553 httpd.dsp
  38. +0 −440 libhttpd.def
  39. +0 −100 libhttpd.dsp
  40. +0 −1,294 modules/arch/win32/mod_isapi.c
  41. +0 −10 os/win32/libhttpd.c
  42. +0 −5 server/mpm/experimental/perchild/.cvsignore
  43. +0 −5 server/mpm/experimental/perchild/Makefile.in
  44. +0 −88 server/mpm/experimental/perchild/mpm.h
  45. +0 −144 server/mpm/experimental/perchild/mpm_default.h
  46. +0 −1,765 server/mpm/experimental/perchild/perchild.c
  47. +0 −51 srclib/expat-lite/libexpat.def
  48. +0 −124 srclib/expat-lite/libexpat.dsp
300 build/binbuild.sh
View
@@ -1,300 +0,0 @@
-#!/bin/sh
-#
-# binbuild.sh - Builds an Apache binary distribution.
-# Initially written by Lars Eilebrecht <lars@apache.org>.
-#
-# This script falls under the Apache License.
-# See http://www.apache.org/docs/LICENSE
-
-OS=`src/helpers/GuessOS`
-case "x$OS" in
- x*390*) CONFIGPARAM="--with-layout=BinaryDistribution --enable-module=most";;
- *) CONFIGPARAM="--with-layout=BinaryDistribution --enable-module=most --enable-shared=max";;
-esac
-APDIR=`pwd`
-APDIR=`basename $APDIR`
-VER=`echo $APDIR |sed s/apache_//`
-TAR="`src/helpers/PrintPath tar`"
-GTAR="`src/helpers/PrintPath gtar`"
-GZIP="`src/helpers/PrintPath gzip`"
-
-if [ x$1 != x ]
-then
- USER=$1
-else
- USER="`src/helpers/buildinfo.sh -n %u@%h%d`"
-fi
-
-if [ ! -f ./ABOUT_APACHE ]
-then
- echo "ERROR: The current directory contains no valid Apache distribution."
- echo "Please change the directory to the top level directory of a freshly"
- echo "unpacked Apache 1.3 source distribution and re-execute the script"
- echo "'./src/helpers/bindbuild.sh'."
- exit 1;
-fi
-
-if [ -d ./CVS ]
-then
- echo "ERROR: The current directory is a CVS checkout of Apache."
- echo "Only a standard Apache 1.3 source distribution should be used to"
- echo "create a binary distribution."
- exit 1;
-fi
-
-echo "Building Apache $VER binary distribution..."
-echo "Platform is \"$OS\"..."
-
-( echo "Build log for Apache binary distribution" && \
- echo "----------------------------------------------------------------------" && \
- ./configure $CONFIGPARAM && \
- echo "----------------------------------------------------------------------" && \
- make clean && \
- rm -rf bindist install-bindist.sh *.bindist
- echo "----------------------------------------------------------------------" && \
- make && \
- echo "----------------------------------------------------------------------" && \
- make install-quiet root="bindist/" && \
- echo "----------------------------------------------------------------------" && \
- make clean && \
- echo "----------------------------------------------------------------------" && \
- echo "[EOF]" \
-) > build.log 2>&1
-
-if [ ! -f ./bindist/bin/httpd ]
-then
- echo "ERROR: Failed to build Apache. See \"build.log\" for details."
- exit 1;
-fi
-
-echo "Binary image successfully created..."
-
-./bindist/bin/httpd -v
-
-echo "Creating supplementary files..."
-
-( echo " " && \
- echo "Apache $VER binary distribution" && \
- echo "================================" && \
- echo " " && \
- echo "This binary distribution is usable on a \"$OS\"" && \
- echo "system and was built by \"$USER\"." && \
- echo "" && \
- echo "The distribution contains all standard Apache modules as shared" && \
- echo "objects. This allows you to enable or disable particular modules" && \
- echo "with the LoadModule/AddModule directives in the configuration file" && \
- echo "without the need to re-compile Apache." && \
- echo "" && \
- echo "See \"INSTALL.bindist\" on how to install the distribution." && \
- echo " " && \
- echo "NOTE: Please do not send support-related mails to the address mentioned" && \
- echo " above or to any member of the Apache Group! Support questions" && \
- echo " should be directed to the \"comp.infosystems.www.servers.unix\"" && \
- echo " or \"comp.infosystems.www.servers.ms-windows\" newsgroup" && \
- echo " (as appropriate for the platform you use), where some of the" && \
- echo " Apache team lurk, in the company of many other Apache gurus" && \
- echo " who should be able to help." && \
- echo " If you think you found a bug in Apache or have a suggestion please" && \
- echo " visit the bug report page at http://www.apache.org/bug_report.html" && \
- echo " " && \
- echo "----------------------------------------------------------------------" && \
- ./bindist/bin/httpd -V && \
- echo "----------------------------------------------------------------------" \
-) > README.bindist
-cp README.bindist ../apache_$VER-$OS.README
-
-( echo " " && \
- echo "Apache $VER binary installation" && \
- echo "================================" && \
- echo " " && \
- echo "To install this binary distribution you have to execute the installation" && \
- echo "script \"install-bindist.sh\" in the top-level directory of the distribution." && \
- echo " " && \
- echo "The script takes the ServerRoot directory into which you want to install" && \
- echo "Apache as an option. If you ommit the option the default path" && \
- echo "\"/usr/local/apache\" is used." && \
- echo "Make sure you have write permissions in the target directory, e.g. switch" && \
- echo "to user \"root\" before you execute the script." && \
- echo " " && \
- echo "See \"README.bindist\" for further details about this distribution." && \
- echo " " && \
- echo "Please note that this distribution includes the complete Apache source code." && \
- echo "Therefore you may compile Apache yourself at any time if you have a compiler" && \
- echo "installation on your system." && \
- echo "See \"INSTALL\" for details on how to accomplish this." && \
- echo " " \
-) > INSTALL.bindist
-
-( echo "#!/bin/sh" && \
- echo "#" && \
- echo "# Usage: install-bindist.sh [ServerRoot]" && \
- echo "# This script installs the Apache binary distribution and" && \
- echo "# was automatically created by binbuild.sh." && \
- echo " " && \
- echo "lmkdir()" && \
- echo "{" && \
- echo " path=\"\"" && \
- echo " dirs=\`echo \$1 | sed -e 's%/% %g'\`" && \
- echo " mode=\$2" && \
- echo " " && \
- echo " set -- \${dirs}" && \
- echo " " && \
- echo " for d in \${dirs}" && \
- echo " do" && \
- echo " path=\"\${path}/\$d\"" && \
- echo " if test ! -d \"\${path}\" ; then" && \
- echo " mkdir \${path}" && \
- echo " if test \$? -ne 0 ; then" && \
- echo " echo \"Failed to create directory: \${path}\"" && \
- echo " exit 1" && \
- echo " fi" && \
- echo " chmod \${mode} \${path}" && \
- echo " fi" && \
- echo " done" && \
- echo "}" && \
- echo " " && \
- echo "lcopy()" && \
- echo "{" && \
- echo " from=\$1" && \
- echo " to=\$2" && \
- echo " dmode=\$3" && \
- echo " fmode=\$4" && \
- echo " " && \
- echo " test -d \${to} || lmkdir \${to} \${dmode}" && \
- echo " (cd \${from} && tar -cf - *) | (cd \${to} && tar -xf -)" && \
- echo " " && \
- echo " if test \"X\${fmode}\" != X ; then" && \
- echo " find \${to} -type f -print | xargs chmod \${fmode}" && \
- echo " fi" && \
- echo " if test \"X\${dmode}\" != X ; then" && \
- echo " find \${to} -type d -print | xargs chmod \${dmode}" && \
- echo " fi" && \
- echo "}" && \
- echo " " && \
- echo "##" && \
- echo "## determine path to (optional) Perl interpreter" && \
- echo "##" && \
- echo "PERL=no-perl5-on-this-system" && \
- echo "perls='perl5 perl'" && \
- echo "path=\`echo \$PATH | sed -e 's/:/ /g'\`" && \
- echo " " && \
- echo "for dir in \${path} ; do" && \
- echo " for pperl in \${perls} ; do" && \
- echo " if test -f \"\${dir}/\${pperl}\" ; then" && \
- echo " if \`\${dir}/\${pperl} -v | grep 'version 5\.' >/dev/null 2>&1\` ; then" && \
- echo " PERL=\"\${dir}/\${pperl}\"" && \
- echo " break" && \
- echo " fi" && \
- echo " fi" && \
- echo " done" && \
- echo "done" && \
- echo " " && \
- echo "if [ .\$1 = . ]" && \
- echo "then" && \
- echo " SR=/usr/local/apache" && \
- echo "else" && \
- echo " SR=\$1" && \
- echo "fi" && \
- echo "echo \"Installing binary distribution for platform $OS\"" && \
- echo "echo \"into directory \$SR ...\"" && \
- echo "lmkdir \$SR 755" && \
- echo "lmkdir \$SR/proxy 750" && \
- echo "lmkdir \$SR/logs 750" && \
- echo "lcopy bindist/man \$SR/man 755 644" && \
- echo "lcopy bindist/libexec \$SR/libexec 750 644" && \
- echo "lcopy bindist/include \$SR/include 755 644" && \
- echo "lcopy bindist/icons \$SR/icons 755 644" && \
- echo "lcopy bindist/cgi-bin \$SR/cgi-bin 750 750" && \
- echo "lcopy bindist/bin \$SR/bin 750 750" && \
- echo "if [ -d \$SR/conf ]" && \
- echo "then" && \
- echo " echo \"[Preserving existing configuration files.]\"" && \
- echo " cp bindist/conf/*.default \$SR/conf/" && \
- echo "else" && \
- echo " lcopy bindist/conf \$SR/conf 750 640" && \
- echo "fi" && \
- echo "if [ -d \$SR/htdocs ]" && \
- echo "then" && \
- echo " echo \"[Preserving existing htdocs directory.]\"" && \
- echo "else" && \
- echo " lcopy bindist/htdocs \$SR/htdocs 755 644" && \
- echo "fi" && \
- echo " " && \
- echo "sed -e \"s;^#!/.*;#!\$PERL;\" -e \"s;\@prefix\@;\$SR;\" -e \"s;\@sbindir\@;\$SR/bin;\" \\" && \
- echo " -e \"s;\@libexecdir\@;\$SR/libexec;\" -e \"s;\@includedir\@;\$SR/include;\" \\" && \
- echo " -e \"s;\@sysconfdir\@;\$SR/conf;\" bindist/bin/apxs > \$SR/bin/apxs" && \
- echo "sed -e \"s;^#!/.*;#!\$PERL;\" bindist/bin/dbmmanage > \$SR/bin/dbmmanage" && \
- echo "sed -e \"s%/usr/local/apache%\$SR%\" \$SR/conf/httpd.conf.default > \$SR/conf/httpd.conf" && \
- echo "sed -e \"s%PIDFILE=%PIDFILE=\$SR/%\" -e \"s%HTTPD=%HTTPD=\\\"\$SR/%\" -e \"s%httpd\$%httpd -d \$SR -R \$SR/libexec\\\"%\" bindist/bin/apachectl > \$SR/bin/apachectl" && \
- echo " " && \
- echo "echo \"Ready.\"" && \
- echo "echo \" +--------------------------------------------------------+\"" && \
- echo "echo \" | You now have successfully installed the Apache $VER |\"" && \
- echo "echo \" | HTTP server. To verify that Apache actually works |\"" && \
- echo "echo \" | correctly you should first check the (initially |\"" && \
- echo "echo \" | created or preserved) configuration files: |\"" && \
- echo "echo \" | |\"" && \
- echo "echo \" | \$SR/conf/httpd.conf\"" && \
- echo "echo \" | |\"" && \
- echo "echo \" | You should then be able to immediately fire up |\"" && \
- echo "echo \" | Apache the first time by running: |\"" && \
- echo "echo \" | |\"" && \
- echo "echo \" | \$SR/bin/apachectl start \"" &&\
- echo "echo \" | |\"" && \
- echo "echo \" | Thanks for using Apache. The Apache Group |\"" && \
- echo "echo \" | http://www.apache.org/ |\"" && \
- echo "echo \" +--------------------------------------------------------+\"" && \
- echo "echo \" \"" \
-) > install-bindist.sh
-chmod 755 install-bindist.sh
-
-sed -e "s%\"htdocs%\"/usr/local/apache/htdocs%" \
- -e "s%\"icons%\"/usr/local/apache/icons%" \
- -e "s%\"cgi-bin%\"/usr/local/apache/cgi-bin%" \
- -e "s%\"proxy%\"/usr/local/apache/proxy%" \
- -e "s%^ServerAdmin.*%ServerAdmin you@your.address%" \
- -e "s%#ServerName.*%#ServerName localhost%" \
- -e "s%Port 8080%Port 80%" \
- bindist/conf/httpd.conf.default > bindist/conf/httpd.conf
-cp bindist/conf/httpd.conf bindist/conf/httpd.conf.default
-
-echo "Creating distribution archive and readme file..."
-
-if [ ".`grep -i error build.log > /dev/null`" != . ]
-then
- echo "ERROR: Failed to build Apache. See \"build.log\" for details."
- exit 1;
-else
- if [ "x$GTAR" != "x" ]
- then
- $GTAR -zcf ../apache_$VER-$OS.tar.gz -C .. apache_$VER
- else
- if [ "x$TAR" != "x" ]
- then
- case "x$OS" in
- x*390*) $TAR -cfU ../apache_$VER-$OS.tar -C .. apache_$VER;;
- *) (cd .. && $TAR -cf apache_$VER-$OS.tar apache_$VER);;
- esac
- if [ "x$GZIP" != "x" ]
- then
- $GZIP ../apache_$VER-$OS.tar
- fi
- else
- echo "ERROR: Could not find a 'tar' program!"
- echo " Please execute the following commands manually:"
- echo " tar -cf ../apache_$VER-$OS.tar ."
- echo " gzip ../apache_$VER-$OS.tar"
- fi
- fi
-
- if [ -f ../apache_$VER-$OS.tar.gz ] && [ -f ../apache_$VER-$OS.README ]
- then
- echo "Ready."
- echo "You can find the binary archive (apache_$VER-$OS.tar.gz)"
- echo "and the readme file (apache_$VER-$OS.README) in the"
- echo "parent directory."
- exit 0;
- else
- exit 1;
- fi
-fi
BIN  docs/docroot/apache_pb.gif
View
Deleted file not rendered
135 docs/manual/bind.html.en
View
@@ -1,135 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML><HEAD>
-<TITLE>Setting which addresses and ports Apache uses</TITLE>
-</HEAD>
-
-<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
-<BODY
- BGCOLOR="#FFFFFF"
- TEXT="#000000"
- LINK="#0000FF"
- VLINK="#000080"
- ALINK="#FF0000"
->
-<!--#include virtual="header.html" -->
-<H1 ALIGN="CENTER">Setting which addresses and ports Apache uses</H1>
-
-<HR>
-
-When Apache starts, it connects to some port and address on the
-local machine and waits for incoming requests. By default, it
-listens to all addresses on the machine, and to the port
-as specified by the <TT>Port</TT> directive in the server configuration.
-However, it can be told to listen to more the one port, or to listen
-to only selected addresses, or a combination. This is often combined
-with the Virtual Host feature which determines how Apache
-responds to different IP addresses, hostnames and ports.<P>
-
-There are two directives used to restrict or specify which addresses
-and ports Apache listens to.
-
-<UL>
-<LI><A HREF="#bindaddress">BindAddress</A> is used to restrict the server to
- listening to
- a single address, and can be used to permit multiple Apache servers
- on the same machine listening to different IP addresses.
-<LI><A HREF="#listen">Listen</A> can be used to make a single Apache server
- listen
- to more than one address and/or port.
-</UL>
-
-<H3><A NAME="bindaddress">BindAddress</A></H3>
-<A
- HREF="mod/directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> BindAddress <EM>[ * | IP-address
- | hostname ]</EM><BR>
-<A
- HREF="mod/directive-dict.html#Default"
- REL="Help"
-><STRONG>Default:</STRONG></A> <CODE>BindAddress *</CODE><BR>
-<A
- HREF="mod/directive-dict.html#Context"
- REL="Help"
-><STRONG>Context:</STRONG></A> server config<BR>
-<A
- HREF="mod/directive-dict.html#Status"
- REL="Help"
-><STRONG>Status:</STRONG></A> Core<P>
-
-Makes the server listen to just the specified address. If the argument
-is *, the server listens to all addresses. The port listened to
-is set with the <TT>Port</TT> directive. Only one BindAddress
-should be used.
-
-<H3><A NAME="listen">Listen</A></H3>
-<A
- HREF="mod/directive-dict.html#Syntax"
- REL="Help"
-><STRONG>Syntax:</STRONG></A> Listen <EM>[ port | IP-address:port ]</EM><BR>
-<A
- HREF="mod/directive-dict.html#Default"
- REL="Help"
-><STRONG>Default:</STRONG></A> <CODE>none</CODE><BR>
-<A
- HREF="mod/directive-dict.html#Context"
- REL="Help"
-><STRONG>Context:</STRONG></A> server config<BR>
-<A
- HREF="mod/directive-dict.html#Status"
- REL="Help"
-><STRONG>Status:</STRONG></A> Core<P>
-
-<TT>Listen</TT> can be used instead of <TT>BindAddress</TT> and
-<TT>Port</TT>. It tells the server to accept incoming requests on the
-specified port or address-and-port combination. If the first format is
-used, with a port number only, the server listens to the given port on
-all interfaces, instead of the port given by the <TT>Port</TT>
-directive. If an IP address is given as well as a port, the server
-will listen on the given port and interface. <P> Multiple Listen
-directives may be used to specify a number of addresses and ports to
-listen to. The server will respond to requests from any of the listed
-addresses and ports.<P>
-
-For example, to make the server accept connections on both port
-80 and port 8000, use:
-<PRE>
- Listen 80
- Listen 8000
-</PRE>
-
-To make the server accept connections on two specified
-interfaces and port numbers, use
-<PRE>
- Listen 192.170.2.1:80
- Listen 192.170.2.5:8000
-</PRE>
-
-<H2>How this works with Virtual Hosts</H2>
-
-BindAddress and Listen do not implement Virtual Hosts. They tell the
-main server what addresses and ports to listen to. If no
-&lt;VirtualHost&gt; directives are used, the server will behave the
-same for all accepted requests. However, &lt;VirtualHost&gt; can be
-used to specify a different behavior for one or more of the addresses
-and ports. To implement a VirtualHost, the server must first be told
-to listen to the address and port to be used. Then a
-&lt;VirtualHost&gt; section should be created for a specified address
-and port to set the behavior of this virtual host. Note that if the
-&lt;VirtualHost&gt; is set for an address and port that the server is
-not listening to, it cannot be accessed.
-
-<H2>See also</H2>
-
-See also the documentation on
-<A HREF="vhosts/index.html">Virtual Hosts</A>,
-<A HREF="mod/core.html#bindaddress">BindAddress directive</A>,
-<A HREF="mod/core.html#port">Port directive</A>,
-<A HREF="dns-caveats.html">DNS Issues</A>
-and
-<A HREF="mod/core.html#virtualhost">&lt;VirtualHost&gt; section</A>.
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
-
93 docs/manual/cgi_path.html.en
View
@@ -1,93 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML><HEAD>
-<TITLE>PATH_INFO Changes in the CGI Environment</TITLE>
-</HEAD>
-
-<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
-<BODY
- BGCOLOR="#FFFFFF"
- TEXT="#000000"
- LINK="#0000FF"
- VLINK="#000080"
- ALINK="#FF0000"
->
-<!--#include virtual="header.html" -->
-<H1 ALIGN="CENTER">PATH_INFO Changes in the CGI Environment</H1>
-
-<HR>
-
-<H2><A NAME="over">Overview</A></H2>
-
-<P>As implemented in Apache 1.1.1 and earlier versions, the method
-Apache used to create PATH_INFO in the CGI environment was
-counterintuitive, and could result in crashes in certain cases. In
-Apache 1.2 and beyond, this behavior has changed. Although this
-results in some compatibility problems with certain legacy CGI
-applications, the Apache 1.2 behavior is still compatible with the
-CGI/1.1 specification, and CGI scripts can be easily modified (<A
-HREF="#compat">see below</A>).
-
-<H2><A NAME="prob">The Problem</A></H2>
-
-<P>Apache 1.1.1 and earlier implemented the PATH_INFO and SCRIPT_NAME
-environment variables by looking at the filename, not the URL. While
-this resulted in the correct values in many cases, when the filesystem
-path was overloaded to contain path information, it could result in
-errant behavior. For example, if the following appeared in a config
-file:
-<PRE>
- Alias /cgi-ralph /usr/local/httpd/cgi-bin/user.cgi/ralph
-</PRE>
-<P>In this case, <CODE>user.cgi</CODE> is the CGI script, the "/ralph"
-is information to be passed onto the CGI. If this configuration was in
-place, and a request came for "<CODE>/cgi-ralph/script/</CODE>", the
-code would set PATH_INFO to "<CODE>/ralph/script</CODE>", and
-SCRIPT_NAME to "<CODE>/cgi-</CODE>". Obviously, the latter is
-incorrect. In certain cases, this could even cause the server to
-crash.</P>
-
-<H2><A NAME="solution">The Solution</A></H2>
-
-<P>Apache 1.2 and later now determine SCRIPT_NAME and PATH_INFO by
-looking directly at the URL, and determining how much of the URL is
-client-modifiable, and setting PATH_INFO to it. To use the above
-example, PATH_INFO would be set to "<CODE>/script</CODE>", and
-SCRIPT_NAME to "<CODE>/cgi-ralph</CODE>". This makes sense and results
-in no server behavior problems. It also permits the script to be
-guaranteed that
-"<CODE>http://$SERVER_NAME:$SERVER_PORT$SCRIPT_NAME$PATH_INFO</CODE>"
-will always be an accessible URL that points to the current script,
-something which was not necessarily true with previous versions of
-Apache.
-
-<P>However, the "<CODE>/ralph</CODE>"
-information from the <CODE>Alias</CODE> directive is lost. This is
-unfortunate, but we feel that using the filesystem to pass along this
-sort of information is not a recommended method, and a script making
-use of it "deserves" not to work. Apache 1.2b3 and later, however, do
-provide <A HREF="#compat">a workaround.</A>
-
-<H2><A NAME="compat">Compatibility with Previous Servers</A></H2>
-
-<P>It may be necessary for a script that was designed for earlier
-versions of Apache or other servers to need the information that the
-old PATH_INFO variable provided. For this purpose, Apache 1.2 (1.2b3
-and later) sets an additional variable, FILEPATH_INFO. This
-environment variable contains the value that PATH_INFO would have had
-with Apache 1.1.1.</P>
-
-<P>A script that wishes to work with both Apache 1.2 and earlier
-versions can simply test for the existence of FILEPATH_INFO, and use
-it if available. Otherwise, it can use PATH_INFO. For example, in
-Perl, one might use:
-<PRE>
- $path_info = $ENV{'FILEPATH_INFO'} || $ENV{'PATH_INFO'};
-</PRE>
-
-<P>By doing this, a script can work with all servers supporting the
-CGI/1.1 specification, including all versions of Apache.</P>
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
-
242 docs/manual/configuring.html.en
View
@@ -1,242 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
-<HEAD>
-<TITLE>Configuration Files</TITLE>
-</HEAD>
-
-<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
-<BODY
- BGCOLOR="#FFFFFF"
- TEXT="#000000"
- LINK="#0000FF"
- VLINK="#000080"
- ALINK="#FF0000"
->
-<!--#include virtual="header.html" -->
-<H1 ALIGN="CENTER">Configuration Files</H1>
-
-<ul>
-<li><a href="#main">Main Configuration Files</a></li>
-<li><a href="#syntax">Syntax of the Configuration Files</a></li>
-<li><a href="#modules">Modules</a></li>
-<li><a href="#scope">Scope of Directives</a></li>
-<li><a href="#htaccess">.htaccess Files</a></li>
-<li><a href="#log">Log Files</a></li>
-</ul>
-
-<hr>
-
-<H2><a name="main">Main Configuration Files</a></H2>
-
-<table border="1"><tr><td valign="top">
-<strong>Related Modules</strong><br><br>
-<a href="mod/mod_mime.html">mod_mime</a><br>
-</td>
-
-<td valign="top">
-<strong>Related Directives</strong><br><br>
-<A HREF="mod/core.html#accessconfig">AccessConfig</A><br>
-<A HREF="mod/core.html#ifdefine">&lt;IfDefine&gt;</A><br>
-<a href="mod/core.html#include">Include</a><br>
-<A HREF="mod/core.html#resourceconfig">ResourceConfig</A><br>
-<A HREF="mod/mod_mime.html#typesconfig">TypesConfig</A><br>
-</td></tr></table>
-
-<P>Apache is configured by placing <A HREF="mod/directives.html"
->directives</A> in plain text configuration files. The main
-configuration file is usually called <CODE>httpd.conf</CODE>. The
-location of this file is set at compile-time, but may be overridden
-with the <CODE>-f</CODE> command line flag. Some sites also have
-<CODE>srm.conf</CODE> and <CODE>access.conf</CODE> files for <A
-HREF="http://www.apache.org/info/three-config-files.html">historical
-reasons</A>. In addition, other configuration files may be added using
-the <CODE><A HREF="mod/core.html#include">Include</A></CODE>
-directive. Any directive may be placed in any of these configuration
-files. Changes to the main configuration files are only recognized by
-Apache when it is started or restarted.</p>
-
-<P>
-The server also reads a file containing mime document types; the
-filename is set by the <A HREF="mod/mod_mime.html#typesconfig"
->TypesConfig</A> directive, and is <CODE>mime.types</CODE> by default.
-
-<hr>
-
-<H2><a name="syntax">Syntax of the Configuration Files</a></H2>
-
-<P>Apache configuration files contain one directive per line. The
-back-slash "\" may be used as the last character on a line to indicate
-that the directive continues onto the next line. There must be no
-other characters or white space between the back-slash and the end of
-the line.
-
-<P>Directives in the configuration files are case-insensitive, but
-arguments to directives are often case sensitive. Lines which begin
-with the hash character "#" are considered comments, and are ignored.
-Comments may <STRONG>not</STRONG> be included on a line after a
-configuration directive. Blank lines and white space occurring before
-a directive are ignored, so you may indent directives for clarity.
-
-<P>You can check your configuration files for syntax errors without
-starting the server by using <CODE>apachectl configtest</CODE>
-or the <CODE>-t</CODE> command line option.
-
-<hr>
-
-<H2><a name="modules">Modules</a></H2>
-
-<table border="1"><tr><td valign="top">
-<strong>Related Modules</strong><br><br>
-<a href="mod/mod_so.html">mod_so</a><br>
-</td>
-<td valign="top">
-<strong>Related Directives</strong><br><br>
-<A HREF="mod/core.html#addmodule">AddModule</A><br>
-<A HREF="mod/core.html#clearmodulelist">ClearModuleList</A><br>
-<A HREF="mod/core.html#ifmodule">&lt;IfModule&gt;</A><br>
-<a href="mod/mod_so.html">LoadModule</a><br>
-</td></tr></table>
-
-<P>Apache is a modular server. This implies that only the most basic
-functionality is included in the core server. Extended features are
-available through <A HREF="mod/index-bytype.html">modules</A> which
-can be loaded into Apache. By default, a <A
-HREF="mod/module-dict.html#Status">base</A> set of modules is
-included in the server at compile-time. If the server is compiled to
-use <A HREF="dso.html">dynamically loaded</A> modules, then modules
-can be compiled separately and added at any time using the <A
-HREF="mod/mod_so.html#loadmodule">LoadModule</A> directive.
-Otherwise, Apache must be recompiled to add or remove modules.
-Configuration directives may be included conditional on a presence of
-a particular module by enclosing them in an <A
-HREF="mod/core.html#ifmodule">&lt;IfModule&gt;</A> block.
-
-<P>To see which modules are currently compiled into the server,
-you can use the <CODE>-l</CODE> command line option.
-
-<hr>
-
-<H2><a name="scope">Scope of Directives</a></H2>
-
-<table border="1"><tr><td valign="top">
-<strong>Related Directives</strong><br><br>
-<A HREF="mod/core.html#directory">&lt;Directory&gt;</A><br>
-<A HREF="mod/core.html#directorymatch">&lt;DirectoryMatch&gt;</A><br>
-<A HREF="mod/core.html#files">&lt;Files&gt;</A><br>
-<A HREF="mod/core.html#filesmatch">&lt;FilesMatch&gt;</A><br>
-<A HREF="mod/core.html#location">&lt;Location&gt;</A><br>
-<A HREF="mod/core.html#locationmatch">&lt;LocationMatch&gt;</A><br>
-<a href="mod/core.html#virtualhost">&lt;VirtualHost&gt;</a><br>
-</td></tr></table>
-
-<P>Directives placed in the main configuration files apply to the entire
-server. If you wish to change the configuration for only a part of
-the server, you can scope your directives by placing them in
-<CODE><A HREF="mod/core.html#directory">&lt;Directory&gt;</A>,
-<A HREF="mod/core.html#directorymatch">&lt;DirectoryMatch&gt;</A>,
-<A HREF="mod/core.html#files">&lt;Files&gt;</A>,
-<A HREF="mod/core.html#filesmatch">&lt;FilesMatch&gt;</A>,
-<A HREF="mod/core.html#location">&lt;Location&gt;</A>,
-</CODE> and <CODE>
-<A HREF="mod/core.html#locationmatch">&lt;LocationMatch&gt;</A>
-</CODE>
-sections. These sections limit the application of the directives
-which they enclose to particular filesystem locations or URLs. They
-can also be nested, allowing for very fine grained configuration.
-
-<P>Apache has the capability to serve many different websites
-simultaneously. This is called <A HREF="vhosts/">Virtual Hosting</A>.
-Directives can also be scoped by placing them inside
-<CODE><A HREF="mod/core.html#virtualhost">&lt;VirtualHost&gt;</A></CODE>
-sections, so that they will only apply to requests for a particular
-website.
-
-<P>Although most directives can be placed in any of these sections,
-some directives do not make sense in some contexts. For example,
-directives controlling process creation can only be placed in the main
-server context. To find which directives can be placed in which
-sections, check the <A
-HREF="mod/directive-dict.html#Context">Context</A> of the directive.
-For further information, we provide details on <A
-HREF="sections.html">How Directory, Location and Files sections
-work</A>.
-
-<hr>
-
-<H2><a name="htaccess">.htaccess Files</a></H2>
-
-<table border="1"><tr><td valign="top">
-<strong>Related Directives</strong><br><br>
-<A HREF="mod/core.html#accessfilename">AccessFileName</A><br>
-<A HREF="mod/core.html#allowoverride">AllowOverride</A><br>
-</td></tr></table>
-
-<P>Apache allows for decentralized management of configuration via
-special files placed inside the web tree. The special files are
-usually called <CODE>.htaccess</CODE>, but any name can be specified
-in the <A HREF="mod/core.html#accessfilename"><CODE
->AccessFileName</CODE></A> directive. Directives placed in
-<CODE>.htaccess</CODE> files apply to the directory where you place
-the file, and all sub-directories. The <CODE>.htaccess</CODE> files
-follow the same syntax as the main configuration files. Since
-<CODE>.htaccess</CODE> files are read on every request, changes made
-in these files take immediate effect.
-
-<P>To find which directives can be placed in <CODE>.htaccess</CODE>
-files, check the <A HREF="mod/directive-dict.html#Context">Context</A>
-of the directive. The server administrator further controls what
-directives may be placed in <CODE>.htaccess</CODE> files by
-configuring the <A
-HREF="mod/core.html#allowoverride"><CODE>AllowOverride</CODE></A>
-directive in the main configuration files.
-
-<hr>
-
-<H2><a name="logs">Log files</a></H2>
-<!-- This section should be moved to its own file -->
-<H3>security warning</H3>
-Anyone who can write to the directory where Apache is writing a
-log file can almost certainly gain access to the uid that the server is
-started as, which is normally root. Do <EM>NOT</EM> give people write
-access to the directory the logs are stored in without being aware of
-the consequences; see the <A HREF="misc/security_tips.html">security tips</A>
-document for details.
-
-<H3>pid file</H3>
-
-<P>On startup, Apache saves the process id of the parent httpd process to
-the file <CODE>logs/httpd.pid</CODE>. This filename can be changed
-with the <A HREF="mod/core.html#pidfile">PidFile</A> directive. The
-process-id is for use by the administrator in restarting and
-terminating the daemon: on Unix, a HUP or USR1 signal causes the
-daemon to re-read its configuration files and a TERM signal causes it
-to die gracefully; on Windows, use the -k command line option instead.
-For more information see the <A HREF="stopping.html">Stopping and
-Restarting</A> page.
-
-<P>
-If the process dies (or is killed) abnormally, then it will be necessary to
-kill the children httpd processes.
-
-<H3>Error log</H3>
-
-<P>The server will log error messages to a log file, by default
-<CODE>logs/error_log</CODE> on Unix or <CODE>logs/error.log</CODE> on
-Windows and OS/2. The filename can be set using the <A
-HREF="mod/core.html#errorlog">ErrorLog</A> directive; different error
-logs can be set for different <A
-HREF="mod/core.html#virtualhost">virtual hosts</A>.
-
-<H3>Transfer log</H3>
-
-<P>The server will typically log each request to a transfer file, by
-default <CODE>logs/access_log</CODE> on Unix or
-<CODE>logs/access.log</CODE> on Windows and OS/2. The filename can be
-set using a <A HREF="mod/mod_log_config.html#customlog">CustomLog</A>
-directive; different transfer logs can be set for different <A
-HREF="mod/core.html#virtualhost">virtual hosts</A>.
-
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
588 docs/manual/content-negotiation.html.en
View
@@ -1,588 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
-<HEAD>
-<TITLE>Apache Content Negotiation</TITLE>
-</HEAD>
-
-<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
-<BODY
- BGCOLOR="#FFFFFF"
- TEXT="#000000"
- LINK="#0000FF"
- VLINK="#000080"
- ALINK="#FF0000"
->
-<!--#include virtual="header.html" -->
-<H1 ALIGN="CENTER">Content Negotiation</H1>
-
-<P>
-Apache's support for content negotiation has been updated to meet the
-HTTP/1.1 specification. It can choose the best representation of a
-resource based on the browser-supplied preferences for media type,
-languages, character set and encoding. It is also implements a
-couple of features to give more intelligent handling of requests from
-browsers which send incomplete negotiation information. <P>
-
-Content negotiation is provided by the
-<A HREF="mod/mod_negotiation.html">mod_negotiation</A> module,
-which is compiled in by default.
-
-<HR>
-
-<H2>About Content Negotiation</H2>
-
-<P>
-A resource may be available in several different representations. For
-example, it might be available in different languages or different
-media types, or a combination. One way of selecting the most
-appropriate choice is to give the user an index page, and let them
-select. However it is often possible for the server to choose
-automatically. This works because browsers can send as part of each
-request information about what representations they prefer. For
-example, a browser could indicate that it would like to see
-information in French, if possible, else English will do. Browsers
-indicate their preferences by headers in the request. To request only
-French representations, the browser would send
-
-<PRE>
- Accept-Language: fr
-</PRE>
-
-<P>
-Note that this preference will only be applied when there is a choice
-of representations and they vary by language.
-<P>
-
-As an example of a more complex request, this browser has been
-configured to accept French and English, but prefer French, and to
-accept various media types, preferring HTML over plain text or other
-text types, and preferring GIF or JPEG over other media types, but also
-allowing any other media type as a last resort:
-
-<PRE>
- Accept-Language: fr; q=1.0, en; q=0.5
- Accept: text/html; q=1.0, text/*; q=0.8, image/gif; q=0.6,
- image/jpeg; q=0.6, image/*; q=0.5, */*; q=0.1
-</PRE>
-
-Apache 1.2 supports 'server driven' content negotiation, as defined in
-the HTTP/1.1 specification. It fully supports the Accept,
-Accept-Language, Accept-Charset and Accept-Encoding request headers.
-Apache 1.3.4 also supports 'transparent' content negotiation, which is
-an experimental negotiation protocol defined in RFC 2295 and RFC 2296.
-It does not offer support for 'feature negotiation' as defined in
-these RFCs.
-<P>
-
-A <STRONG>resource</STRONG> is a conceptual entity identified by a URI
-(RFC 2396). An HTTP server like Apache provides access to
-<STRONG>representations</STRONG> of the resource(s) within its namespace,
-with each representation in the form of a sequence of bytes with a
-defined media type, character set, encoding, etc. Each resource may be
-associated with zero, one, or more than one representation
-at any given time. If multiple representations are available,
-the resource is referred to as <STRONG>negotiable</STRONG> and each of its
-representations is termed a <STRONG>variant</STRONG>. The ways in which the
-variants for a negotiable resource vary are called the
-<STRONG>dimensions</STRONG> of negotiation.
-
-<H2>Negotiation in Apache</H2>
-
-<P>
-In order to negotiate a resource, the server needs to be given
-information about each of the variants. This is done in one of two
-ways:
-
-<UL>
- <LI> Using a type map (<EM>i.e.</EM>, a <CODE>*.var</CODE> file) which
- names the files containing the variants explicitly, or
- <LI> Using a 'MultiViews' search, where the server does an implicit
- filename pattern match and chooses from among the results.
-</UL>
-
-<H3>Using a type-map file</H3>
-
-<P>
-A type map is a document which is associated with the handler
-named <CODE>type-map</CODE> (or, for backwards-compatibility with
-older Apache configurations, the mime type
-<CODE>application/x-type-map</CODE>). Note that to use this feature,
-you must have a handler set in the configuration that defines a
-file suffix as <CODE>type-map</CODE>; this is best done with a
-
-<PRE>
- AddHandler type-map var
-</PRE>
-
-in the server configuration file. See the comments in the sample config
-file for more details. <P>
-
-Type map files have an entry for each available variant; these entries
-consist of contiguous HTTP-format header lines. Entries for
-different variants are separated by blank lines. Blank lines are
-illegal within an entry. It is conventional to begin a map file with
-an entry for the combined entity as a whole (although this
-is not required, and if present will be ignored). An example
-map file is:
-
-<PRE>
- URI: foo
-
- URI: foo.en.html
- Content-type: text/html
- Content-language: en
-
- URI: foo.fr.de.html
- Content-type: text/html;charset=iso-8859-2
- Content-language: fr, de
-</PRE>
-
-If the variants have different source qualities, that may be indicated
-by the "qs" parameter to the media type, as in this picture (available
-as jpeg, gif, or ASCII-art):
-
-<PRE>
- URI: foo
-
- URI: foo.jpeg
- Content-type: image/jpeg; qs=0.8
-
- URI: foo.gif
- Content-type: image/gif; qs=0.5
-
- URI: foo.txt
- Content-type: text/plain; qs=0.01
-</PRE>
-<P>
-
-qs values can vary in the range 0.000 to 1.000. Note that any variant with
-a qs value of 0.000 will never be chosen. Variants with no 'qs'
-parameter value are given a qs factor of 1.0. The qs parameter indicates
-the relative 'quality' of this variant compared to the other available
-variants, independent of the client's capabilities. For example, a jpeg
-file is usually of higher source quality than an ascii file if it is
-attempting to represent a photograph. However, if the resource being
-represented is an original ascii art, then an ascii representation would
-have a higher source quality than a jpeg representation. A qs value
-is therefore specific to a given variant depending on the nature of
-the resource it represents.
-
-<P>
-The full list of headers recognized is:
-
-<DL>
- <DT> <CODE>URI:</CODE>
- <DD> uri of the file containing the variant (of the given media
- type, encoded with the given content encoding). These are
- interpreted as URLs relative to the map file; they must be on
- the same server (!), and they must refer to files to which the
- client would be granted access if they were to be requested
- directly.
- <DT> <CODE>Content-Type:</CODE>
- <DD> media type --- charset, level and "qs" parameters may be given. These
- are often referred to as MIME types; typical media types are
- <CODE>image/gif</CODE>, <CODE>text/plain</CODE>, or
- <CODE>text/html;&nbsp;level=3</CODE>.
- <DT> <CODE>Content-Language:</CODE>
- <DD> The languages of the variant, specified as an Internet standard
- language tag from RFC 1766 (<EM>e.g.</EM>, <CODE>en</CODE> for English,
- <CODE>kr</CODE> for Korean, <EM>etc.</EM>).
- <DT> <CODE>Content-Encoding:</CODE>
- <DD> If the file is compressed, or otherwise encoded, rather than
- containing the actual raw data, this says how that was done.
- Apache only recognizes encodings that are defined by an
- <A HREF="mod/mod_mime.html#addencoding">AddEncoding</A> directive.
- This normally includes the encodings <CODE>x-compress</CODE>
- for compress'd files, and <CODE>x-gzip</CODE> for gzip'd files.
- The <CODE>x-</CODE> prefix is ignored for encoding comparisons.
- <DT> <CODE>Content-Length:</CODE>
- <DD> The size of the file. Specifying content
- lengths in the type-map allows the server to compare file sizes
- without checking the actual files.
- <DT> <CODE>Description:</CODE>
- <DD> A human-readable textual description of the variant. If Apache cannot
- find any appropriate variant to return, it will return an error
- response which lists all available variants instead. Such a variant
- list will include the human-readable variant descriptions.
-</DL>
-
-<H3>Multiviews</H3>
-
-<P>
-<CODE>MultiViews</CODE> is a per-directory option, meaning it can be set with
-an <CODE>Options</CODE> directive within a <CODE>&lt;Directory&gt;</CODE>,
-<CODE>&lt;Location&gt;</CODE> or <CODE>&lt;Files&gt;</CODE>
-section in <CODE>access.conf</CODE>, or (if <CODE>AllowOverride</CODE>
-is properly set) in <CODE>.htaccess</CODE> files. Note that
-<CODE>Options All</CODE> does not set <CODE>MultiViews</CODE>; you
-have to ask for it by name.
-
-<P>
-The effect of <CODE>MultiViews</CODE> is as follows: if the server
-receives a request for <CODE>/some/dir/foo</CODE>, if
-<CODE>/some/dir</CODE> has <CODE>MultiViews</CODE> enabled, and
-<CODE>/some/dir/foo</CODE> does <EM>not</EM> exist, then the server reads the
-directory looking for files named foo.*, and effectively fakes up a
-type map which names all those files, assigning them the same media
-types and content-encodings it would have if the client had asked for
-one of them by name. It then chooses the best match to the client's
-requirements.
-
-<P>
-<CODE>MultiViews</CODE> may also apply to searches for the file named by the
-<CODE>DirectoryIndex</CODE> directive, if the server is trying to
-index a directory. If the configuration files specify
-
-<PRE>
- DirectoryIndex index
-</PRE>
-
-then the server will arbitrate between <CODE>index.html</CODE>
-and <CODE>index.html3</CODE> if both are present. If neither are
-present, and <CODE>index.cgi</CODE> is there, the server will run it.
-
-<P>
-If one of the files found when reading the directive is a CGI script,
-it's not obvious what should happen. The code gives that case
-special treatment --- if the request was a POST, or a GET with
-QUERY_ARGS or PATH_INFO, the script is given an extremely high quality
-rating, and generally invoked; otherwise it is given an extremely low
-quality rating, which generally causes one of the other views (if any)
-to be retrieved.
-
-<H2>The Negotiation Methods</H2>
-
-After Apache has obtained a list of the variants for a given resource,
-either from a type-map file or from the filenames in the directory, it
-invokes one of two methods to decide on the 'best' variant to
-return, if any. It is not necessary to know any of the details of how
-negotiation actually takes place in order to use Apache's content
-negotiation features. However the rest of this document explains the
-methods used for those interested.
-<P>
-
-There are two negotiation methods:
-
-<OL>
-
-<LI><STRONG>Server driven negotiation with the Apache
-algorithm</STRONG> is used in the normal case. The Apache algorithm is
-explained in more detail below. When this algorithm is used, Apache
-can sometimes 'fiddle' the quality factor of a particular dimension to
-achieve a better result. The ways Apache can fiddle quality factors is
-explained in more detail below.
-
-<LI><STRONG>Transparent content negotiation</STRONG> is used when the
-browser specifically requests this through the mechanism defined in RFC
-2295. This negotiation method gives the browser full control over
-deciding on the 'best' variant, the result is therefore dependent on
-the specific algorithms used by the browser. As part of the
-transparent negotiation process, the browser can ask Apache to run the
-'remote variant selection algorithm' defined in RFC 2296. </UL>
-
-
-<H3>Dimensions of Negotiation</H3>
-
-<TABLE>
-<TR valign="top">
-<TH>Dimension
-<TH>Notes
-<TR valign="top">
-<TD>Media Type
-<TD>Browser indicates preferences with the Accept header field. Each item
-can have an associated quality factor. Variant description can also
-have a quality factor (the "qs" parameter).
-<TR valign="top">
-<TD>Language
-<TD>Browser indicates preferences with the Accept-Language header field.
-Each item can have a quality factor. Variants can be associated with none, one
-or more than one language.
-<TR valign="top">
-<TD>Encoding
-<TD>Browser indicates preference with the Accept-Encoding header field.
-Each item can have a quality factor.
-<TR valign="top">
-<TD>Charset
-<TD>Browser indicates preference with the Accept-Charset header field.
-Each item can have a quality factor.
-Variants can indicate a charset as a parameter of the media type.
-</TABLE>
-
-<H3>Apache Negotiation Algorithm</H3>
-
-<P>
-Apache can use the following algorithm to select the 'best' variant
-(if any) to return to the browser. This algorithm is not
-further configurable. It operates as follows:
-
-<OL>
-<LI>First, for each dimension of the negotiation, check the appropriate
-<EM>Accept*</EM> header field and assign a quality to each
-variant. If the <EM>Accept*</EM> header for any dimension implies that this
-variant is not acceptable, eliminate it. If no variants remain, go
-to step 4.
-
-<LI>Select the 'best' variant by a process of elimination. Each of the
-following tests is applied in order. Any variants not selected at each
-test are eliminated. After each test, if only one variant remains,
-select it as the best match and proceed to step 3. If more than one
-variant remains, move on to the next test.
-
-<OL>
-<LI>Multiply the quality factor from the Accept header with the
- quality-of-source factor for this variant's media type, and select
- the variants with the highest value.
-
-<LI>Select the variants with the highest language quality factor.
-
-<LI>Select the variants with the best language match, using either the
- order of languages in the Accept-Language header (if present), or else
- else the order of languages in the <CODE>LanguagePriority</CODE>
- directive (if present).
-
-<LI>Select the variants with the highest 'level' media parameter
- (used to give the version of text/html media types).
-
-<LI>Select variants with the best charset media parameters,
- as given on the Accept-Charset header line. Charset ISO-8859-1
- is acceptable unless explicitly excluded. Variants with a
- <CODE>text/*</CODE> media type but not explicitly associated
- with a particular charset are assumed to be in ISO-8859-1.
-
-<LI>Select those variants which have associated
- charset media parameters that are <EM>not</EM> ISO-8859-1.
- If there are no such variants, select all variants instead.
-
-<LI>Select the variants with the best encoding. If there are
- variants with an encoding that is acceptable to the user-agent,
- select only these variants. Otherwise if there is a mix of encoded
- and non-encoded variants, select only the unencoded variants.
- If either all variants are encoded or all variants are not encoded,
- select all variants.
-
-<LI>Select the variants with the smallest content length.
-
-<LI>Select the first variant of those remaining. This will be either the
- first listed in the type-map file, or when variants are read from
- the directory, the one whose file name comes first when sorted using
- ASCII code order.
-
-</OL>
-
-<LI>The algorithm has now selected one 'best' variant, so return
- it as the response. The HTTP response header Vary is set to indicate the
- dimensions of negotiation (browsers and caches can use this
- information when caching the resource). End.
-
-<LI>To get here means no variant was selected (because none are acceptable
- to the browser). Return a 406 status (meaning "No acceptable representation")
- with a response body consisting of an HTML document listing the
- available variants. Also set the HTTP Vary header to indicate the
- dimensions of variance.
-
-</OL>
-
-<H2><A NAME="better">Fiddling with Quality Values</A></H2>
-
-<P>
-Apache sometimes changes the quality values from what would be
-expected by a strict interpretation of the Apache negotiation
-algorithm above. This is to get a better result from the algorithm for
-browsers which do not send full or accurate information. Some of the
-most popular browsers send Accept header information which would
-otherwise result in the selection of the wrong variant in many
-cases. If a browser sends full and correct information these fiddles
-will not be applied.
-<P>
-
-<H3>Media Types and Wildcards</H3>
-
-<P>
-The Accept: request header indicates preferences for media types. It
-can also include 'wildcard' media types, such as "image/*" or "*/*"
-where the * matches any string. So a request including:
-<PRE>
- Accept: image/*, */*
-</PRE>
-
-would indicate that any type starting "image/" is acceptable,
-as is any other type (so the first "image/*" is redundant). Some
-browsers routinely send wildcards in addition to explicit types they
-can handle. For example:
-<PRE>
- Accept: text/html, text/plain, image/gif, image/jpeg, */*
-</PRE>
-
-The intention of this is to indicate that the explicitly
-listed types are preferred, but if a different representation is
-available, that is ok too. However under the basic algorithm, as given
-above, the */* wildcard has exactly equal preference to all the other
-types, so they are not being preferred. The browser should really have
-sent a request with a lower quality (preference) value for *.*, such
-as:
-<PRE>
- Accept: text/html, text/plain, image/gif, image/jpeg, */*; q=0.01
-</PRE>
-
-The explicit types have no quality factor, so they default to a
-preference of 1.0 (the highest). The wildcard */* is given
-a low preference of 0.01, so other types will only be returned if
-no variant matches an explicitly listed type.
-<P>
-
-If the Accept: header contains <EM>no</EM> q factors at all, Apache sets
-the q value of "*/*", if present, to 0.01 to emulate the desired
-behavior. It also sets the q value of wildcards of the format
-"type/*" to 0.02 (so these are preferred over matches against
-"*/*". If any media type on the Accept: header contains a q factor,
-these special values are <EM>not</EM> applied, so requests from browsers
-which send the correct information to start with work as expected.
-
-<H3>Variants with no Language</H3>
-
-<P>
-If some of the variants for a particular resource have a language
-attribute, and some do not, those variants with no language
-are given a very low language quality factor of 0.001.<P>
-
-The reason for setting this language quality factor for
-variant with no language to a very low value is to allow
-for a default variant which can be supplied if none of the
-other variants match the browser's language preferences.
-
-For example, consider the situation with three variants:
-
-<UL>
-<LI>foo.en.html, language en
-<LI>foo.fr.html, language en
-<LI>foo.html, no language
-</UL>
-
-<P>
-The meaning of a variant with no language is that it is
-always acceptable to the browser. If the request Accept-Language
-header includes either en or fr (or both) one of foo.en.html
-or foo.fr.html will be returned. If the browser does not list
-either en or fr as acceptable, foo.html will be returned instead.
-
-<H2>Extensions to Transparent Content Negotiation</H2>
-
-Apache extends the transparent content negotiation protocol (RFC 2295)
-as follows. A new <CODE> {encoding ..}</CODE> element is used in
-variant lists to label variants which are available with a specific
-content-encoding only. The implementation of the
-RVSA/1.0 algorithm (RFC 2296) is extended to recognize encoded
-variants in the list, and to use them as candidate variants whenever
-their encodings are acceptable according to the Accept-Encoding
-request header. The RVSA/1.0 implementation does not round computed
-quality factors to 5 decimal places before choosing the best variant.
-
-<H2>Note on hyperlinks and naming conventions</H2>
-
-<P>
-If you are using language negotiation you can choose between
-different naming conventions, because files can have more than one
-extension, and the order of the extensions is normally irrelevant
-(see <A HREF="mod/mod_mime.html">mod_mime</A> documentation for details).
-<P>
-A typical file has a MIME-type extension (<EM>e.g.</EM>, <SAMP>html</SAMP>),
-maybe an encoding extension (<EM>e.g.</EM>, <SAMP>gz</SAMP>), and of course a
-language extension (<EM>e.g.</EM>, <SAMP>en</SAMP>) when we have different
-language variants of this file.
-
-<P>
-Examples:
-<UL>
-<LI>foo.en.html
-<LI>foo.html.en
-<LI>foo.en.html.gz
-</UL>
-
-<P>
-Here some more examples of filenames together with valid and invalid
-hyperlinks:
-</P>
-
-<TABLE BORDER=1 CELLPADDING=8 CELLSPACING=0>
-<TR>
- <TH>Filename</TH>
- <TH>Valid hyperlink</TH>
- <TH>Invalid hyperlink</TH>
-</TR>
-<TR>
- <TD><EM>foo.html.en</EM></TD>
- <TD>foo<BR>
- foo.html</TD>
- <TD>-</TD>
-</TR>
-<TR>
- <TD><EM>foo.en.html</EM></TD>
- <TD>foo</TD>
- <TD>foo.html</TD>
-</TR>
-<TR>
- <TD><EM>foo.html.en.gz</EM></TD>
- <TD>foo<BR>
- foo.html</TD>
- <TD>foo.gz<BR>
- foo.html.gz</TD>
-</TR>
-<TR>
- <TD><EM>foo.en.html.gz</EM></TD>
- <TD>foo</TD>
- <TD>foo.html<BR>
- foo.html.gz<BR>
- foo.gz</TD>
-</TR>
-<TR>
- <TD><EM>foo.gz.html.en</EM></TD>
- <TD>foo<BR>
- foo.gz<BR>
- foo.gz.html</TD>
- <TD>foo.html</TD>
-</TR>
-<TR>
- <TD><EM>foo.html.gz.en</EM></TD>
- <TD>foo<BR>
- foo.html<BR>
- foo.html.gz</TD>
- <TD>foo.gz</TD>
-</TR>
-</TABLE>
-
-<P>
-Looking at the table above you will notice that it is always possible to
-use the name without any extensions in an hyperlink (<EM>e.g.</EM>, <SAMP>foo</SAMP>).
-The advantage is that you can hide the actual type of a
-document rsp. file and can change it later, <EM>e.g.</EM>, from <SAMP>html</SAMP>
-to <SAMP>shtml</SAMP> or <SAMP>cgi</SAMP> without changing any
-hyperlink references.
-
-<P>
-If you want to continue to use a MIME-type in your hyperlinks (<EM>e.g.</EM>
-<SAMP>foo.html</SAMP>) the language extension (including an encoding extension
-if there is one) must be on the right hand side of the MIME-type extension
-(<EM>e.g.</EM>, <SAMP>foo.html.en</SAMP>).
-
-
-<H2>Note on Caching</H2>
-
-<P>
-When a cache stores a representation, it associates it with the request URL.
-The next time that URL is requested, the cache can use the stored
-representation. But, if the resource is negotiable at the server,
-this might result in only the first requested variant being cached and
-subsequent cache hits might return the wrong response. To prevent this,
-Apache normally marks all responses that are returned after content negotiation
-as non-cacheable by HTTP/1.0 clients. Apache also supports the HTTP/1.1
-protocol features to allow caching of negotiated responses. <P>
-
-For requests which come from a HTTP/1.0 compliant client (either a
-browser or a cache), the directive <TT>CacheNegotiatedDocs</TT> can be
-used to allow caching of responses which were subject to negotiation.
-This directive can be given in the server config or virtual host, and
-takes no arguments. It has no effect on requests from HTTP/1.1 clients.
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
177 docs/manual/custom-error.html.en
View
@@ -1,177 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
-<HEAD>
-<TITLE>Custom error responses</TITLE>
-</HEAD>
-
-<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
-<BODY
- BGCOLOR="#FFFFFF"
- TEXT="#000000"
- LINK="#0000FF"
- VLINK="#000080"
- ALINK="#FF0000"
->
-<!--#include virtual="header.html" -->
-<H1 ALIGN="CENTER">Custom error responses</H1>
-
-<DL>
-
-<DT>Purpose
-
- <DD>Additional functionality. Allows webmasters to configure the response of
- Apache to some error or problem.
-
- <P>Customizable responses can be defined to be activated in the
- event of a server detected error or problem.
-
- <P>e.g. if a script crashes and produces a "500 Server Error"
- response, then this response can be replaced with either some
- friendlier text or by a redirection to another URL (local or
- external).
- <P>
-
-<DT>Old behavior
-
- <DD>NCSA httpd 1.3 would return some boring old error/problem message
- which would often be meaningless to the user, and would provide no
- means of logging the symptoms which caused it.<BR>
-
- <P>
-
-<DT>New behavior
-
- <DD>The server can be asked to;
- <OL>
- <LI>Display some other text, instead of the NCSA hard coded messages, or
- <LI>redirect to a local URL, or
- <LI>redirect to an external URL.
- </OL>
-
- <P>Redirecting to another URL can be useful, but only if some information
- can be passed which can then be used to explain and/or log the
- error/problem
- more clearly.
-
- <P>To achieve this, Apache will define new CGI-like environment
- variables, <EM>e.g.</EM>
-
- <BLOCKQUOTE><CODE>
-REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/x-xbitmap, image/jpeg <BR>
-REDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2 (X11; I; HP-UX A.09.05 9000/712) <BR>
-REDIRECT_PATH=.:/bin:/usr/local/bin:/etc <BR>
-REDIRECT_QUERY_STRING= <BR>
-REDIRECT_REMOTE_ADDR=121.345.78.123 <BR>
-REDIRECT_REMOTE_HOST=ooh.ahhh.com <BR>
-REDIRECT_SERVER_NAME=crash.bang.edu <BR>
-REDIRECT_SERVER_PORT=80 <BR>
-REDIRECT_SERVER_SOFTWARE=Apache/0.8.15 <BR>
-REDIRECT_URL=/cgi-bin/buggy.pl <BR>
- </CODE></BLOCKQUOTE>
-
- <P>note the <CODE>REDIRECT_</CODE> prefix.
-
- <P>At least <CODE>REDIRECT_URL</CODE> and <CODE>REDIRECT_QUERY_STRING</CODE>
- will
- be passed to the new URL (assuming it's a cgi-script or a cgi-include).
- The
- other variables will exist only if they existed prior to the
- error/problem.
- <STRONG>None</STRONG> of these will be set if your ErrorDocument is an
- <EM>external</EM> redirect (<EM>i.e.</EM>, anything starting with a
- scheme name
- like <CODE>http:</CODE>, even if it refers to the same host as the
- server).<P>
-
-<DT>Configuration
-
- <DD> Use of "ErrorDocument" is enabled for .htaccess files when the
- <A HREF="mod/core.html#allowoverride">"FileInfo" override</A> is
- allowed.
-
- <P>Here are some examples...
-
- <BLOCKQUOTE><CODE>
-ErrorDocument 500 /cgi-bin/crash-recover <BR>
-ErrorDocument 500 "Sorry, our script crashed. Oh dear<BR>
-ErrorDocument 500 http://xxx/ <BR>
-ErrorDocument 404 /Lame_excuses/not_found.html <BR>
-ErrorDocument 401 /Subscription/how_to_subscribe.html
- </CODE></BLOCKQUOTE>
-
- <P>The syntax is,
-
- <P><CODE><A HREF="mod/core.html#errordocument">ErrorDocument</A></CODE>
-&lt;3-digit-code&gt; action
-
- <P>where the action can be,
-
- <OL>
- <LI>Text to be displayed. Prefix the text with a quote (&quot;). Whatever
- follows the quote is displayed. <EM>Note: the (&quot;) prefix isn't
- displayed.</EM>
-
- <LI>An external URL to redirect to.
-
- <LI>A local URL to redirect to.
-
- </OL>
-</DL>
-
-<P><HR><P>
-
-<H2>Custom error responses and redirects</H2>
-
-<DL>
-
-<DT>Purpose
-
- <DD>Apache's behavior to redirected URLs has been modified so that additional
- environment variables are available to a script/server-include.<P>
-
-<DT>Old behavior
-
- <DD>Standard CGI vars were made available to a script which has been
- redirected to. No indication of where the redirection came from was
- provided.
-
- <P>
-
-<DT>New behavior
- <DD>
-
-A new batch of environment variables will be initialized for use by a
-script which has been redirected to. Each new variable will have the
-prefix <CODE>REDIRECT_</CODE>. <CODE>REDIRECT_</CODE> environment
-variables are created from the CGI environment variables which existed
-prior to the redirect, they are renamed with a <CODE>REDIRECT_</CODE>
-prefix, <EM>i.e.</EM>, <CODE>HTTP_USER_AGENT</CODE> becomes
-<CODE>REDIRECT_HTTP_USER_AGENT</CODE>. In addition to these new
-variables, Apache will define <CODE>REDIRECT_URL</CODE> and
-<CODE>REDIRECT_STATUS</CODE> to help the script trace its origin.
-Both the original URL and the URL being redirected to can be logged in
-the access log.
-
-</DL>
-<P>
-If the ErrorDocument specifies a local redirect to a CGI script, the script
-should include a "<SAMP>Status:</SAMP>" header field in its output
-in order to ensure the propagation all the way back to the client
-of the error condition that caused it to be invoked. For instance, a Perl
-ErrorDocument script might include the following:
-</P>
-<PRE>
- :
- print "Content-type: text/html\n";
- printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"};
- :
-</PRE>
-<P>
-If the script is dedicated to handling a particular error condition, such as
-<SAMP>404&nbsp;Not&nbsp;Found</SAMP>, it can use the specific code and
-error text instead.
-</P>
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
1,153 docs/manual/developer/API.html
View
@@ -1,1153 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML><HEAD>
-<TITLE>Apache API notes</TITLE>
-</HEAD>
-<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
-<BODY
- BGCOLOR="#FFFFFF"
- TEXT="#000000"
- LINK="#0000FF"
- VLINK="#000080"
- ALINK="#FF0000"
->
-<!--#include virtual="header.html" -->
-<H1 ALIGN="CENTER">Apache API notes</H1>
-
-These are some notes on the Apache API and the data structures you
-have to deal with, <EM>etc.</EM> They are not yet nearly complete, but
-hopefully, they will help you get your bearings. Keep in mind that
-the API is still subject to change as we gain experience with it.
-(See the TODO file for what <EM>might</EM> be coming). However,
-it will be easy to adapt modules to any changes that are made.
-(We have more modules to adapt than you do).
-<P>
-
-A few notes on general pedagogical style here. In the interest of
-conciseness, all structure declarations here are incomplete --- the
-real ones have more slots that I'm not telling you about. For the
-most part, these are reserved to one component of the server core or
-another, and should be altered by modules with caution. However, in
-some cases, they really are things I just haven't gotten around to
-yet. Welcome to the bleeding edge.<P>
-
-Finally, here's an outline, to give you some bare idea of what's
-coming up, and in what order:
-
-<UL>
-<LI> <A HREF="#basics">Basic concepts.</A>
-<MENU>
- <LI> <A HREF="#HMR">Handlers, Modules, and Requests</A>
- <LI> <A HREF="#moduletour">A brief tour of a module</A>
-</MENU>
-<LI> <A HREF="#handlers">How handlers work</A>
-<MENU>
- <LI> <A HREF="#req_tour">A brief tour of the <CODE>request_rec</CODE></A>
- <LI> <A HREF="#req_orig">Where request_rec structures come from</A>
- <LI> <A HREF="#req_return">Handling requests, declining, and returning error
- codes</A>
- <LI> <A HREF="#resp_handlers">Special considerations for response handlers</A>
- <LI> <A HREF="#auth_handlers">Special considerations for authentication
- handlers</A>
- <LI> <A HREF="#log_handlers">Special considerations for logging handlers</A>
-</MENU>
-<LI> <A HREF="#pools">Resource allocation and resource pools</A>
-<LI> <A HREF="#config">Configuration, commands and the like</A>
-<MENU>
- <LI> <A HREF="#per-dir">Per-directory configuration structures</A>
- <LI> <A HREF="#commands">Command handling</A>
- <LI> <A HREF="#servconf">Side notes --- per-server configuration,
- virtual servers, <EM>etc</EM>.</A>
-</MENU>
-</UL>
-
-<H2><A NAME="basics">Basic concepts.</A></H2>
-
-We begin with an overview of the basic concepts behind the
-API, and how they are manifested in the code.
-
-<H3><A NAME="HMR">Handlers, Modules, and Requests</A></H3>
-
-Apache breaks down request handling into a series of steps, more or
-less the same way the Netscape server API does (although this API has
-a few more stages than NetSite does, as hooks for stuff I thought
-might be useful in the future). These are:
-
-<UL>
- <LI> URI -&gt; Filename translation
- <LI> Auth ID checking [is the user who they say they are?]
- <LI> Auth access checking [is the user authorized <EM>here</EM>?]
- <LI> Access checking other than auth
- <LI> Determining MIME type of the object requested
- <LI> `Fixups' --- there aren't any of these yet, but the phase is
- intended as a hook for possible extensions like
- <CODE>SetEnv</CODE>, which don't really fit well elsewhere.
- <LI> Actually sending a response back to the client.
- <LI> Logging the request
-</UL>
-
-These phases are handled by looking at each of a succession of
-<EM>modules</EM>, looking to see if each of them has a handler for the
-phase, and attempting invoking it if so. The handler can typically do
-one of three things:
-
-<UL>
- <LI> <EM>Handle</EM> the request, and indicate that it has done so
- by returning the magic constant <CODE>OK</CODE>.
- <LI> <EM>Decline</EM> to handle the request, by returning the magic
- integer constant <CODE>DECLINED</CODE>. In this case, the
- server behaves in all respects as if the handler simply hadn't
- been there.
- <LI> Signal an error, by returning one of the HTTP error codes.
- This terminates normal handling of the request, although an
- ErrorDocument may be invoked to try to mop up, and it will be
- logged in any case.
-</UL>
-
-Most phases are terminated by the first module that handles them;
-however, for logging, `fixups', and non-access authentication
-checking, all handlers always run (barring an error). Also, the
-response phase is unique in that modules may declare multiple handlers
-for it, via a dispatch table keyed on the MIME type of the requested
-object. Modules may declare a response-phase handler which can handle
-<EM>any</EM> request, by giving it the key <CODE>*/*</CODE> (<EM>i.e.</EM>, a
-wildcard MIME type specification). However, wildcard handlers are
-only invoked if the server has already tried and failed to find a more
-specific response handler for the MIME type of the requested object
-(either none existed, or they all declined).<P>
-
-The handlers themselves are functions of one argument (a
-<CODE>request_rec</CODE> structure. vide infra), which returns an
-integer, as above.<P>
-
-<H3><A NAME="moduletour">A brief tour of a module</A></H3>
-
-At this point, we need to explain the structure of a module. Our
-candidate will be one of the messier ones, the CGI module --- this
-handles both CGI scripts and the <CODE>ScriptAlias</CODE> config file
-command. It's actually a great deal more complicated than most
-modules, but if we're going to have only one example, it might as well
-be the one with its fingers in every place.<P>
-
-Let's begin with handlers. In order to handle the CGI scripts, the
-module declares a response handler for them. Because of
-<CODE>ScriptAlias</CODE>, it also has handlers for the name
-translation phase (to recognize <CODE>ScriptAlias</CODE>ed URIs), the
-type-checking phase (any <CODE>ScriptAlias</CODE>ed request is typed
-as a CGI script).<P>
-
-The module needs to maintain some per (virtual)
-server information, namely, the <CODE>ScriptAlias</CODE>es in effect;
-the module structure therefore contains pointers to a functions which
-builds these structures, and to another which combines two of them (in
-case the main server and a virtual server both have
-<CODE>ScriptAlias</CODE>es declared).<P>
-
-Finally, this module contains code to handle the
-<CODE>ScriptAlias</CODE> command itself. This particular module only
-declares one command, but there could be more, so modules have
-<EM>command tables</EM> which declare their commands, and describe
-where they are permitted, and how they are to be invoked. <P>
-
-A final note on the declared types of the arguments of some of these
-commands: a <CODE>pool</CODE> is a pointer to a <EM>resource pool</EM>
-structure; these are used by the server to keep track of the memory
-which has been allocated, files opened, <EM>etc.</EM>, either to service a
-particular request, or to handle the process of configuring itself.
-That way, when the request is over (or, for the configuration pool,
-when the server is restarting), the memory can be freed, and the files
-closed, <EM>en masse</EM>, without anyone having to write explicit code to
-track them all down and dispose of them. Also, a
-<CODE>cmd_parms</CODE> structure contains various information about
-the config file being read, and other status information, which is
-sometimes of use to the function which processes a config-file command
-(such as <CODE>ScriptAlias</CODE>).
-
-With no further ado, the module itself:
-
-<PRE>
-/* Declarations of handlers. */
-
-int translate_scriptalias (request_rec *);
-int type_scriptalias (request_rec *);
-int cgi_handler (request_rec *);
-
-/* Subsidiary dispatch table for response-phase handlers, by MIME type */
-
-handler_rec cgi_handlers[] = {
-{ "application/x-httpd-cgi", cgi_handler },
-{ NULL }
-};
-
-/* Declarations of routines to manipulate the module's configuration
- * info. Note that these are returned, and passed in, as void *'s;
- * the server core keeps track of them, but it doesn't, and can't,
- * know their internal structure.
- */
-
-void *make_cgi_server_config (pool *);
-void *merge_cgi_server_config (pool *, void *, void *);
-
-/* Declarations of routines to handle config-file commands */
-
-extern char *script_alias(cmd_parms *, void *per_dir_config, char *fake,
- char *real);
-
-command_rec cgi_cmds[] = {
-{ "ScriptAlias", script_alias, NULL, RSRC_CONF, TAKE2,
- "a fakename and a realname"},
-{ NULL }
-};
-
-module cgi_module = {
- STANDARD_MODULE_STUFF,
- NULL, /* initializer */
- NULL, /* dir config creator */
- NULL, /* dir merger --- default is to override */
- make_cgi_server_config, /* server config */
- merge_cgi_server_config, /* merge server config */
- cgi_cmds, /* command table */
- cgi_handlers, /* handlers */
- translate_scriptalias, /* filename translation */
- NULL, /* check_user_id */
- NULL, /* check auth */
- NULL, /* check access */
- type_scriptalias, /* type_checker */
- NULL, /* fixups */
- NULL, /* logger */
- NULL /* header parser */
-};
-</PRE>
-
-<H2><A NAME="handlers">How handlers work</A></H2>
-
-The sole argument to handlers is a <CODE>request_rec</CODE> structure.
-This structure describes a particular request which has been made to
-the server, on behalf of a client. In most cases, each connection to
-the client generates only one <CODE>request_rec</CODE> structure.<P>
-
-<H3><A NAME="req_tour">A brief tour of the <CODE>request_rec</CODE></A></H3>
-
-The <CODE>request_rec</CODE> contains pointers to a resource pool
-which will be cleared when the server is finished handling the
-request; to structures containing per-server and per-connection
-information, and most importantly, information on the request itself.<P>
-
-The most important such information is a small set of character
-strings describing attributes of the object being requested, including
-its URI, filename, content-type and content-encoding (these being filled
-in by the translation and type-check handlers which handle the
-request, respectively). <P>
-
-Other commonly used data items are tables giving the MIME headers on
-the client's original request, MIME headers to be sent back with the
-response (which modules can add to at will), and environment variables
-for any subprocesses which are spawned off in the course of servicing
-the request. These tables are manipulated using the
-<CODE>ap_table_get</CODE> and <CODE>ap_table_set</CODE> routines. <P>
-<BLOCKQUOTE>
- Note that the <SAMP>Content-type</SAMP> header value <EM>cannot</EM> be
- set by module content-handlers using the <SAMP>ap_table_*()</SAMP>
- routines. Rather, it is set by pointing the <SAMP>content_type</SAMP>
- field in the <SAMP>request_rec</SAMP> structure to an appropriate
- string. <EM>E.g.</EM>,
- <PRE>
- r-&gt;content_type = "text/html";
- </PRE>
-</BLOCKQUOTE>
-Finally, there are pointers to two data structures which, in turn,
-point to per-module configuration structures. Specifically, these
-hold pointers to the data structures which the module has built to
-describe the way it has been configured to operate in a given
-directory (via <CODE>.htaccess</CODE> files or
-<CODE>&lt;Directory&gt;</CODE> sections), for private data it has
-built in the course of servicing the request (so modules' handlers for
-one phase can pass `notes' to their handlers for other phases). There
-is another such configuration vector in the <CODE>server_rec</CODE>
-data structure pointed to by the <CODE>request_rec</CODE>, which
-contains per (virtual) server configuration data.<P>
-
-Here is an abridged declaration, giving the fields most commonly used:<P>
-
-<PRE>
-struct request_rec {
-
- pool *pool;
- conn_rec *connection;
- server_rec *server;
-
- /* What object is being requested */
-
- char *uri;
- char *filename;
- char *path_info;
- char *args; /* QUERY_ARGS, if any */
- struct stat finfo; /* Set by server core;
- * st_mode set to zero if no such file */
-
- char *content_type;
- char *content_encoding;
-
- /* MIME header environments, in and out. Also, an array containing
- * environment variables to be passed to subprocesses, so people can
- * write modules to add to that environment.
- *
- * The difference between headers_out and err_headers_out is that
- * the latter are printed even on error, and persist across internal
- * redirects (so the headers printed for ErrorDocument handlers will
- * have them).
- */
-
- table *headers_in;
- table *headers_out;
- table *err_headers_out;
- table *subprocess_env;
-
- /* Info about the request itself... */
-
- int header_only; /* HEAD request, as opposed to GET */
- char *protocol; /* Protocol, as given to us, or HTTP/0.9 */
- char *method; /* GET, HEAD, POST, <EM>etc.</EM> */
- int method_number; /* M_GET, M_POST, <EM>etc.</EM> */
-
- /* Info for logging */
-
- char *the_request;
- int bytes_sent;
-
- /* A flag which modules can set, to indicate that the data being
- * returned is volatile, and clients should be told not to cache it.
- */
-
- int no_cache;
-
- /* Various other config info which may change with .htaccess files
- * These are config vectors, with one void* pointer for each module
- * (the thing pointed to being the module's business).
- */
-
- void *per_dir_config; /* Options set in config files, <EM>etc.</EM> */
- void *request_config; /* Notes on *this* request */
-
-};
-
-</PRE>
-
-<H3><A NAME="req_orig">Where request_rec structures come from</A></H3>
-
-Most <CODE>request_rec</CODE> structures are built by reading an HTTP
-request from a client, and filling in the fields. However, there are
-a few exceptions:
-
-<UL>
- <LI> If the request is to an imagemap, a type map (<EM>i.e.</EM>, a
- <CODE>*.var</CODE> file), or a CGI script which returned a
- local `Location:', then the resource which the user requested
- is going to be ultimately located by some URI other than what
- the client originally supplied. In this case, the server does
- an <EM>internal redirect</EM>, constructing a new
- <CODE>request_rec</CODE> for the new URI, and processing it
- almost exactly as if the client had requested the new URI
- directly. <P>
-
- <LI> If some handler signaled an error, and an
- <CODE>ErrorDocument</CODE> is in scope, the same internal
- redirect machinery comes into play.<P>
-
- <LI> Finally, a handler occasionally needs to investigate `what
- would happen if' some other request were run. For instance,
- the directory indexing module needs to know what MIME type
- would be assigned to a request for each directory entry, in
- order to figure out what icon to use.<P>
-
- Such handlers can construct a <EM>sub-request</EM>, using the
- functions <CODE>ap_sub_req_lookup_file</CODE>,
- <CODE>ap_sub_req_lookup_uri</CODE>, and
- <CODE>ap_sub_req_method_uri</CODE>; these construct a new
- <CODE>request_rec</CODE> structure and processes it as you
- would expect, up to but not including the point of actually
- sending a response. (These functions skip over the access
- checks if the sub-request is for a file in the same directory
- as the original request).<P>
-
- (Server-side includes work by building sub-requests and then
- actually invoking the response handler for them, via the
- function <CODE>ap_run_sub_req</CODE>).
-</UL>
-
-<H3><A NAME="req_return">Handling requests, declining, and returning error
- codes</A></H3>
-
-As discussed above, each handler, when invoked to handle a particular
-<CODE>request_rec</CODE>, has to return an <CODE>int</CODE> to
-indicate what happened. That can either be
-
-<UL>
- <LI> OK --- the request was handled successfully. This may or may
- not terminate the phase.
- <LI> DECLINED --- no erroneous condition exists, but the module
- declines to handle the phase; the server tries to find another.
- <LI> an HTTP error code, which aborts handling of the request.
-</UL>
-
-Note that if the error code returned is <CODE>REDIRECT</CODE>, then
-the module should put a <CODE>Location</CODE> in the request's
-<CODE>headers_out</CODE>, to indicate where the client should be
-redirected <EM>to</EM>. <P>
-
-<H3><A NAME="resp_handlers">Special considerations for response
- handlers</A></H3>
-
-Handlers for most phases do their work by simply setting a few fields
-in the <CODE>request_rec</CODE> structure (or, in the case of access
-checkers, simply by returning the correct error code). However,
-response handlers have to actually send a request back to the client. <P>
-
-They should begin by sending an HTTP response header, using the
-function <CODE>ap_send_http_header</CODE>. (You don't have to do
-anything special to skip sending the header for HTTP/0.9 requests; the
-function figures out on its own that it shouldn't do anything). If
-the request is marked <CODE>header_only</CODE>, that's all they should
-do; they should return after that, without attempting any further
-output. <P>
-
-Otherwise, they should produce a request body which responds to the
-client as appropriate. The primitives for this are <CODE>ap_rputc</CODE>
-and <CODE>ap_rprintf</CODE>, for internally generated output, and
-<CODE>ap_send_fd</CODE>, to copy the contents of some <CODE>FILE *</CODE>
-straight to the client. <P>
-
-At this point, you should more or less understand the following piece
-of code, which is the handler which handles <CODE>GET</CODE> requests
-which have no more specific handler; it also shows how conditional
-<CODE>GET</CODE>s can be handled, if it's desirable to do so in a
-particular response handler --- <CODE>ap_set_last_modified</CODE> checks
-against the <CODE>If-modified-since</CODE> value supplied by the
-client, if any, and returns an appropriate code (which will, if
-nonzero, be USE_LOCAL_COPY). No similar considerations apply for
-<CODE>ap_set_content_length</CODE>, but it returns an error code for
-symmetry.<P>
-
-<PRE>
-int default_handler (request_rec *r)
-{
- int errstatus;
- FILE *f;
-
- if (r-&gt;method_number != M_GET) return DECLINED;
- if (r-&gt;finfo.st_mode == 0) return NOT_FOUND;
-
- if ((errstatus = ap_set_content_length (r, r-&gt;finfo.st_size))
- || (errstatus = ap_set_last_modified (r, r-&gt;finfo.st_mtime)))
- return errstatus;
-
- f = fopen (r-&gt;filename, "r");
-
- if (f == NULL) {
- log_reason("file permissions deny server access",
- r-&gt;filename, r);
- return FORBIDDEN;
- }
-
- register_timeout ("send", r);
- ap_send_http_header (r);
-
- if (!r-&gt;header_only) send_fd (f, r);
- ap_pfclose (r-&gt;pool, f);
- return OK;
-}
-</PRE>
-
-Finally, if all of this is too much of a challenge, there are a few
-ways out of it. First off, as shown above, a response handler which
-has not yet produced any output can simply return an error code, in
-which case the server will automatically produce an error response.
-Secondly, it can punt to some other handler by invoking
-<CODE>ap_internal_redirect</CODE>, which is how the internal redirection
-machinery discussed above is invoked. A response handler which has
-internally redirected should always return <CODE>OK</CODE>. <P>
-
-(Invoking <CODE>ap_internal_redirect</CODE> from handlers which are
-<EM>not</EM> response handlers will lead to serious confusion).
-
-<H3><A NAME="auth_handlers">Special considerations for authentication
- handlers</A></H3>
-
-Stuff that should be discussed here in detail:
-
-<UL>
- <LI> Authentication-phase handlers not invoked unless auth is
- configured for the directory.
- <LI> Common auth configuration stored in the core per-dir
- configuration; it has accessors <CODE>ap_auth_type</CODE>,
- <CODE>ap_auth_name</CODE>, and <CODE>ap_requires</CODE>.
- <LI> Common routines, to handle the protocol end of things, at least
- for HTTP basic authentication (<CODE>ap_get_basic_auth_pw</CODE>,
- which sets the <CODE>connection-&gt;user</CODE> structure field
- automatically, and <CODE>ap_note_basic_auth_failure</CODE>, which
- arranges for the proper <CODE>WWW-Authenticate:</CODE> header
- to be sent back).
-</UL>
-
-<H3><A NAME="log_handlers">Special considerations for logging handlers</A></H3>
-
-When a request has internally redirected, there is the question of
-what to log. Apache handles this by bundling the entire chain of
-redirects into a list of <CODE>request_rec</CODE> structures which are
-threaded through the <CODE>r-&gt;prev</CODE> and <CODE>r-&gt;next</CODE>
-pointers. The <CODE>request_rec</CODE> which is passed to the logging
-handlers in such cases is the one which was originally built for the
-initial request from the client; note that the bytes_sent field will
-only be correct in the last request in the chain (the one for which a
-response was actually sent).
-
-<H2><A NAME="pools">Resource allocation and resource pools</A></H2>
-<P>
-One of the problems of writing and designing a server-pool server is
-that of preventing leakage, that is, allocating resources (memory,
-open files, <EM>etc.</EM>), without subsequently releasing them. The resource
-pool machinery is designed to make it easy to prevent this from
-happening, by allowing resource to be allocated in such a way that
-they are <EM>automatically</EM> released when the server is done with
-them.
-</P>
-<P>
-The way this works is as follows: the memory which is allocated, file
-opened, <EM>etc.</EM>, to deal with a particular request are tied to a
-<EM>resource pool</EM> which is allocated for the request. The pool
-is a data structure which itself tracks the resources in question.
-</P>
-<P>
-When the request has been processed, the pool is <EM>cleared</EM>. At
-that point, all the memory associated with it is released for reuse,
-all files associated with it are closed, and any other clean-up
-functions which are associated with the pool are run. When this is
-over, we can be confident that all the resource tied to the pool have
-been released, and that none of them have leaked.
-</P>
-<P>
-Server restarts, and allocation of memory and resources for per-server
-configuration, are handled in a similar way. There is a
-<EM>configuration pool</EM>, which keeps track of resources which were
-allocated while reading the server configuration files, and handling
-the commands therein (for instance, the memory that was allocated for
-per-server module configuration, log files and other files that were
-opened, and so forth). When the server restarts, and has to reread
-the configuration files, the configuration pool is cleared, and so the
-memory and file descriptors which were taken up by reading them the
-last time are made available for reuse.
-</P>
-<P>
-It should be noted that use of the pool machinery isn't generally
-obligatory, except for situations like logging handlers, where you
-really need to register cleanups to make sure that the log file gets
-closed when the server restarts (this is most easily done by using the
-function <CODE><A HREF="#pool-files">ap_pfopen</A></CODE>, which also
-arranges for the underlying file descriptor to be closed before any
-child processes, such as for CGI scripts, are <CODE>exec</CODE>ed), or
-in case you are using the timeout machinery (which isn't yet even
-documented here). However, there are two benefits to using it:
-resources allocated to a pool never leak (even if you allocate a
-scratch string, and just forget about it); also, for memory
-allocation, <CODE>ap_palloc</CODE> is generally faster than
-<CODE>malloc</CODE>.
-</P>
-<P>
-We begin here by describing how memory is allocated to pools, and then
-discuss how other resources are tracked by the resource pool
-machinery.
-</P>
-<H3>Allocation of memory in pools</H3>
-<P>
-Memory is allocated to pools by calling the function
-<CODE>ap_palloc</CODE>, which takes two arguments, one being a pointer to
-a resource pool structure, and the other being the amount of memory to
-allocate (in <CODE>char</CODE>s). Within handlers for handling
-requests, the most common way of getting a resource pool structure is
-by looking at the <CODE>pool</CODE> slot of the relevant
-<CODE>request_rec</CODE>; hence the repeated appearance of the
-following idiom in module code:
-</P>
-<PRE>
-int my_handler(request_rec *r)
-{
- struct my_structure *foo;
- ...
-
- foo = (foo *)ap_palloc (r-&gt;pool, sizeof(my_structure));
-}
-</PRE>
-<P>
-Note that <EM>there is no <CODE>ap_pfree</CODE></EM> ---
-<CODE>ap_palloc</CODE>ed memory is freed only when the associated
-resource pool is cleared. This means that <CODE>ap_palloc</CODE> does not
-have to do as much accounting as <CODE>malloc()</CODE>; all it does in
-the typical case is to round up the size, bump a pointer, and do a
-range check.
-</P>
-<P>
-(It also raises the possibility that heavy use of <CODE>ap_palloc</CODE>
-could cause a server process to grow excessively large. There are
-two ways to deal with this, which are dealt with below; briefly, you
-can use <CODE>malloc</CODE>, and try to be sure that all of the memory
-gets explicitly <CODE>free</CODE>d, or you can allocate a sub-pool of
-the main pool, allocate your memory in the sub-pool, and clear it out
-periodically. The latter technique is discussed in the section on
-sub-pools below, and is used in the directory-indexing code, in order
-to avoid excessive storage allocation when listing directories with
-thousands of files).
-</P>
-<H3>Allocating initialized memory</H3>
-<P>
-There are functions which allocate initialized memory, and are
-frequently useful. The function <CODE>ap_pcalloc</CODE> has the same
-interface as <CODE>ap_palloc</CODE>, but clears out the memory it
-allocates before it returns it. The function <CODE>ap_pstrdup</CODE>
-takes a resource pool and a <CODE>char *</CODE> as arguments, and
-allocates memory for a copy of the string the pointer points to,
-returning a pointer to the copy. Finally <CODE>ap_pstrcat</CODE> is a
-varargs-style function, which takes a pointer to a resource pool, and
-at least two <CODE>char *</CODE> arguments, the last of which must be
-<CODE>NULL</CODE>. It allocates enough memory to fit copies of each
-of the strings, as a unit; for instance:
-</P>
-<PRE>
- ap_pstrcat (r-&gt;pool, "foo", "/", "bar", NULL);
-</PRE>
-<P>
-returns a pointer to 8 bytes worth of memory, initialized to
-<CODE>"foo/bar"</CODE>.
-</P>
-<H3><A NAME="pools-used">Commonly-used pools in the Apache Web server</A></H3>
-<P>
-A pool is really defined by its lifetime more than anything else. There
-are some static pools in http_main which are passed to various
-non-http_main functions as arguments at opportune times. Here they are:
-</P>
-<DL COMPACT>
- <DT>permanent_pool
- </DT>
- <DD>
- <UL>
- <LI>never passed to anything else, this is the ancestor of all pools
- </LI>
- </UL>
- </DD>
- <DT>pconf
- </DT>
- <DD>
- <UL>
- <LI>subpool of permanent_pool
- </LI>
- <LI>created at the beginning of a config "cycle"; exists until the
- server is terminated or restarts; passed to all config-time
- routines, either via cmd-&gt;pool, or as the "pool *p" argument on
- those which don't take pools
- </LI>
- <LI>passed to the module init() functions
- </LI>
- </UL>
- </DD>
- <DT>ptemp
- </DT>
- <DD>
- <UL>
- <LI>sorry I lie, this pool isn't called this currently in 1.3, I
- renamed it this in my pthreads development. I'm referring to
- the use of ptrans in the parent... contrast this with the later
- definition of ptrans in the child.
- </LI>
- <LI>subpool of permanent_pool
- </LI>
- <LI>created at the beginning of a config "cycle"; exists until the
- end of config parsing; passed to config-time routines <EM>via</EM>
- cmd-&gt;temp_pool. Somewhat of a "bastard child" because it isn't
- available everywhere. Used for temporary scratch space which
- may be needed by some config routines but which is deleted at
- the end of config.
- </LI>
- </UL>
- </DD>
- <DT>pchild
- </DT>
- <DD>
- <UL>
- <LI>subpool of permanent_pool
- </LI>
- <LI>created when a child is spawned (or a thread is created); lives
- until that child (thread) is destroyed
- </LI>
- <LI>passed to the module child_init functions
- </LI>
- <LI>destruction happens right after the child_exit functions are
- called... (which may explain why I think child_exit is redundant
- and unneeded)
- </LI>
- </UL>
- </DD>
- <DT>ptrans
- <DT>
- <DD>
- <UL>
- <LI>should be a subpool of pchild, but currently is a subpool of
- permanent_pool, see above
- </LI>
- <LI>cleared by the child before going into the accept() loop to receive
- a connection
- </LI>
- <LI>used as connection-&gt;pool
- </LI>
- </UL>
- </DD>
- <DT>r-&gt;pool
- </DT>
- <DD>
- <UL>
- <LI>for the main request this is a subpool of connection-&gt;pool; for
- subrequests it is a subpool of the parent request's pool.
- </LI>
- <LI>exists until the end of the request (<EM>i.e.</EM>,
- ap_destroy_sub_req, or
- in child_main after process_request has finished)
- </LI>
- <LI>note that r itself is allocated from r-&gt;pool; <EM>i.e.</EM>,
- r-&gt;pool is
- first created and then r is the first thing palloc()d from it
- </LI>
- </UL>
- </DD>
-</DL>
-<P>
-For almost everything folks do, r-&gt;pool is the pool to use. But you
-can see how other lifetimes, such as pchild, are useful to some
-modules... such as modules that need to open a database connection once
-per child, and wish to clean it up when the child dies.
-</P>
-<P>
-You can also see how some bugs have manifested themself, such as setting
-connection-&gt;user to a value from r-&gt;pool -- in this case
-connection exists
-for the lifetime of ptrans, which is longer than r-&gt;pool (especially if
-r-&gt;pool is a subrequest!). So the correct thing to do is to allocate
-from connection-&gt;pool.
-</P>
-<P>
-And there was another interesting bug in mod_include/mod_cgi. You'll see
-in those that they do this test to decide if they should use r-&gt;pool
-or r-&gt;main-&gt;pool. In this case the resource that they are registering
-for cleanup is a child process. If it were registered in r-&gt;pool,
-then the code would wait() for the child when the subrequest finishes.
-With mod_include this could be any old #include, and the delay can be up
-to 3 seconds... and happened quite frequently. Instead the subprocess
-is registered in r-&gt;main-&gt;pool which causes it to be cleaned up when
-the entire request is done -- <EM>i.e.</EM>, after the output has been sent to
-the client and logging has happened.
-</P>
-<H3><A NAME="pool-files">Tracking open files, etc.</A></H3>
-<P>
-As indicated above, resource pools are also used to track other sorts
-of resources besides memory. The most common are open files. The
-routine which is typically used for this is <CODE>ap_pfopen</CODE>, which
-takes a resource pool and two strings as arguments; the strings are
-the same as the typical arguments to <CODE>fopen</CODE>, <EM>e.g.</EM>,
-</P>
-<PRE>
- ...
- FILE *f = ap_pfopen (r-&gt;pool, r-&gt;filename, "r");
-
- if (f == NULL) { ... } else { ... }
-</PRE>
-<P>
-There is also a <CODE>ap_popenf</CODE> routine, which parallels the
-lower-level <CODE>open</CODE> system call. Both of these routines
-arrange for the file to be closed when the resource pool in question
-is cleared.
-</P>
-<P>
-Unlike the case for memory, there <EM>are</EM> functions to close
-files allocated with <CODE>ap_pfopen</CODE>, and <CODE>ap_popenf</CODE>,
-namely <CODE>ap_pfclose</CODE> and <CODE>ap_pclosef</CODE>. (This is
-because, on many systems, the number of files which a single process
-can have open is quite limited). It is important to use these
-functions to close files allocated with <CODE>ap_pfopen</CODE> and
-<CODE>ap_popenf</CODE>, since to do otherwise could cause fatal errors on
-systems such as Linux, which react badly if the same
-<CODE>FILE*</CODE> is closed more than once.
-</P>
-<P>
-(Using the <CODE>close</CODE> functions is not mandatory, since the
-file will eventually be closed regardless, but you should consider it
-in cases where your module is opening, or could open, a lot of files).
-</P>
-<H3>Other sorts of resources --- cleanup functions</H3>
-<BLOCKQUOTE>
-More text goes here. Describe the the cleanup primitives in terms of
-which the file stuff is implemented; also, <CODE>spawn_process</CODE>.
-</BLOCKQUOTE>
-<P>
-Pool cleanups live until clear_pool() is called: clear_pool(a) recursively
-calls destroy_pool() on all subpools of a; then calls all the cleanups for a;
-then releases all the memory for a. destroy_pool(a) calls clear_pool(a)
-and then releases the pool structure itself. <EM>i.e.</EM>, clear_pool(a) doesn't
-delete a, it just frees up all the resources and you can start using it
-again immediately.
-</P>
-<H3>Fine control --- creating and dealing with sub-pools, with a note
-on sub-requests</H3>
-
-On rare occasions, too-free use of <CODE>ap_palloc()</CODE> and the
-associated primitives may result in undesirably profligate resource
-allocation. You can deal with such a case by creating a
-<EM>sub-pool</EM>, allocating within the sub-pool rather than the main
-pool, and clearing or destroying the sub-pool, which releases the
-resources which were associated with it. (This really <EM>is</EM> a
-rare situation; the only case in which it comes up in the standard
-module set is in case of listing directories, and then only with
-<EM>very</EM> large directories. Unnecessary use of the primitives
-discussed here can hair up your code quite a bit, with very little
-gain). <P>
-
-The primitive for creating a sub-pool is <CODE>ap_make_sub_pool</CODE>,
-which takes another pool (the parent pool) as an argument. When the
-main pool is cleared, the sub-pool will be destroyed. The sub-pool
-may also be cleared or destroyed at any time, by calling the functions
-<CODE>ap_clear_pool</CODE> and <CODE>ap_destroy_pool</CODE>, respectively.
-(The difference is that <CODE>ap_clear_pool</CODE> frees resources
-associated with the pool, while <CODE>ap_destroy_pool</CODE> also
-deallocates the pool itself. In the former case, you can allocate new
-resources within the pool, and clear it again, and so forth; in the
-latter case, it is simply gone). <P>
-
-One final note --- sub-requests have their own resource pools, which
-are sub-pools of the resource pool for the main request. The polite
-way to reclaim the resources associated with a sub request which you
-have allocated (using the <CODE>ap_sub_req_...</CODE> functions)
-is <CODE>ap_destroy_sub_req</CODE>, which frees the resource pool.
-Before calling this function, be sure to copy anything that you care
-about which might be allocated in the sub-request's resource pool into
-someplace a little less volatile (for instance, the filename in its
-<CODE>request_rec</CODE> structure). <P>
-
-(Again, under most circumstances, you shouldn't feel obliged to call
-this function; only 2K of memory or so are allocated for a typical sub
-request, and it will be freed anyway when the main request pool is
-cleared. It is only when you are allocating many, many sub-requests
-for a single main request that you should seriously consider the
-<CODE>ap_destroy_...</CODE> functions).
-
-<H2><A NAME="config">Configuration, commands and the like</A></H2>
-
-One of the design goals for this server was to maintain external
-compatibility with the NCSA 1.3 server --- that is, to read the same
-configuration files, to process all the directives therein correctly,
-and in general to be a drop-in replacement for NCSA. On the other
-hand, another design goal was to move as much of the server's
-functionality into modules which have as little as possible to do with
-the monolithic server core. The only way to reconcile these goals is
-to move the handling of most commands from the central server into the
-modules. <P>
-
-However, just giving the modules command tables is not enough to
-divorce them completely from the server core. The server has to
-remember the commands in order to act on them later. That involves
-maintaining data which is private to the modules, and which can be
-either per-server, or per-directory. Most things are per-directory,
-including in particular access control and authorization information,
-but also information on how to determine file types from suffixes,
-which can be modified by <CODE>AddType</CODE> and
-<CODE>DefaultType</CODE> directives, and so forth. In general, the
-governing philosophy is that anything which <EM>can</EM> be made
-configurable by directory should be; per-server information is
-generally used in the standard set of modules for information like
-<CODE>Alias</CODE>es and <CODE>Redirect</CODE>s which come into play
-before the request is tied to a particular place in the underlying
-file system. <P>
-
-Another requirement for emulating the NCSA server is being able to
-handle the per-directory configuration files, generally called
-<CODE>.htaccess</CODE> files, though even in the NCSA server they can
-contain directives which have nothing at all to do with access
-control. Accordingly, after URI -&gt; filename translation, but before
-performing any other phase, the server walks down the directory
-hierarchy of the underlying filesystem, following the translated
-pathname, to read any <CODE>.htaccess</CODE> files which might be
-present. The information which is read in then has to be
-<EM>merged</EM> with the applicable information from the server's own
-config files (either from the <CODE>&lt;Directory&gt;</CODE> sections
-in <CODE>access.conf</CODE>, or from defaults in
-<CODE>srm.conf</CODE>, which actually behaves for most purposes almost
-exactly like <CODE>&lt;Directory /&gt;</CODE>).<P>
-
-Finally, after having served a request which involved reading
-<CODE>.htaccess</CODE> files, we need to discard the storage allocated
-for handling them. That is solved the same way it is solved wherever
-else similar problems come up, by tying those structures to the
-per-transaction resource pool. <P>
-
-<H3><A NAME="per-dir">Per-directory configuration structures</A></H3>
-
-Let's look out how all of this plays out in <CODE>mod_mime.c</CODE>,
-which defines the file typing handler which emulates the NCSA server's
-behavior of determining file types from suffixes. What we'll be
-looking at, here, is the code which implements the
-<CODE>AddType</CODE> and <CODE>AddEncoding</CODE> commands. These
-commands can appear in <CODE>.htaccess</CODE> files, so they must be
-handled in the module's private per-directory data, which in fact,
-consists of two separate <CODE>table</CODE>s for MIME types and
-encoding information, and is declared as follows:
-
-<PRE>
-typedef struct {
- table *forced_types; /* Additional AddTyped stuff */
- table *encoding_types; /* Added with AddEncoding... */
-} mime_dir_config;
-</PRE>
-
-When the server is reading a configuration file, or
-<CODE>&lt;Directory&gt;</CODE> section, which includes one of the MIME
-module's commands, it needs to create a <CODE>mime_dir_config</CODE>
-structure, so those commands have something to act on. It does this
-by invoking the function it finds in the module's `create per-dir
-config slot', with two arguments: the name of the directory to which
-this configuration information applies (or <CODE>NULL</CODE> for
-<CODE>srm.conf</CODE>), and a pointer to a resource pool in which the
-allocation should happen. <P>
-
-(If we are reading a <CODE>.htaccess</CODE> file, that resource pool
-is the per-request resource pool for the request; otherwise it is a
-resource pool which is used for configuration data, and cleared on
-restarts. Either way, it is important for the structure being created
-to vanish when the pool is cleared, by registering a cleanup on the
-pool if necessary). <P>
-
-For the MIME module, the per-dir config creation function just
-<CODE>ap_palloc</CODE>s the structure above, and a creates a couple of
-<CODE>table</CODE>s to fill it. That looks like this:
-
-<PRE>
-void *create_mime_dir_config (pool *p, char *dummy)
-{
- mime_dir_config *new =
- (mime_dir_config *) ap_palloc (p, sizeof(mime_dir_config));
-
- new-&gt;forced_types = ap_make_table (p, 4);
- new-&gt;encoding_types = ap_make_table (p, 4);
-
- return new;
-}
-</PRE>
-
-Now, suppose we've just read in a <CODE>.htaccess</CODE> file. We
-already have the per-directory configuration structure for the next
-directory up in the hierarchy. If the <CODE>.htaccess</CODE> file we
-just read in didn't have any <CODE>AddType</CODE> or
-<CODE>AddEncoding</CODE> commands, its per-directory config structure
-for the MIME module is still valid, and we can just use it.
-Otherwise, we need to merge the two structures somehow. <P>
-
-To do that, the server invokes the module's per-directory config merge
-function, if one is present. That function takes three arguments:
-the two structures being merged, and a resource pool in which to
-allocate the result. For the MIME module, all that needs to be done
-is overlay the tables from the new per-directory config structure with
-those from the parent:
-
-<PRE>
-void *merge_mime_dir_configs (pool *p, void *parent_dirv, void *subdirv)
-{
- mime_dir_config *parent_dir = (mime_dir_config *)parent_dirv;
- mime_dir_config *subdir = (mime_dir_config *)subdirv;
- mime_dir_config *new =
- (mime_dir_config *)ap_palloc (p, sizeof(mime_dir_config));
-
- new-&gt;forced_types = ap_overlay_tables (p, subdir-&gt;forced_types,
- parent_dir-&gt;forced_types);
- new-&gt;encoding_types = ap_overlay_tables (p, subdir-&gt;encoding_types,
- parent_dir-&gt;encoding_types);
-
- return new;
-}
-</PRE>
-
-As a note --- if there is no per-directory merge function present, the
-server will just use the subdirectory's configuration info, and ignore
-the parent's. For some modules, that works just fine (<EM>e.g.</EM>, for the
-includes module, whose per-directory configuration information
-consists solely of the state of the <CODE>XBITHACK</CODE>), and for
-those modules, you can just not declare one, and leave the
-corresponding structure slot in the module itself <CODE>NULL</CODE>.<P>
-
-<H3><A NAME="commands">Command handling</A></H3>
-
-Now that we have these structures, we need to be able to figure out
-how to fill them. That involves processing the actual
-<CODE>AddType</CODE> and <CODE>AddEncoding</CODE> commands. To find
-commands, the server looks in the module's <CODE>command table</CODE>.
-That table contains information on how many arguments the commands
-take, and in what formats, where it is permitted, and so forth. That
-information is sufficient to allow the server to invoke most
-command-handling functions with pre-parsed arguments. Without further
-ado, let's look at the <CODE>AddType</CODE> command handler, which
-looks like this (the <CODE>AddEncoding</CODE> command looks basically
-the same, and won't be shown here):
-
-<PRE>
-char *add_type(cmd_parms *cmd, mime_dir_config *m, char *ct, char *ext)
-{
- if (*ext == '.') ++ext;
- ap_table_set (m-&gt;forced_types, ext, ct);
- return NULL;
-}
-</PRE>
-
-This command handler is unusually simple. As you can see, it takes
-four arguments, two of which are pre-parsed arguments, the third being
-the per-directory configuration structure for the module in question,
-and the fourth being a pointer to a <CODE>cmd_parms</CODE> structure.
-That structure contains a bunch of arguments which are frequently of
-use to some, but not all, commands, including a resource pool (from
-which memory can be allocated, and to which cleanups should be tied),
-and the (virtual) server being configured, from which the module's
-per-server configuration data can be obtained if required.<P>
-
-Another way in which this particular command handler is unusually
-simple is that there are no error conditions which it can encounter.
-If there were, it could return an error message instead of
-<CODE>NULL</CODE>; this causes an error to be printed out on the
-server's <CODE>stderr</CODE>, followed by a quick exit, if it is in
-the main config files; for a <CODE>.htaccess</CODE> file, the syntax
-error is logged in the server error log (along with an indication of
-where it came from), and the request is bounced with a server error
-response (HTTP error status, code 500). <P>
-
-The MIME module's command table has entries for these commands, which
-look like this:
-
-<PRE>
-command_rec mime_cmds[] = {
-{ "AddType", add_type, NULL, OR_FILEINFO, TAKE2,
- "a mime type followed by a file extension" },
-{ "AddEncoding", add_encoding, NULL, OR_FILEINFO, TAKE2,
- "an encoding (<EM>e.g.</EM>, gzip), followed by a file extension" },
-{ NULL }
-};
-</PRE>
-
-The entries in these tables are:
-
-<UL>
- <LI> The name of the command
- <LI> The function which handles it
- <LI> a <CODE>(void *)</CODE> pointer, which is passed in the
- <CODE>cmd_parms</CODE> structure to the command handler ---
- this is useful in case many similar commands are handled by the
- same function.
- <LI> A bit mask indicating where the command may appear. There are
- mask bits corresponding to each <CODE>AllowOverride</CODE>
- option, and an additional mask bit, <CODE>RSRC_CONF</CODE>,
- indicating that the command may appear in the server's own
- config files, but <EM>not</EM> in any <CODE>.htaccess</CODE>
- file.
- <LI> A flag indicating how many arguments the command handler wants
- pre-parsed, and how they should be passed in.
- <CODE>TAKE2</CODE> indicates two pre-parsed arguments. Other
- options are <CODE>TAKE1</CODE>, which indicates one pre-parsed
- argument, <CODE>FLAG</CODE>, which indicates that the argument
- should be <CODE>On</CODE> or <CODE>Off</CODE>, and is passed in
- as a boolean flag, <CODE>RAW_ARGS</CODE>, which causes the
- server to give the command the raw, unparsed arguments
- (everything but the command name itself). There is also
- <CODE>ITERATE</CODE>, which means that the handler looks the
- same as <CODE>TAKE1</CODE>, but that if multiple arguments are
- present, it should be called multiple times, and finally
- <CODE>ITERATE2</CODE>, which indicates that the command handler
- looks like a <CODE>TAKE2</CODE>, but if more arguments are
- present, then it should be called multiple times, holding the
- first argument constant.
- <LI> Finally, we have a string which describes the arguments that
- should be present. If the arguments in the actual config file
- are not as required, this string will be used to help give a
- more specific error message. (You can safely leave this
- <CODE>NULL</CODE>).
-</UL>
-
-Finally, having set this all up, we have to use it. This is
-ultimately done in the module's handlers, specifically for its
-file-typing handler, which looks more or less like this; note that the
-per-directory configuration structure is extracted from the
-<CODE>request_rec</CODE>'s per-directory configuration vector by using
-the <CODE>ap_get_module_config</CODE> function.
-
-<PRE>
-int find_ct(request_rec *r)
-{
- int i;
- char *fn = ap_pstrdup (r-&gt;pool, r-&gt;filename);
- mime_dir_config *conf = (mime_dir_config *)
- ap_get_module_config(r-&gt;per_dir_config, &amp;mime_module);
- char *type;
-
- if (S_ISDIR(r-&gt;finfo.st_mode)) {
- r-&gt;content_type = DIR_MAGIC_TYPE;
- return OK;
- }
-
- if((i=ap_rind(fn,'.')) &lt; 0) return DECLINED;
- ++i;
-
- if ((type = ap_table_get (conf-&gt;encoding_types, &amp;fn[i])))
- {
- r-&gt;content_encoding = type;
-
- /* go back to previous extension to try to use it as a type */
-
- fn[i-1] = '\0';