diff options
106 files changed, 9511 insertions, 14347 deletions
diff --git a/build/binbuild.sh b/build/binbuild.sh deleted file mode 100755 index 3279148fcb..0000000000 --- a/build/binbuild.sh +++ /dev/null @@ -1,221 +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 - - -APDIR=$(basename $(pwd)) -VER=$(echo $APDIR |sed s/apache-//) -OS=$(src/helpers/GuessOS) -USER="$(src/helpers/buildinfo.sh -n %u@%h%d)" -TAR="$(src/helpers/findprg.sh tar)" -GTAR="$(src/helpers/findprg.sh gtar)" -GZIP="$(src/helpers/findprg.sh gzip)" -CONFIGPARAM="--with-layout=BinaryDistribution --enable-module=most --enable-shared=max" - -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 images successfully created..." -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 "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 "./src/helpers/mkdir.sh \$SR" && \ - echo "cp -r bindist/proxy \$SR/proxy" && \ - echo "cp -r bindist/man \$SR/man" && \ - echo "cp -r bindist/logs \$SR/logs" && \ - echo "cp -r bindist/libexec \$SR/libexec" && \ - echo "cp -r bindist/include \$SR/include" && \ - echo "cp -r bindist/icons \$SR/icons" && \ - echo "cp -r bindist/cgi-bin \$SR/cgi-bin" && \ - echo "cp -r bindist/bin \$SR/bin" && \ - echo "if [ -d \$SR/conf ]" && \ - echo "then" && \ - echo " echo \"[Preserving existing configuration files.]\"" && \ - echo " cp -r bindist/conf/*.default \$SR/conf/" && \ - echo "else" && \ - echo " cp -r bindist/conf \$SR/conf" && \ - echo "fi" && \ - echo "if [ -d \$SR/htdocs ]" && \ - echo "then" && \ - echo " echo \"[Preserving existing htdocs directory.]\"" && \ - echo "else" && \ - echo " cp -r bindist/htdocs \$SR/htdocs" && \ - echo "fi" && \ - 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\\\"%\" 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 now should first check the (initially |\"" && \ - echo "echo \" | created or preserved) configuration files |\"" && \ - echo "echo \" | |\"" && \ - echo "echo \" | \$SR/conf/httpd.conf\"" && \ - echo "echo \" | |\"" && \ - echo "echo \" | and then you should 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%^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 [ ".$GTAR" != . ] - then - $GTAR -zcf ../apache-$VER-$OS.tar.gz -C .. --owner=root --group=root apache-$VER - else - if [ ".$TAR" != . ] - then - $TAR -cf ../apache-$VER-$OS.tar -C .. apache-$VER - if [ ".$GZIP" != . ] - 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 diff --git a/docs/docroot/apache_pb.gif b/docs/docroot/apache_pb.gif Binary files differdeleted file mode 100644 index 3a1c139fc4..0000000000 --- a/docs/docroot/apache_pb.gif +++ /dev/null diff --git a/docs/manual/LICENSE b/docs/manual/LICENSE deleted file mode 100644 index 0d3053a52e..0000000000 --- a/docs/manual/LICENSE +++ /dev/null @@ -1,51 +0,0 @@ - -Apache httpd license - ==================== - - -This is the license for the Apache Server. It covers all the -files which come in this distribution, and should never be removed. - -The "Apache Group" has based this server, called "Apache", on -public domain code distributed under the name "NCSA httpd 1.3". - -NCSA httpd 1.3 was placed in the public domain by the National Center -for Supercomputing Applications at the University of Illinois -at Urbana-Champaign. - -As requested by NCSA we acknowledge, - - "Portions developed at the National Center for Supercomputing - Applications at the University of Illinois at Urbana-Champaign." - -Copyright on the sections of code added by the "Apache Group" belong -to the "Apache Group" and/or the original authors. The "Apache Group" and -authors hereby grant permission for their code, along with the -public domain NCSA code, to be distributed under the "Apache" name. - -Reuse of "Apache Group" code outside of the Apache distribution should -be acknowledged with the following quoted text, to be included with any new -work; - - "Portions developed by the "Apache Group", taken with permission - from the Apache Server http://www.hyperreal.com/apache/ " - - -Permission is hereby granted to anyone to redistribute Apache under -the "Apache" name. We do not grant permission for the resale of Apache, but -we do grant permission for vendors to bundle Apache free with other software, -or to charge a reasonable price for redistribution, provided it is made -clear that Apache is free. Permission is also granted for vendors to -sell support for for Apache. We explicitly forbid the redistribution of -Apache under any other name. - -The "Apache Group" makes no promises to support "Apache". Users and -sellers of Apache support, and users of "Apache Group" code, should be -aware that they use "Apache" or portions of the "Apache Group" code at -their own risk. While every effort has been made to ensure that "Apache" -is robust and safe to use, we will not accept responsibility for any -damage caused, or loss of data or income which results from its use. - - - -Apache httpd server (c) 1995 The Apache Group. diff --git a/docs/manual/bind.html b/docs/manual/bind.html deleted file mode 100644 index 777f79650f..0000000000 --- a/docs/manual/bind.html +++ /dev/null @@ -1,103 +0,0 @@ -<html><head> -<title>Setting which addresses and ports Apache uses</title> -</head><body> - -<img src="../images/apache_sub.gif" alt=""> -<h1>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> -<strong>Syntax:</strong> BindAddress <em>[ * | IP-address | hostname ]</em><br> -<strong>Default:</strong> <code>BindAddress *</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> 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> -<strong>Syntax:</strong> Listen <em>[ port | IP-address:port ]</em><br> -<strong>Default:</strong> <code>none</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> 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 -<VirtualHost> directives are used, the server will behave the -same for all accepted requests. However, <VirtualHost> can be -used to specify a different behavour 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 -<VirtualHost> section should be created for a specified address -and port to set the behaviour of this virtual host. Note that if the -<VirtualHost> 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="virtual-host.html">Virtual Hosts</a>, -<a href="host.html">Non-IP virtual hosts</a>, -<a href="core.html#bindaddress">BindAddress directive</a>, -<a href="core.html#port">Port directive</a> -and -<a href="core.html#virtualhost"><VirtualHost> section</a>. -</ul> - -<hr> -<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> -<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> - -</BODY> -</HTML> - diff --git a/docs/manual/bind.html.en b/docs/manual/bind.html.en deleted file mode 100644 index 777f79650f..0000000000 --- a/docs/manual/bind.html.en +++ /dev/null @@ -1,103 +0,0 @@ -<html><head> -<title>Setting which addresses and ports Apache uses</title> -</head><body> - -<img src="../images/apache_sub.gif" alt=""> -<h1>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> -<strong>Syntax:</strong> BindAddress <em>[ * | IP-address | hostname ]</em><br> -<strong>Default:</strong> <code>BindAddress *</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> 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> -<strong>Syntax:</strong> Listen <em>[ port | IP-address:port ]</em><br> -<strong>Default:</strong> <code>none</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> 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 -<VirtualHost> directives are used, the server will behave the -same for all accepted requests. However, <VirtualHost> can be -used to specify a different behavour 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 -<VirtualHost> section should be created for a specified address -and port to set the behaviour of this virtual host. Note that if the -<VirtualHost> 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="virtual-host.html">Virtual Hosts</a>, -<a href="host.html">Non-IP virtual hosts</a>, -<a href="core.html#bindaddress">BindAddress directive</a>, -<a href="core.html#port">Port directive</a> -and -<a href="core.html#virtualhost"><VirtualHost> section</a>. -</ul> - -<hr> -<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> -<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> - -</BODY> -</HTML> - diff --git a/docs/manual/cgi_path.html b/docs/manual/cgi_path.html deleted file mode 100644 index 81bb314ead..0000000000 --- a/docs/manual/cgi_path.html +++ /dev/null @@ -1,84 +0,0 @@ -<html><head> -<title>PATH_INFO Changes in the CGI Environment</title> -</head><body> - -<!--#include virtual="header.html" --> -<h1>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 -counterintiutive, 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 -gauranteed that -"<code>http://$SERVER_NAME:$SERVER_PORT$SCRIPT_NAME$PATH_INFO</code>" -will always be an accessable URL that points to the current script, -something which was not neccessarily 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 neccessary 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 existance 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> - diff --git a/docs/manual/cgi_path.html.en b/docs/manual/cgi_path.html.en deleted file mode 100644 index 81bb314ead..0000000000 --- a/docs/manual/cgi_path.html.en +++ /dev/null @@ -1,84 +0,0 @@ -<html><head> -<title>PATH_INFO Changes in the CGI Environment</title> -</head><body> - -<!--#include virtual="header.html" --> -<h1>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 -counterintiutive, 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 -gauranteed that -"<code>http://$SERVER_NAME:$SERVER_PORT$SCRIPT_NAME$PATH_INFO</code>" -will always be an accessable URL that points to the current script, -something which was not neccessarily 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 neccessary 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 existance 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> - diff --git a/docs/manual/content-negotiation.html b/docs/manual/content-negotiation.html deleted file mode 100644 index 20825f3661..0000000000 --- a/docs/manual/content-negotiation.html +++ /dev/null @@ -1,216 +0,0 @@ -<html> -<head> -<title>Apache server Content arbitration: MultiViews and *.var files</title> -</head> - -<body> -<IMG SRC="../images/apache_sub.gif" ALT=""> -<h3>Content Arbitration: MultiViews and *.var files</h3> - -The HTTP standard allows clients (i.e., browsers like Mosaic or -Netscape) to specify what data formats they are prepared to accept. -The intention is that when information is available in multiple -variants (e.g., in different data formats), servers can use this -information to decide which variant to send. This feature has been -supported in the CERN server for a while, and while it is not yet -supported in the NCSA server, it is likely to assume a new importance -in light of the emergence of HTML3 capable browsers. <p> - -The Apache module <A HREF="mod_negotiation.html">mod_negotiation</A> handles -content negotiation in two different ways; special treatment for the -pseudo-mime-type <code>application/x-type-map</code>, and the -MultiViews per-directory Option (which can be set in srm.conf, or in -.htaccess files, as usual). These features are alternate user -interfaces to what amounts to the same piece of code (in the new file -<code>http_mime_db.c</code>) which implements the content negotiation -portion of the HTTP protocol. <p> - -Each of these features allows one of several files to satisfy a -request, based on what the client says it's willing to accept; the -differences are in the way the files are identified: - -<ul> - <li> A type map (i.e., a <code>*.var</code> file) names the files - containing the variants explicitly - <li> In a MultiViews search, the server does an implicit filename - pattern match, and chooses from among the results. -</ul> - -Apache also supports a new pseudo-MIME type, -text/x-server-parsed-html3, which is treated as text/html;level=3 -for purposes of content negotiation, and as server-side-included HTML -elsewhere. - -<h3>Type maps (*.var files)</h3> - -A type map is a document which is typed by the server (using its -normal suffix-based mechanisms) as -<code>application/x-type-map</code>. Note that to use this feature, -you've got to have an <code>AddType</code> some place which defines a -file suffix as <code>application/x-type-map</code>; the easiest thing -may be to stick a -<pre> - - AddType application/x-type-map var - -</pre> -in <code>srm.conf</code>. See comments in the sample config files for -details. <p> - -Type map files have an entry for each available variant; these entries -consist of contiguous RFC822-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, e.g., -<pre> - - URI: foo; vary="type,language" - - URI: foo.en.html - Content-type: text/html; level=2 - Content-language: en - - URI: foo.fr.html - Content-type: text/html; level=2 - Content-language: fr - -</pre> -If the variants have different qualities, that may be indicated by the -"qs" parameter, as in this picture (available as jpeg, gif, or ASCII-art): -<pre> - - URI: foo; vary="type,language" - - 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> - -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 --- level may be specified, along with "qs". These - are often referred to as MIME types; typical media types are - <code>image/gif</code>, <code>text/plain</code>, or - <code>text/html; level=3</code>. - <dt> <code>Content-language:</code> - <dd> The language of the variant, specified as an internet standard - language code (e.g., <code>en</code> for English, - <code>kr</code> for Korean, etc.). - <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. - For compressed files (the only case where this generally comes - up), content encoding should be - <code>x-compress</code>, or <code>gzip</code>, as appropriate. - <dt> <code>Content-length:</code> - <dd> The size of the file. Clients can ask to receive a given media - type only if the variant isn't too big; specifying a content - length in the map allows the server to compare against these - thresholds without checking the actual file. -</dl> - -<h3>Multiviews</h3> - -This is a per-directory option, meaning it can be set with an -<code>Options</code> directive within a <code><Directory></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. (Fixing this is a one-line change to -<code>httpd.h</code>). - -<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 *not* 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, and forwards them along. - -<p> - -This applies 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 by the globbing is a CGI script, it's not -obvious what should happen. My code gives that case gets 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. This is the only jiggering of quality ratings done by the -MultiViews code; aside from that, all Qualities in the synthesized -type maps are 1.0. - -<p> - -<B>New as of 0.8:</B> Documents in multiple languages can also be resolved through the use -of the <code>AddLanguage</code> and <code>LanguagePriority</code> -directives: - -<pre> -AddLanguage en .en -AddLanguage fr .fr -AddLanguage de .de -AddLanguage da .da -AddLanguage el .el -AddLanguage it .it - -# LanguagePriority allows you to give precedence to some languages -# in case of a tie during content negotiation. -# Just list the languages in decreasing order of preference. - -LanguagePriority en fr de -</pre> - -Here, a request for "foo.html" matched against "foo.html.en" and -"foo.html.fr" would return an French document to a browser that -indicated a preference for French, or an English document otherwise. -In fact, a request for "foo" matched against "foo.html.en", -"foo.html.fr", "foo.ps.en", "foo.pdf.de", and "foo.txt.it" would do -just what you expect - treat those suffices as a database and compare -the request to it, returning the best match. The languages and data -types share the same suffix name space. - -<p> - -Note that this machinery only comes into play if the file which the -user attempted to retrieve does <em>not</em> exist by that name; if it -does, it is simply retrieved as usual. (So, someone who actually asks -for <code>foo.jpeg</code>, as opposed to <code>foo</code>, never gets -<code>foo.gif</code>). - -<P><HR><P> -<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> -<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> - -</body> </html> diff --git a/docs/manual/content-negotiation.html.en b/docs/manual/content-negotiation.html.en deleted file mode 100644 index 20825f3661..0000000000 --- a/docs/manual/content-negotiation.html.en +++ /dev/null @@ -1,216 +0,0 @@ -<html> -<head> -<title>Apache server Content arbitration: MultiViews and *.var files</title> -</head> - -<body> -<IMG SRC="../images/apache_sub.gif" ALT=""> -<h3>Content Arbitration: MultiViews and *.var files</h3> - -The HTTP standard allows clients (i.e., browsers like Mosaic or -Netscape) to specify what data formats they are prepared to accept. -The intention is that when information is available in multiple -variants (e.g., in different data formats), servers can use this -information to decide which variant to send. This feature has been -supported in the CERN server for a while, and while it is not yet -supported in the NCSA server, it is likely to assume a new importance -in light of the emergence of HTML3 capable browsers. <p> - -The Apache module <A HREF="mod_negotiation.html">mod_negotiation</A> handles -content negotiation in two different ways; special treatment for the -pseudo-mime-type <code>application/x-type-map</code>, and the -MultiViews per-directory Option (which can be set in srm.conf, or in -.htaccess files, as usual). These features are alternate user -interfaces to what amounts to the same piece of code (in the new file -<code>http_mime_db.c</code>) which implements the content negotiation -portion of the HTTP protocol. <p> - -Each of these features allows one of several files to satisfy a -request, based on what the client says it's willing to accept; the -differences are in the way the files are identified: - -<ul> - <li> A type map (i.e., a <code>*.var</code> file) names the files - containing the variants explicitly - <li> In a MultiViews search, the server does an implicit filename - pattern match, and chooses from among the results. -</ul> - -Apache also supports a new pseudo-MIME type, -text/x-server-parsed-html3, which is treated as text/html;level=3 -for purposes of content negotiation, and as server-side-included HTML -elsewhere. - -<h3>Type maps (*.var files)</h3> - -A type map is a document which is typed by the server (using its -normal suffix-based mechanisms) as -<code>application/x-type-map</code>. Note that to use this feature, -you've got to have an <code>AddType</code> some place which defines a -file suffix as <code>application/x-type-map</code>; the easiest thing -may be to stick a -<pre> - - AddType application/x-type-map var - -</pre> -in <code>srm.conf</code>. See comments in the sample config files for -details. <p> - -Type map files have an entry for each available variant; these entries -consist of contiguous RFC822-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, e.g., -<pre> - - URI: foo; vary="type,language" - - URI: foo.en.html - Content-type: text/html; level=2 - Content-language: en - - URI: foo.fr.html - Content-type: text/html; level=2 - Content-language: fr - -</pre> -If the variants have different qualities, that may be indicated by the -"qs" parameter, as in this picture (available as jpeg, gif, or ASCII-art): -<pre> - - URI: foo; vary="type,language" - - 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> - -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 --- level may be specified, along with "qs". These - are often referred to as MIME types; typical media types are - <code>image/gif</code>, <code>text/plain</code>, or - <code>text/html; level=3</code>. - <dt> <code>Content-language:</code> - <dd> The language of the variant, specified as an internet standard - language code (e.g., <code>en</code> for English, - <code>kr</code> for Korean, etc.). - <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. - For compressed files (the only case where this generally comes - up), content encoding should be - <code>x-compress</code>, or <code>gzip</code>, as appropriate. - <dt> <code>Content-length:</code> - <dd> The size of the file. Clients can ask to receive a given media - type only if the variant isn't too big; specifying a content - length in the map allows the server to compare against these - thresholds without checking the actual file. -</dl> - -<h3>Multiviews</h3> - -This is a per-directory option, meaning it can be set with an -<code>Options</code> directive within a <code><Directory></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. (Fixing this is a one-line change to -<code>httpd.h</code>). - -<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 *not* 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, and forwards them along. - -<p> - -This applies 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 by the globbing is a CGI script, it's not -obvious what should happen. My code gives that case gets 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. This is the only jiggering of quality ratings done by the -MultiViews code; aside from that, all Qualities in the synthesized -type maps are 1.0. - -<p> - -<B>New as of 0.8:</B> Documents in multiple languages can also be resolved through the use -of the <code>AddLanguage</code> and <code>LanguagePriority</code> -directives: - -<pre> -AddLanguage en .en -AddLanguage fr .fr -AddLanguage de .de -AddLanguage da .da -AddLanguage el .el -AddLanguage it .it - -# LanguagePriority allows you to give precedence to some languages -# in case of a tie during content negotiation. -# Just list the languages in decreasing order of preference. - -LanguagePriority en fr de -</pre> - -Here, a request for "foo.html" matched against "foo.html.en" and -"foo.html.fr" would return an French document to a browser that -indicated a preference for French, or an English document otherwise. -In fact, a request for "foo" matched against "foo.html.en", -"foo.html.fr", "foo.ps.en", "foo.pdf.de", and "foo.txt.it" would do -just what you expect - treat those suffices as a database and compare -the request to it, returning the best match. The languages and data -types share the same suffix name space. - -<p> - -Note that this machinery only comes into play if the file which the -user attempted to retrieve does <em>not</em> exist by that name; if it -does, it is simply retrieved as usual. (So, someone who actually asks -for <code>foo.jpeg</code>, as opposed to <code>foo</code>, never gets -<code>foo.gif</code>). - -<P><HR><P> -<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> -<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> - -</body> </html> diff --git a/docs/manual/custom-error.html b/docs/manual/custom-error.html deleted file mode 100644 index 31c955a2c4..0000000000 --- a/docs/manual/custom-error.html +++ /dev/null @@ -1,109 +0,0 @@ -<HTML> -<HEAD> -<TITLE>Ccustom error responses</TITLE> -</HEAD> - -<BODY> -<IMG SRC="../images/apache_sub.gif" ALT=""> -<H1>Custom error responses</H1> -<DL> -<DT>Purpose -<DD>Additional functionality. Allows webmasters to configure the response of -Apache to some error or problem.<BR> -<P>Customizable responses can be defined to be activated in the event of a -server detected error or problem.<BR> -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). -<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><BR> -<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.<BR>To achieve this, Apache will define new CGI-like environment -variables, e.g. -<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> - -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.<p> - -<DT>Configuration -<DD><em>file: </em>server configuration<BR> -<P>Here are some examples... -<blockquote><code> -ErrorDocument 500 /cgi-bin/crash-recover <br> -ErrorDocument 500 "Sorry, our script crashed because %s. 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> -The syntax is, <p> -<code><A HREF="core.html#errordocument">ErrorDocument</A></code> -<3-digit-code> action <p> - -where the action can be, -<OL> -<LI>Text to be displayed.<BR>Prefix the text with a quote ("). Whatever -follows the quote is displayed. If the error/problem produced any additional -information, it can be specified using <code>%s</code>. -<em>Note: the (") prefix isn't displayed.</em> -<LI>An external URL to redirect to. -<LI>A local URL to redirect to. -</OL> -<P><code>ErrorDocument</code> definitions are sensitive to a -<code>SIGHUP</code>, so you can change any of the definitions or add new ones -prior to sending a <code>SIGHUP</code> (kill -1) signal. -</DL> -<P><HR><P> - -<h2>Custom error responses and redirects</H2> -<DL> -<DT>Purpose -<DD>Apache's behaviour to redirected URLs has been modified so that additional -environment variables are available to a script/server-include.<p> - -<DT>Old behaviour -<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 behaviour -<DD>A new batch of environment variables will be initialized for use by a -script which has been redirected to.<BR> -Each new variable will have the prefix <code>REDIRECT_</code>.<BR> -REDIRECT_ environment variables are created from the CGI environment -variables which existed prior to the redirect, they are renamed with a -REDIRECT_ prefix, i.e. HTTP_USER_AGENT -> REDIRECT_HTTP_USER_AGENT.<BR> -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.<BR> -Logging: both the original URL and the URL being redirected to, will -now be logged correctly in the access log.<p> -</DL> -<P><HR> - -<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> -<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> -</BODY> -</HTML> diff --git a/docs/manual/custom-error.html.en b/docs/manual/custom-error.html.en deleted file mode 100644 index 31c955a2c4..0000000000 --- a/docs/manual/custom-error.html.en +++ /dev/null @@ -1,109 +0,0 @@ -<HTML> -<HEAD> -<TITLE>Ccustom error responses</TITLE> -</HEAD> - -<BODY> -<IMG SRC="../images/apache_sub.gif" ALT=""> -<H1>Custom error responses</H1> -<DL> -<DT>Purpose -<DD>Additional functionality. Allows webmasters to configure the response of -Apache to some error or problem.<BR> -<P>Customizable responses can be defined to be activated in the event of a -server detected error or problem.<BR> -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). -<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><BR> -<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.<BR>To achieve this, Apache will define new CGI-like environment -variables, e.g. -<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> - -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.<p> - -<DT>Configuration -<DD><em>file: </em>server configuration<BR> -<P>Here are some examples... -<blockquote><code> -ErrorDocument 500 /cgi-bin/crash-recover <br> -ErrorDocument 500 "Sorry, our script crashed because %s. 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> -The syntax is, <p> -<code><A HREF="core.html#errordocument">ErrorDocument</A></code> -<3-digit-code> action <p> - -where the action can be, -<OL> -<LI>Text to be displayed.<BR>Prefix the text with a quote ("). Whatever -follows the quote is displayed. If the error/problem produced any additional -information, it can be specified using <code>%s</code>. -<em>Note: the (") prefix isn't displayed.</em> -<LI>An external URL to redirect to. -<LI>A local URL to redirect to. -</OL> -<P><code>ErrorDocument</code> definitions are sensitive to a -<code>SIGHUP</code>, so you can change any of the definitions or add new ones -prior to sending a <code>SIGHUP</code> (kill -1) signal. -</DL> -<P><HR><P> - -<h2>Custom error responses and redirects</H2> -<DL> -<DT>Purpose -<DD>Apache's behaviour to redirected URLs has been modified so that additional -environment variables are available to a script/server-include.<p> - -<DT>Old behaviour -<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 behaviour -<DD>A new batch of environment variables will be initialized for use by a -script which has been redirected to.<BR> -Each new variable will have the prefix <code>REDIRECT_</code>.<BR> -REDIRECT_ environment variables are created from the CGI environment -variables which existed prior to the redirect, they are renamed with a -REDIRECT_ prefix, i.e. HTTP_USER_AGENT -> REDIRECT_HTTP_USER_AGENT.<BR> -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.<BR> -Logging: both the original URL and the URL being redirected to, will -now be logged correctly in the access log.<p> -</DL> -<P><HR> - -<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> -<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> -</BODY> -</HTML> diff --git a/docs/manual/developer/API.html b/docs/manual/developer/API.html deleted file mode 100644 index f860996e47..0000000000 --- a/docs/manual/developer/API.html +++ /dev/null @@ -1,988 +0,0 @@ -<!--%hypertext --> -<html><head> -<title>Apache API notes</title> -</head> -<body> -<!--/%hypertext --> -<h1>Apache API notes</h1> - -These are some notes on the Apache API and the data structures you -have to deal with, etc. 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, etc.</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 -> 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> (i.e., 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 recognise <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, etc., 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, <i>en masse</i>, 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 */ -}; -</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>table_get</code> and <code>table_set</code> routines. <p> - -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><Directory></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, etc. */ - int method_number; /* M_GET, M_POST, etc. */ - - /* 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, etc. */ - 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 (i.e., 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>sub_req_lookup_file</code> and - <code>sub_req_lookup_uri</code>; this constructs 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>run_sub_request</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>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>rputc</code> -and <code>rprintf</code>, for internally generated output, and -<code>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>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>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->method_number != M_GET) return DECLINED; - if (r->finfo.st_mode == 0) return NOT_FOUND; - - if ((errstatus = set_content_length (r, r->finfo.st_size)) - || (errstatus = set_last_modified (r, r->finfo.st_mtime))) - return errstatus; - - f = fopen (r->filename, "r"); - - if (f == NULL) { - log_reason("file permissions deny server access", - r->filename, r); - return FORBIDDEN; - } - - register_timeout ("send", r); - send_http_header (r); - - if (!r->header_only) send_fd (f, r); - pfclose (r->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>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>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>auth_type</code>, - <code>auth_name</code>, and <code>requires</code>. - <li> Common routines, to handle the protocol end of things, at least - for HTTP basic authentication (<code>get_basic_auth_pw</code>, - which sets the <code>connection->user</code> structure field - automatically, and <code>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->prev</code> and <code>r->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> - -One of the problems of writing and designing a server-pool server is -that of preventing leakage, that is, allocating resources (memory, -open files, etc.), 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> - -The way this works is as follows: the memory which is allocated, file -opened, etc., 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> - -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> - -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> - -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">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>palloc</code> is generally faster than -<code>malloc</code>.<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. - -<h3>Allocation of memory in pools</h3> - -Memory is allocated to pools by calling the function -<code>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: - -<pre> -int my_handler(request_rec *r) -{ - struct my_structure *foo; - ... - - foo = (foo *)palloc (r->pool, sizeof(my_structure)); -} -</pre> - -Note that <em>there is no <code>pfree</code></em> --- -<code>palloc</code>ed memory is freed only when the associated -resource pool is cleared. This means that <code>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> - -(It also raises the possibility that heavy use of <code>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). - -<h3>Allocating initialized memory</h3> - -There are functions which allocate initialized memory, and are -frequently useful. The function <code>pcalloc</code> has the same -interface as <code>palloc</code>, but clears out the memory it -allocates before it returns it. The function <code>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>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: - -<pre> - pstrcat (r->pool, "foo", "/", "bar", NULL); -</pre> - -returns a pointer to 8 bytes worth of memory, initialized to -<code>"foo/bar"</code>. - -<h3>Tracking open files, etc.</h3> - -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>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>, e.g., - -<pre> - ... - FILE *f = pfopen (r->pool, r->filename, "r"); - - if (f == NULL) { ... } else { ... } -</pre> - -There is also a <code>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> - -Unlike the case for memory, there <em>are</em> functions to close -files allocated with <code>pfopen</code>, and <code>popenf</code>, -namely <code>pfclose</code> and <code>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>pfopen</code> and -<code>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> - -(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). - -<h3>Other sorts of resources --- cleanup functions</h3> - -More text goes here. Describe the the cleanup primitives in terms of -which the file stuff is implemented; also, <code>spawn_process</code>. - -<h3>Fine control --- creating and dealing with sub-pools, with a note -on sub-requests</h3> - -On rare occasions, too-free use of <code>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>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>clear_pool</code> and <code>destroy_pool</code>, respectively. -(The difference is that <code>clear_pool</code> frees resources -associated with the pool, while <code>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>sub_req_lookup_...</code> functions) -is <code>destroy_sub_request</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>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 -> 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><Directory></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><Directory /></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><Directory></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>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 *) palloc (p, sizeof(mime_dir_config)); - - new->forced_types = make_table (p, 4); - new->encoding_types = 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 *)palloc (p, sizeof(mime_dir_config)); - - new->forced_types = overlay_tables (p, subdir->forced_types, - parent_dir->forced_types); - new->encoding_types = overlay_tables (p, subdir->encoding_types, - parent_dir->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 (e.g., 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; - table_set (m->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 (e.g., 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>get_module_config</code> function. - -<pre> -int find_ct(request_rec *r) -{ - int i; - char *fn = pstrdup (r->pool, r->filename); - mime_dir_config *conf = (mime_dir_config *) - get_module_config(r->per_dir_config, &mime_module); - char *type; - - if (S_ISDIR(r->finfo.st_mode)) { - r->content_type = DIR_MAGIC_TYPE; - return OK; - } - - if((i=rind(fn,'.')) < 0) return DECLINED; - ++i; - - if ((type = table_get (conf->encoding_types, &fn[i]))) - { - r->content_encoding = type; - - /* go back to previous extension to try to use it as a type */ - - fn[i-1] = '\0'; - if((i=rind(fn,'.')) < 0) return OK; - ++i; - } - - if ((type = table_get (conf->forced_types, &fn[i]))) - { - r->content_type = type; - } - - return OK; -} - -</pre> - -<h3><a name="servconf">Side notes --- per-server configuration, virtual servers, etc.</a></h3> - -The basic ideas behind per-server module configuration are basically -the same as those for per-directory configuration; there is a creation -function and a merge function, the latter being invoked where a -virtual server has partially overridden the base server configuration, -and a combined structure must be computed. (As with per-directory -configuration, the default if no merge function is specified, and a -module is configured in some virtual server, is that the base -configuration is simply ignored). <p> - -The only substantial difference is that when a command needs to -configure the per-server private module data, it needs to go to the -<code>cmd_parms</code> data to get at it. Here's an example, from the -alias module, which also indicates how a syntax error can be returned -(note that the per-directory configuration argument to the command -handler is declared as a dummy, since the module doesn't actually have -per-directory config data): - -<pre> -char *add_redirect(cmd_parms *cmd, void *dummy, char *f, char *url) -{ - server_rec *s = cmd->server; - alias_server_conf *conf = (alias_server_conf *) - get_module_config(s->module_config,&alias_module); - alias_entry *new = push_array (conf->redirects); - - if (!is_url (url)) return "Redirect to non-URL"; - - new->fake = f; new->real = url; - return NULL; -} -</pre> -<!--%hypertext --> -</body></html> -<!--/%hypertext --> diff --git a/docs/manual/dns-caveats.html b/docs/manual/dns-caveats.html deleted file mode 100644 index e535a36187..0000000000 --- a/docs/manual/dns-caveats.html +++ /dev/null @@ -1,190 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<html><head> -<title>Issues Regarding DNS and Apache</title> -</head><body> - -<!--#include virtual="header.html" --> -<h1>Issues Regarding DNS and Apache</h1> - -<p>This page could be summarized with the statement: <i>don't require -Apache to use DNS for any parsing of the configuration files</i>. -If Apache has to use DNS to parse the configuration files then your -server may be subject to reliability problems (it might not boot), or -denial and theft of service attacks (including users able to steal hits -from other users). - -<h3>A Simple Example</h3> - -Consider this configuration snippet: - -<blockquote><pre> - <VirtualHost www.abc.dom> - ServerAdmin webgirl@abc.dom - DocumentRoot /www/abc - </VirtualHost> -</pre></blockquote> - -<p>In order for Apache to function properly it absolutely needs -to have two pieces of information about each virtual host: the -<a href="mod/core.html#servername"><code>ServerName</code></a> -and at least one ip address that the server -responds to. This example does not include the ip address, so Apache -must use DNS to find the address of <code>www.abc.dom</code>. If for -some reason DNS is not available at the time your server is parsing its -config file, then this virtual host <b>will not be configured</b>. It -won't be able to respond to any hits to this virtual host (prior to -Apache version 1.2 the server would not even boot). - -<p>Suppose that <code>www.abc.dom</code> has address 10.0.0.1. Then -consider this configuration snippet: - -<blockquote><pre> - <VirtualHost 10.0.0.1> - ServerAdmin webgirl@abc.dom - DocumentRoot /www/abc - </VirtualHost> -</pre></blockquote> - -<p>Now Apache needs to use reverse DNS to find the <code>ServerName</code> -for this virtualhost. If that reverse lookup fails then it will partially -disable the virtualhost (prior to Apache version 1.2 the server would not -even boot). If the virtual host is name-based then it will effectively -be totally disabled, but if it is ip-based then it will mostly work. -However if Apache should ever have to generate a full URL for the server -which includes the server name then it will fail to generate a valid URL. - -<p>Here is a snippet that avoids both of these problems. - -<blockquote><pre> - <VirtualHost 10.0.0.1> - ServerName www.abc.dom - ServerAdmin webgirl@abc.dom - DocumentRoot /www/abc - </VirtualHost> -</pre></blockquote> - -<h3>Denial of Service</h3> - -<p>There are (at least) two forms that denial of service can come in. -If you are running a version of Apache prior to version 1.2 then your -server will not even boot if one of the two DNS lookups mentioned above -fails for any of your virtual hosts. In some cases this DNS lookup may -not even be under your control. For example, if <code>abc.dom</code> -is one of your customers and they control their own DNS then they -can force your (pre-1.2) server to fail while booting simply by deleting the -<code>www.abc.dom</code> record. - -<p>Another form is far more insidious. Consider this configuration -snippet: - -<blockquote><pre> - <VirtualHost www.abc.dom> - ServerAdmin webgirl@abc.dom - DocumentRoot /www/abc - </VirtualHost> -</pre></blockquote> - -<blockquote><pre> - <VirtualHost www.def.dom> - ServerAdmin webguy@def.dom - DocumentRoot /www/def - </VirtualHost> -</pre></blockquote> - -<p>Suppose that you've assigned 10.0.0.1 to <code>www.abc.dom</code> and -10.0.0.2 to <code>www.def.dom</code>. Furthermore, suppose that -<code>def.com</code> has control of their own DNS. With this config -you have put <code>def.com</code> into a position where they can steal -all traffic destined to <code>abc.com</code>. To do so, all they have to -do is set <code>www.def.dom</code> to 10.0.0.1. -Since they control their own DNS you can't stop them from pointing the -<code>www.def.com</code> record wherever they wish. - -<p>Requests coming in to 10.0.0.1 (including all those where users typed -in URLs of the form <code>http://www.abc.dom/whatever</code>) will all be -served by the <code>def.com</code> virtual host. To better understand why -this happens requires a more in-depth discussion of how Apache matches -up incoming requests with the virtual host that will serve it. A rough -document describing this <a href="vhosts-in-depth.html"> is available</a>. - -<h3>The "main server" Address</h3> - -<p>The addition of <a href="host.html">non-IP-based virtual host -support</a> in Apache 1.1 requires Apache to know the IP address(es) of -the host that httpd is running on. To get this address it uses either -the global <code>ServerName</code> (if present) or calls the C function -<code>gethostname</code> (which should return the same as typing -"hostname" at the command prompt). Then it performs a DNS lookup on -this address. At present there is no way to avoid this lookup. - -<p>If you fear that this lookup might fail because your DNS server is down -then you can insert the hostname in <code>/etc/hosts</code> (where you -probably already have it so that the machine can boot properly). Then -ensure that your machine is configured to use <code>/etc/hosts</code> -in the event that DNS fails. Depending on what OS you are using this -might be accomplished by editing <code>/etc/resolv.conf</code>, or maybe -<code>/etc/nsswitch.conf</code>. - -<p>If your server doesn't have to perform DNS for any other reason -then you might be able to get away with running Apache with the -<code>HOSTRESORDER</code> environment variable set to "local". This all -depends on what OS and resolver libraries you are using. It also affects -CGIs unless you use <a href="mod/mod_env.html"><code>mod_env</code></a> -to control the environment. It's best to consult the man pages or FAQs -for your OS. - -<h3>The _default_ Address</h3> - -<p>Any address that happens to go to your webserver which doesn't match -the ip address of any of the webservers will be served from the "main" or -"default" server configurations. The "main" server configuration consists -of all those definitions appearing outside of any VirtualHost section. -You may want instead to define a <code><VirtualHost _default></code> -which returns 403 or 404 for all hits. - -<a name="tips"><h3>Tips to Avoid these problems</h3></a> - -<ul> -<li> use ip addresses in <code><VirtualHost></code> -<li> use ip addresses in <code>Listen</code> -<li> use ip addresses in <code>BindAddress</code> -<li> ensure all virtual hosts have an explicit <code>ServerName</code> -<li> create a <code><VirtualHost _default_></code> server that - has no pages to serve -</ul> - -<h3>Appendix: Future Directions</h3> - -<p>The situation regarding DNS is highly undesirable. For Apache -1.2 we've attempted to make the server at least continue booting -in the event of failed DNS, but it might not be the best we -can do. In any event requiring the use of explicit ip addresses in -configuration files is highly undesirable in today's Internet where <a -href="http://www.ietf.org/html.charters/pier-charter.html">renumbering -</a> is a necessity. - -<p>A possible work around to the theft of service attack described above -would be to perform a reverse DNS lookup on the ip address returned by -the forward lookup and compare the two names. In the event of a mismatch -the virtualhost would be disabled. This would require reverse DNS to be -configured properly (which is something that most admins are familiar with -because of the common use of "double-reverse" DNS lookups by FTP servers -and TCP wrappers). - -<p>In any event it doesn't seem possible to reliably boot a virtual-hosted -web server when DNS has failed unless IP addresses are used. Partial -solutions such as disabling portions of the configuration might be worse -than not booting at all depending on what the webserver is supposed -to accomplish. - -<p>As HTTP/1.1 is deployed and browsers and proxies start issuing the -<code>Host</code> header it will become possible to avoid the use of -ip-based virtual hosts entirely. In this event a webserver has no requirement -to do DNS lookups during configuration. But as of March 1997 these -features have not been deployed widely enough to be put into use on -critical webservers. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/dso.html b/docs/manual/dso.html deleted file mode 100644 index ecaf33f90f..0000000000 --- a/docs/manual/dso.html +++ /dev/null @@ -1,337 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML><HEAD> -<TITLE>Apache 1.3 Dynamic Shared Object (DSO) support</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>Apache 1.3 Dynamic Shared Object (DSO) support</H1> - -<P><HR><P> - -<address>Originally written by Ralf S. Engelschall, April 1998</address> - -<H3>Background</H3> - -<P>On modern Unix derivatives there exists a nifty mechanism usually - called dynamic linking/loading of Dynamic Shared Objects (DSO) which - provides a way to build a piece of program code in a special format - for loading it at run-time into the address space of an executable - program. - -<P>This loading can usually be done in two ways: Automatically by a - system program called <CODE>ld.so</CODE> when an executable program - is started or manually from within the executing program via a - programmatic system interface to the Unix loader through the system - calls <CODE>dlopen()/dlsym()</CODE>. - -<P>In the first way the DSO's are usually called "shared libraries" or - "DSO libraries" and named <CODE>libfoo.so</CODE> or - <CODE>libfoo.so.1.2</CODE>. They reside in a system directory - (usually <CODE>/usr/lib</CODE>) and the link to the executable - program is established at link-time by specifying <CODE>-lfoo</CODE> - to the linker command. This hardcodes library references into the - executable program file so that at start-time the Unix loader is able - to locate <CODE>libfoo.so</CODE> in <CODE>/usr/lib</CODE> or in paths - configured via the environment variable - <CODE>LD_LIBRARY_PATH</CODE>. It then resolves any (yet unresolved) - symbols in the executable program which are available in the DSO. - -<P>Symbols in the executable program are usually not referenced by the - DSO (because it's a reuseable library of general code) and hence no - further resolving has to be done. The executable program has no need - to do anything on its own to use the symbols from the DSO because the - complete resolving is done by the Unix loader. (In fact, the code to - invoke <CODE>ld.so</CODE> is part of the run-time startup code which - is linked into every executable program which has been bound - non-static). The advantage of dynamic loading of common library code - is obvious: the library code needs to be stored only once, in a - system library like <CODE>libc.so</CODE>, saving disk space for every - program. - -<P>In the second way the DSO's are usually called "shared objects" or - "DSO files" and can be named with an arbitrary extension (although - the canonical name is <CODE>foo.so</CODE>). These files usually stay - inside a program-specific directory and there is no automatically - established link to the executable program where they are - used. Instead the executable program manually loads the DSO at - run-time into its address space via <CODE>dlopen()</CODE>. At this - time no resolving of symbols from the DSO for the executable program - is done. But instead the Unix loader automatically resolves any (yet - unresolved) symbols in the DSO from the set of symbols exported by - the executable program and its already loaded DSO libraries - (especially all symbols from the ubiquitous <CODE>libc.so</CODE>). - This way the DSO gets knowledge of the executable program's symbol - set as if it had been statically linked with it in the first place. - -<P>Finally, to take advantage of the DSO's API the executable program - has to resolve particular symbols from the DSO via - <CODE>dlsym()</CODE> for later use inside dispatch tables etc. In - other words: The executable program has to manually resolve every - symbol it needs to be able to use it. The advantage of such a - mechanism is that optional program parts need not be loaded (and thus - do not spend memory) until they are needed by the program in - question. When required, these program parts can be loaded - dynamically to extend the base program's functionality. - -<P>Although this DSO mechanism sounds straightforward there is at least one - difficult step here: The resolving of symbols from the executable program for - the DSO when using a DSO to extend a program (the second way). Why? Because - `reverse resolving' DSO symbols from the executable program's symbol set is - against the library design (where the library has no knowledge about the - programs it is used by) and is neither available under all platforms nor - standardized. In practice the executable program's global symbols are often - not re-exported and thus not available for use in a DSO. Finding a way to - force the linker to export all global symbols is the main problem one has to - solve when using DSO for extending a program at run-time. - -<H3>Practical Usage</H3> - -<P>The shared library approach is the typical one, because it is what the DSO - mechanism was designed for, hence it is used for nearly all types of - libraries the operating system provides. On the other hand using shared - objects for extending a program is not used by a lot of programs. - -<P>As of 1998 there are only a few software packages available which use the DSO - mechanism to actually extend their functionality at run-time: Perl 5 (via its - XS mechanism and the DynaLoader module), GIMP, Netscape Server, etc. - Starting with version 1.3, Apache joined the crew, because Apache already - uses a module concept to extend its functionality and internally uses a - dispatch-list-based approach to link external modules into the Apache core - functionality. So, Apache is really predestined for using DSO to load its - modules at run-time. - -<P>As of Apache 1.3, the configuration system supports two optional features for - taking advantage of the modular DSO approach: compilation of the Apache core - program into a DSO library for shared usage and compilation of the Apache - modules into DSO files for explicit loading at run-time. - -<H3>Implementation</H3> - -<P> The DSO support for loading individual Apache modules is based on a module - named mod_so.c which has to be statically compiled into the Apache core. It - is the only module besides http_core.c which cannot be put into a DSO itself - (bootstrapping!). Practically all other distributed Apache modules then can - then be placed into a DSO by individually enabling the DSO build for them via - configure's --enable-shared option (see ../INSTALL file) or by changing the - `AddModule' command in src/Configuration.tmpl into a `SharedModule' command - (see ./INSTALL file). After a module is compiled into a DSO named mod_foo.so - you can use mod_so's `LoadModule' command in your httpd.conf file to load - this module at server startup or restart. - -<P>To simplify this creation of DSO files for Apache modules (especially for - third-party modules) a new support program named `apxs' is available. It can - be used to build DSO based modules _outside of_ the Apache source tree. The - idea is simple: When installing Apache the configure's "make install" - procedure installs the Apache C header files and puts the platform-dependend - compiler and linker flags for building DSO files into the `apxs' program. - This way the user can use `apxs' to compile his Apache module sources without - the Apache distribution source tree and without having to fiddle with the - platform-dependend compiler and linker flags for DSO support. - -<P>To place the complete Apache core program into a DSO library (only required - on some of the supported platforms to force the linker to export the apache - core symbols -- a prerequisite for the DSO modularization) the rule - SHARED_CORE has to be enabled via configure's --enable-rule=SHARED_CORE - option (see ../INSTALL file) or by changing the Rule command in - Configuration.tmpl to "Rule SHARED_CORE=yes" (see ./INSTALL file). The Apache - core code is then placed into a DSO library named libhttpd.so. Because one - cannot link a DSO against static libraries, an additional executable program - named libhttpd.ep is created which both binds this static code and provides a - stub for the main() function. Finally the httpd executable program itself is - replaced by a bootstrapping code which automatically makes sure the Unix - loader is able to load and start libhttpd.ep by providing the LD_LIBRARY_PATH - to libhttpd.so. - -<H3>Supported Platforms</H3> - -<P>Apache's src/Configure script currently has only limited built-in knowledge - on how to compile DSO files because (as already mentioned) this is heavily - platform-dependent. Nevertheless all major Unix platforms are supported. The - definitive current state (May 1998) is this: - -<PRE> - Out-of-the-box supported platforms: - (actually tested versions in parenthesis) - - o FreeBSD (2.1.5, 2.2.5, 2.2.6) - o OpenBSD (2.x) - o NetBSD (1.3.1) - o Linux (Debian/1.3.1, RedHat/4.2) - o Solaris (2.4, 2.5.1, 2.6) - o SunOS (4.1.3) - o OSF1 (4.0) - o IRIX (6.2) - o HP/UX (10.20) - o UnixWare (2.01, 2.1.2) - o AIX (3.2, 4.1.5, 4.2, 4.3) - o ReliantUNIX/SINIX (5.43) - o SVR4 (-) - - Explicitly unsupported platforms: - - o Ultrix: There is no dlopen-style interface under this platform. -</PRE> - - -<H3>Usage Summary</H3> - -<P>To give you an overview of the DSO features of Apache 1.3, here is - a short and concise summary: - -<OL> - -<LI>Placing the Apache core code (all the stuff which usually forms - the httpd binary) into a DSO libhttpd.so, an executable program - libhttpd.ep and a bootstrapping executable program httpd (Notice: - this is only required on some of the supported platforms to force - the linker to export the Apache core symbols, which in turn is a - prerequisite for the DSO modularization): - -<PRE> - o Build and install via configure (preferred): - $ ./configure --prefix=/path/to/install - --enable-rule=SHARED_CORE ... - $ make install - - o Build and install manually: - - Edit src/Configuration: - << "Rule SHARED_CORE=default" - >> "Rule SHARED_CORE=yes" - << "EXTRA_CFLAGS= " - >> "EXTRA_CFLAGS= -DSHARED_CORE_DIR=\"/path/to/install/libexec\" - $ make - $ cp src/libhttpd.so* /path/to/install/libexec/ - $ cp src/libhttpd.ep /path/to/install/libexec/ - $ cp src/httpd /path/to/install/bin/ -</PRE> - -<LI>Build and install a distributed Apache module, say mod_foo.c, - into its own DSO mod_foo.so: - -<PRE> - o Build and install via configure (preferred): - $ ./configure --prefix=/path/to/install - --enable-shared=foo - $ make install - - o Build and install manually: - - Edit src/Configuration: - << "AddModule modules/xxxx/mod_foo.o" - >> "SharedModule modules/xxxx/mod_foo.so" - $ make - $ cp src/xxxx/mod_foo.so /path/to/install/libexec - - Edit /path/to/install/etc/httpd.conf - >> "LoadModule foo_module /path/to/install/libexec/mod_foo.so" -</PRE> - -<LI>Build and install a third-party Apache module, say mod_foo.c, - into its own DSO mod_foo.so - -<PRE> - o Build and install via configure (preferred): - $ ./configure --add-module=/path/to/3rdparty/mod_foo.c - --enable-shared=foo - $ make install - - o Build and install manually: - $ cp /path/to/3rdparty/mod_foo.c /path/to/apache-1.3/src/modules/extra/ - - Edit src/Configuration: - >> "SharedModule modules/extra/mod_foo.so" - $ make - $ cp src/xxxx/mod_foo.so /path/to/install/libexec - - Edit /path/to/install/etc/httpd.conf - >> "LoadModule foo_module /path/to/install/libexec/mod_foo.so" -</PRE> - -<LI>Build and install a third-party Apache module, say mod_foo.c, - into its own DSO mod_foo.so _outside of_ the Apache source tree: - -<PRE> - o Build and install via APXS: - $ cd /path/to/3rdparty - $ apxs -c mod_foo.c - $ apxs -i -a -n foo mod_foo.so -</PRE> - -</UL> - -<H3>Advantages & Disadvantages</H3> - -<P>The above DSO based features of Apache 1.3 have the following advantages: - -<UL> -<LI> The server package is more flexible at run-time because the actual server - process can be assembled at run-time via LoadModule httpd.conf - configuration commands instead of Configuration AddModule commands at - build-time. For instance this way one is able to run different server - instances (standard & SSL version, minimalistic & powered up version - [mod_perl, PHP3], etc.) with only one Apache installation. - -<LI> The server package can be easily extended with third-party modules even - after installation. This is at least a great benefit for vendor package - maintainers who can create a Apache core package and additional packages - containing extensions like PHP3, mod_perl, mod_fastcgi, etc. - -<LI> Easier Apache module prototyping because with the DSO/APXS pair you can - both work outside the Apache source tree and only need an `apxs -i' - command followed by a `apachectl restart' to bring a new version of your - currently developed module into the running Apache server. -</UL> - -<P>DSO has the following disadvantages: - -<UL> -<LI> The DSO mechanism cannot be used on every platform because not all - operating systems support dynamic loading. - -<LI> The server is approximately 20% slower at startup time because of the - symbol resolving overhead the Unix loader now has to do. - -<LI> The server is approximately 5% slower at execution time under some - platforms because position independed code (PIC) sometimes needs - complicated assembler tricks for relative addressing which are not - necessarily as fast as absolute addressing. - -<LI> Because DSO modules cannot be linked against other DSO-based libraries - (ld -lfoo) on all platforms (for instance a.out-based platforms usually - don't provide this functionality while ELF-based platforms do) you cannot - use the DSO mechanism for all types of modules. Or in other words, - modules compiled as DSO files are restricted to only use symbols from the - Apache core, from the C library (libc) and all other dynamic or static - libraries used by the Apache core, or from static library archives - (libfoo.a) containing position independend code. The only chance to use - other code is to either make sure the Apache core itself already contains - a reference to it or loading the code yourself via dlopen(). - -<LI> Under some platforms (many SVR4 systems) there is no way to force the - linker to export all global symbols for use in DSO's when linking the - Apache httpd executable program. But without the visibility of the Apache - core symbols no standard Apache module could be used as a DSO. The only - chance here is to use the SHARED_CORE feature because this way the global - symbols are forced to be exported. As a consequence the Apache - src/Configure script automatically enforces SHARED_CORE on these - platforms when DSO features are used in the Configuration file or on the - configure command line. -</UL> - -<PRE> - Ralf S. Engelschall - rse@engelschall.com - www.engelschall.com -</PRE> - - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - - diff --git a/docs/manual/dso.html.en b/docs/manual/dso.html.en deleted file mode 100644 index ecaf33f90f..0000000000 --- a/docs/manual/dso.html.en +++ /dev/null @@ -1,337 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML><HEAD> -<TITLE>Apache 1.3 Dynamic Shared Object (DSO) support</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>Apache 1.3 Dynamic Shared Object (DSO) support</H1> - -<P><HR><P> - -<address>Originally written by Ralf S. Engelschall, April 1998</address> - -<H3>Background</H3> - -<P>On modern Unix derivatives there exists a nifty mechanism usually - called dynamic linking/loading of Dynamic Shared Objects (DSO) which - provides a way to build a piece of program code in a special format - for loading it at run-time into the address space of an executable - program. - -<P>This loading can usually be done in two ways: Automatically by a - system program called <CODE>ld.so</CODE> when an executable program - is started or manually from within the executing program via a - programmatic system interface to the Unix loader through the system - calls <CODE>dlopen()/dlsym()</CODE>. - -<P>In the first way the DSO's are usually called "shared libraries" or - "DSO libraries" and named <CODE>libfoo.so</CODE> or - <CODE>libfoo.so.1.2</CODE>. They reside in a system directory - (usually <CODE>/usr/lib</CODE>) and the link to the executable - program is established at link-time by specifying <CODE>-lfoo</CODE> - to the linker command. This hardcodes library references into the - executable program file so that at start-time the Unix loader is able - to locate <CODE>libfoo.so</CODE> in <CODE>/usr/lib</CODE> or in paths - configured via the environment variable - <CODE>LD_LIBRARY_PATH</CODE>. It then resolves any (yet unresolved) - symbols in the executable program which are available in the DSO. - -<P>Symbols in the executable program are usually not referenced by the - DSO (because it's a reuseable library of general code) and hence no - further resolving has to be done. The executable program has no need - to do anything on its own to use the symbols from the DSO because the - complete resolving is done by the Unix loader. (In fact, the code to - invoke <CODE>ld.so</CODE> is part of the run-time startup code which - is linked into every executable program which has been bound - non-static). The advantage of dynamic loading of common library code - is obvious: the library code needs to be stored only once, in a - system library like <CODE>libc.so</CODE>, saving disk space for every - program. - -<P>In the second way the DSO's are usually called "shared objects" or - "DSO files" and can be named with an arbitrary extension (although - the canonical name is <CODE>foo.so</CODE>). These files usually stay - inside a program-specific directory and there is no automatically - established link to the executable program where they are - used. Instead the executable program manually loads the DSO at - run-time into its address space via <CODE>dlopen()</CODE>. At this - time no resolving of symbols from the DSO for the executable program - is done. But instead the Unix loader automatically resolves any (yet - unresolved) symbols in the DSO from the set of symbols exported by - the executable program and its already loaded DSO libraries - (especially all symbols from the ubiquitous <CODE>libc.so</CODE>). - This way the DSO gets knowledge of the executable program's symbol - set as if it had been statically linked with it in the first place. - -<P>Finally, to take advantage of the DSO's API the executable program - has to resolve particular symbols from the DSO via - <CODE>dlsym()</CODE> for later use inside dispatch tables etc. In - other words: The executable program has to manually resolve every - symbol it needs to be able to use it. The advantage of such a - mechanism is that optional program parts need not be loaded (and thus - do not spend memory) until they are needed by the program in - question. When required, these program parts can be loaded - dynamically to extend the base program's functionality. - -<P>Although this DSO mechanism sounds straightforward there is at least one - difficult step here: The resolving of symbols from the executable program for - the DSO when using a DSO to extend a program (the second way). Why? Because - `reverse resolving' DSO symbols from the executable program's symbol set is - against the library design (where the library has no knowledge about the - programs it is used by) and is neither available under all platforms nor - standardized. In practice the executable program's global symbols are often - not re-exported and thus not available for use in a DSO. Finding a way to - force the linker to export all global symbols is the main problem one has to - solve when using DSO for extending a program at run-time. - -<H3>Practical Usage</H3> - -<P>The shared library approach is the typical one, because it is what the DSO - mechanism was designed for, hence it is used for nearly all types of - libraries the operating system provides. On the other hand using shared - objects for extending a program is not used by a lot of programs. - -<P>As of 1998 there are only a few software packages available which use the DSO - mechanism to actually extend their functionality at run-time: Perl 5 (via its - XS mechanism and the DynaLoader module), GIMP, Netscape Server, etc. - Starting with version 1.3, Apache joined the crew, because Apache already - uses a module concept to extend its functionality and internally uses a - dispatch-list-based approach to link external modules into the Apache core - functionality. So, Apache is really predestined for using DSO to load its - modules at run-time. - -<P>As of Apache 1.3, the configuration system supports two optional features for - taking advantage of the modular DSO approach: compilation of the Apache core - program into a DSO library for shared usage and compilation of the Apache - modules into DSO files for explicit loading at run-time. - -<H3>Implementation</H3> - -<P> The DSO support for loading individual Apache modules is based on a module - named mod_so.c which has to be statically compiled into the Apache core. It - is the only module besides http_core.c which cannot be put into a DSO itself - (bootstrapping!). Practically all other distributed Apache modules then can - then be placed into a DSO by individually enabling the DSO build for them via - configure's --enable-shared option (see ../INSTALL file) or by changing the - `AddModule' command in src/Configuration.tmpl into a `SharedModule' command - (see ./INSTALL file). After a module is compiled into a DSO named mod_foo.so - you can use mod_so's `LoadModule' command in your httpd.conf file to load - this module at server startup or restart. - -<P>To simplify this creation of DSO files for Apache modules (especially for - third-party modules) a new support program named `apxs' is available. It can - be used to build DSO based modules _outside of_ the Apache source tree. The - idea is simple: When installing Apache the configure's "make install" - procedure installs the Apache C header files and puts the platform-dependend - compiler and linker flags for building DSO files into the `apxs' program. - This way the user can use `apxs' to compile his Apache module sources without - the Apache distribution source tree and without having to fiddle with the - platform-dependend compiler and linker flags for DSO support. - -<P>To place the complete Apache core program into a DSO library (only required - on some of the supported platforms to force the linker to export the apache - core symbols -- a prerequisite for the DSO modularization) the rule - SHARED_CORE has to be enabled via configure's --enable-rule=SHARED_CORE - option (see ../INSTALL file) or by changing the Rule command in - Configuration.tmpl to "Rule SHARED_CORE=yes" (see ./INSTALL file). The Apache - core code is then placed into a DSO library named libhttpd.so. Because one - cannot link a DSO against static libraries, an additional executable program - named libhttpd.ep is created which both binds this static code and provides a - stub for the main() function. Finally the httpd executable program itself is - replaced by a bootstrapping code which automatically makes sure the Unix - loader is able to load and start libhttpd.ep by providing the LD_LIBRARY_PATH - to libhttpd.so. - -<H3>Supported Platforms</H3> - -<P>Apache's src/Configure script currently has only limited built-in knowledge - on how to compile DSO files because (as already mentioned) this is heavily - platform-dependent. Nevertheless all major Unix platforms are supported. The - definitive current state (May 1998) is this: - -<PRE> - Out-of-the-box supported platforms: - (actually tested versions in parenthesis) - - o FreeBSD (2.1.5, 2.2.5, 2.2.6) - o OpenBSD (2.x) - o NetBSD (1.3.1) - o Linux (Debian/1.3.1, RedHat/4.2) - o Solaris (2.4, 2.5.1, 2.6) - o SunOS (4.1.3) - o OSF1 (4.0) - o IRIX (6.2) - o HP/UX (10.20) - o UnixWare (2.01, 2.1.2) - o AIX (3.2, 4.1.5, 4.2, 4.3) - o ReliantUNIX/SINIX (5.43) - o SVR4 (-) - - Explicitly unsupported platforms: - - o Ultrix: There is no dlopen-style interface under this platform. -</PRE> - - -<H3>Usage Summary</H3> - -<P>To give you an overview of the DSO features of Apache 1.3, here is - a short and concise summary: - -<OL> - -<LI>Placing the Apache core code (all the stuff which usually forms - the httpd binary) into a DSO libhttpd.so, an executable program - libhttpd.ep and a bootstrapping executable program httpd (Notice: - this is only required on some of the supported platforms to force - the linker to export the Apache core symbols, which in turn is a - prerequisite for the DSO modularization): - -<PRE> - o Build and install via configure (preferred): - $ ./configure --prefix=/path/to/install - --enable-rule=SHARED_CORE ... - $ make install - - o Build and install manually: - - Edit src/Configuration: - << "Rule SHARED_CORE=default" - >> "Rule SHARED_CORE=yes" - << "EXTRA_CFLAGS= " - >> "EXTRA_CFLAGS= -DSHARED_CORE_DIR=\"/path/to/install/libexec\" - $ make - $ cp src/libhttpd.so* /path/to/install/libexec/ - $ cp src/libhttpd.ep /path/to/install/libexec/ - $ cp src/httpd /path/to/install/bin/ -</PRE> - -<LI>Build and install a distributed Apache module, say mod_foo.c, - into its own DSO mod_foo.so: - -<PRE> - o Build and install via configure (preferred): - $ ./configure --prefix=/path/to/install - --enable-shared=foo - $ make install - - o Build and install manually: - - Edit src/Configuration: - << "AddModule modules/xxxx/mod_foo.o" - >> "SharedModule modules/xxxx/mod_foo.so" - $ make - $ cp src/xxxx/mod_foo.so /path/to/install/libexec - - Edit /path/to/install/etc/httpd.conf - >> "LoadModule foo_module /path/to/install/libexec/mod_foo.so" -</PRE> - -<LI>Build and install a third-party Apache module, say mod_foo.c, - into its own DSO mod_foo.so - -<PRE> - o Build and install via configure (preferred): - $ ./configure --add-module=/path/to/3rdparty/mod_foo.c - --enable-shared=foo - $ make install - - o Build and install manually: - $ cp /path/to/3rdparty/mod_foo.c /path/to/apache-1.3/src/modules/extra/ - - Edit src/Configuration: - >> "SharedModule modules/extra/mod_foo.so" - $ make - $ cp src/xxxx/mod_foo.so /path/to/install/libexec - - Edit /path/to/install/etc/httpd.conf - >> "LoadModule foo_module /path/to/install/libexec/mod_foo.so" -</PRE> - -<LI>Build and install a third-party Apache module, say mod_foo.c, - into its own DSO mod_foo.so _outside of_ the Apache source tree: - -<PRE> - o Build and install via APXS: - $ cd /path/to/3rdparty - $ apxs -c mod_foo.c - $ apxs -i -a -n foo mod_foo.so -</PRE> - -</UL> - -<H3>Advantages & Disadvantages</H3> - -<P>The above DSO based features of Apache 1.3 have the following advantages: - -<UL> -<LI> The server package is more flexible at run-time because the actual server - process can be assembled at run-time via LoadModule httpd.conf - configuration commands instead of Configuration AddModule commands at - build-time. For instance this way one is able to run different server - instances (standard & SSL version, minimalistic & powered up version - [mod_perl, PHP3], etc.) with only one Apache installation. - -<LI> The server package can be easily extended with third-party modules even - after installation. This is at least a great benefit for vendor package - maintainers who can create a Apache core package and additional packages - containing extensions like PHP3, mod_perl, mod_fastcgi, etc. - -<LI> Easier Apache module prototyping because with the DSO/APXS pair you can - both work outside the Apache source tree and only need an `apxs -i' - command followed by a `apachectl restart' to bring a new version of your - currently developed module into the running Apache server. -</UL> - -<P>DSO has the following disadvantages: - -<UL> -<LI> The DSO mechanism cannot be used on every platform because not all - operating systems support dynamic loading. - -<LI> The server is approximately 20% slower at startup time because of the - symbol resolving overhead the Unix loader now has to do. - -<LI> The server is approximately 5% slower at execution time under some - platforms because position independed code (PIC) sometimes needs - complicated assembler tricks for relative addressing which are not - necessarily as fast as absolute addressing. - -<LI> Because DSO modules cannot be linked against other DSO-based libraries - (ld -lfoo) on all platforms (for instance a.out-based platforms usually - don't provide this functionality while ELF-based platforms do) you cannot - use the DSO mechanism for all types of modules. Or in other words, - modules compiled as DSO files are restricted to only use symbols from the - Apache core, from the C library (libc) and all other dynamic or static - libraries used by the Apache core, or from static library archives - (libfoo.a) containing position independend code. The only chance to use - other code is to either make sure the Apache core itself already contains - a reference to it or loading the code yourself via dlopen(). - -<LI> Under some platforms (many SVR4 systems) there is no way to force the - linker to export all global symbols for use in DSO's when linking the - Apache httpd executable program. But without the visibility of the Apache - core symbols no standard Apache module could be used as a DSO. The only - chance here is to use the SHARED_CORE feature because this way the global - symbols are forced to be exported. As a consequence the Apache - src/Configure script automatically enforces SHARED_CORE on these - platforms when DSO features are used in the Configuration file or on the - configure command line. -</UL> - -<PRE> - Ralf S. Engelschall - rse@engelschall.com - www.engelschall.com -</PRE> - - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - - diff --git a/docs/manual/env.html b/docs/manual/env.html deleted file mode 100644 index fbecf41bb7..0000000000 --- a/docs/manual/env.html +++ /dev/null @@ -1,30 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Special Purpose Environment Variables</TITLE> -</HEAD> - -<BODY> -<!--#include virtual="header.html" --> -<h1>Special Purpose Environment Variables</h1> -<P>Interoperability problems have led to the introduction of mechanisms to modify -the way Apache behaves when talking to particular clients. To make these -mechanisms as flexible as possible, they are invoked by defining environment -variables, typically with <A HREF=mod/mod_browser.html#browsermatch>BrowserMatch</A>, though <A HREF=mod/mod_env.html#setenv>SetEnv</A> and -<A HREF=mod/mod_env.html#passenv>PassEnv</A> could also be used, for example.</P> -<H2>nokeepalive</H2> -This disables <A HREF=mod/core.html#keepalive>KeepAlive</A> when set. Because -of problems with Netscape 2.x and KeepAlive, we recommend the following -directive be used: -<BLOCKQUOTE><CODE> -BrowserMatch Mozilla/2 nokeepalive -</CODE></BLOCKQUOTE> -<H2>force-response-1.0</H2> -This forces an HTTP/1.0 response when set. It was originally implemented as a -result of a problem with AOL's proxies. Some clients may not behave correctly -when given an HTTP/1.1 response, and this can be used to interoperate with -them. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/env.html.en b/docs/manual/env.html.en deleted file mode 100644 index fbecf41bb7..0000000000 --- a/docs/manual/env.html.en +++ /dev/null @@ -1,30 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Special Purpose Environment Variables</TITLE> -</HEAD> - -<BODY> -<!--#include virtual="header.html" --> -<h1>Special Purpose Environment Variables</h1> -<P>Interoperability problems have led to the introduction of mechanisms to modify -the way Apache behaves when talking to particular clients. To make these -mechanisms as flexible as possible, they are invoked by defining environment -variables, typically with <A HREF=mod/mod_browser.html#browsermatch>BrowserMatch</A>, though <A HREF=mod/mod_env.html#setenv>SetEnv</A> and -<A HREF=mod/mod_env.html#passenv>PassEnv</A> could also be used, for example.</P> -<H2>nokeepalive</H2> -This disables <A HREF=mod/core.html#keepalive>KeepAlive</A> when set. Because -of problems with Netscape 2.x and KeepAlive, we recommend the following -directive be used: -<BLOCKQUOTE><CODE> -BrowserMatch Mozilla/2 nokeepalive -</CODE></BLOCKQUOTE> -<H2>force-response-1.0</H2> -This forces an HTTP/1.0 response when set. It was originally implemented as a -result of a problem with AOL's proxies. Some clients may not behave correctly -when given an HTTP/1.1 response, and this can be used to interoperate with -them. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/handler.html b/docs/manual/handler.html deleted file mode 100644 index 4472b3165d..0000000000 --- a/docs/manual/handler.html +++ /dev/null @@ -1,138 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Apache's Handler Use</TITLE> -</HEAD> - -<BODY> -<IMG SRC="../images/apache_sub.gif" ALT=""> -<h1>Apache's Handler Use</h1> - -<h2>What is a Handler</h2> - -<p>A "handler" is an internal Apache representation of the action to be -performed when a file is called. Generally, files have implicit -handlers, based on the file type. Normally, all files are simply -served by the server, but certain file typed are "handled" -seperately. For example, you may use a type of -"application/x-httpd-cgi" to invoke CGI scripts.</p> - -<p>Apache 1.1 adds the additional ability to use handlers -explicitly. Either based on filename extensions or on location, these -handlers are unrelated to file type. This is advantageous both because -it is a more elegant solution, but it also allows for both a type -<strong>and</strong> a handler to be associated with a file.</p> - -<p>Handlers can either be built into the server or to a module, or -they can be added with the <a -href="mod_actions.html#action">Action</a> directive. The built-in -handlers in the standard distribution are as follows:</p> - -<ul> -<li><strong>send-as-is</strong>: - Send file with HTTP headers as is. - (<a href="mod_asis.html">mod_asis</a>) -<li><strong>cgi-script</strong>: - Treat the file as a CGI script. - (<a href="mod_cgi.html">mod_cgi</a>) -<li><strong>imap-file</strong>: - Imagemap rule file. - (<a href="mod_imap.html">mod_imap</a>) -<li><strong>server-info</strong>: - Get the server's configuration information - (<a href="mod_info.html">mod_info</a>) -<li><strong>server-parsed</strong>: - Parse for server-side includes - (<a href="mod_include.html">mod_include</a>) -<li><strong>server-status</strong>: - Get the server's status report - (<a href="mod_status.html">mod_status</a>) -<li><strong>type-map</strong>: - Parse as a type map file for content negotation - (<a href="mod_negotiation.html">mod_negotiation</a>) -</ul> - -<p> - -<h2>Directives</h2> -<ul> -<li><A HREF="#addhandler">AddHandler</A> -<li><A HREF="#sethandler">SetHandler</A> -</ul> - -<hr> - -<h2><a name="addhandler">AddHandler</a></h2> - -<strong>Syntax:</strong> <AddHandler <em>handler-name extention</em>><br> -<strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_mime - -<p>AddHandler maps the filename extension <em>extension</em> to the -handler <em>handler-name</em>. For example, to activate CGI scripts -with the file extension "<code>.cgi</code>", you might use: -<pre> - AddHandler cgi-script cgi -</pre> - -<p>Once that has been put into your srm.conf or httpd.conf file, any -file ending with "<code>.cgi</code>" will be treated as a CGI -program.</p> - -<hr> - -<h2><a name="sethandler">SetHandler</a></h2> - -<strong>Syntax:</strong> <SetHandler <em>handler-name</em>><br> -<strong>Context:</strong> directory, .htaccess<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_mime - -<p>When placed into an <code>.htaccess</code> file or a -<code><Directory></code> or <code><Location</code> section, -this directive forces all matching files to be parsed through the -handler given by <em>handler-name</em>. For example, if you had a -directory you wanted to be parsed entirely as imagemap rule files, -regardless of extension, you might put the following into an -<code>.htaccess</code> file in that directory: -<pre> - SetHandler imap-file -</pre> -<p>Another example: if you wanted to have the server display a status -report whenever a URL of <code>http://servername/status</code> was -called, you might put the following into access.conf: -<pre> - <Location /status> - SetHandler server-status - </Location> -</pre> - -<p><hr> - -<h2>Programmer's Note</h2> - -<p>In order to implement the handler features, an addition has been -made to the <a href="API.html">Apache API</a> that you may wish to -make use of. Specifically, a new record has been added to the -<code>request_rec</code> structure:</p> -<pre> - char *handler -</pre> -<p>If you wish to have your module engage a handler, you need only to -set <code>r->handler</code> to the name of the handler at any time -prior to the <code>invoke_handler</code> stage of the -request. Handlers are implemented as they were before, albiet using -the handler name instead of a content type. While it is not -neccessary, the naming convention for handlers is to use a -dash-seperated word, with no slashes, so as to not invade the media -type namespace.</p> - -<hr> - -<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> -<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> - -</BODY> -</HTML> - diff --git a/docs/manual/handler.html.en b/docs/manual/handler.html.en deleted file mode 100644 index 4472b3165d..0000000000 --- a/docs/manual/handler.html.en +++ /dev/null @@ -1,138 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Apache's Handler Use</TITLE> -</HEAD> - -<BODY> -<IMG SRC="../images/apache_sub.gif" ALT=""> -<h1>Apache's Handler Use</h1> - -<h2>What is a Handler</h2> - -<p>A "handler" is an internal Apache representation of the action to be -performed when a file is called. Generally, files have implicit -handlers, based on the file type. Normally, all files are simply -served by the server, but certain file typed are "handled" -seperately. For example, you may use a type of -"application/x-httpd-cgi" to invoke CGI scripts.</p> - -<p>Apache 1.1 adds the additional ability to use handlers -explicitly. Either based on filename extensions or on location, these -handlers are unrelated to file type. This is advantageous both because -it is a more elegant solution, but it also allows for both a type -<strong>and</strong> a handler to be associated with a file.</p> - -<p>Handlers can either be built into the server or to a module, or -they can be added with the <a -href="mod_actions.html#action">Action</a> directive. The built-in -handlers in the standard distribution are as follows:</p> - -<ul> -<li><strong>send-as-is</strong>: - Send file with HTTP headers as is. - (<a href="mod_asis.html">mod_asis</a>) -<li><strong>cgi-script</strong>: - Treat the file as a CGI script. - (<a href="mod_cgi.html">mod_cgi</a>) -<li><strong>imap-file</strong>: - Imagemap rule file. - (<a href="mod_imap.html">mod_imap</a>) -<li><strong>server-info</strong>: - Get the server's configuration information - (<a href="mod_info.html">mod_info</a>) -<li><strong>server-parsed</strong>: - Parse for server-side includes - (<a href="mod_include.html">mod_include</a>) -<li><strong>server-status</strong>: - Get the server's status report - (<a href="mod_status.html">mod_status</a>) -<li><strong>type-map</strong>: - Parse as a type map file for content negotation - (<a href="mod_negotiation.html">mod_negotiation</a>) -</ul> - -<p> - -<h2>Directives</h2> -<ul> -<li><A HREF="#addhandler">AddHandler</A> -<li><A HREF="#sethandler">SetHandler</A> -</ul> - -<hr> - -<h2><a name="addhandler">AddHandler</a></h2> - -<strong>Syntax:</strong> <AddHandler <em>handler-name extention</em>><br> -<strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_mime - -<p>AddHandler maps the filename extension <em>extension</em> to the -handler <em>handler-name</em>. For example, to activate CGI scripts -with the file extension "<code>.cgi</code>", you might use: -<pre> - AddHandler cgi-script cgi -</pre> - -<p>Once that has been put into your srm.conf or httpd.conf file, any -file ending with "<code>.cgi</code>" will be treated as a CGI -program.</p> - -<hr> - -<h2><a name="sethandler">SetHandler</a></h2> - -<strong>Syntax:</strong> <SetHandler <em>handler-name</em>><br> -<strong>Context:</strong> directory, .htaccess<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_mime - -<p>When placed into an <code>.htaccess</code> file or a -<code><Directory></code> or <code><Location</code> section, -this directive forces all matching files to be parsed through the -handler given by <em>handler-name</em>. For example, if you had a -directory you wanted to be parsed entirely as imagemap rule files, -regardless of extension, you might put the following into an -<code>.htaccess</code> file in that directory: -<pre> - SetHandler imap-file -</pre> -<p>Another example: if you wanted to have the server display a status -report whenever a URL of <code>http://servername/status</code> was -called, you might put the following into access.conf: -<pre> - <Location /status> - SetHandler server-status - </Location> -</pre> - -<p><hr> - -<h2>Programmer's Note</h2> - -<p>In order to implement the handler features, an addition has been -made to the <a href="API.html">Apache API</a> that you may wish to -make use of. Specifically, a new record has been added to the -<code>request_rec</code> structure:</p> -<pre> - char *handler -</pre> -<p>If you wish to have your module engage a handler, you need only to -set <code>r->handler</code> to the name of the handler at any time -prior to the <code>invoke_handler</code> stage of the -request. Handlers are implemented as they were before, albiet using -the handler name instead of a content type. While it is not -neccessary, the naming convention for handlers is to use a -dash-seperated word, with no slashes, so as to not invade the media -type namespace.</p> - -<hr> - -<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> -<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> - -</BODY> -</HTML> - diff --git a/docs/manual/images/home.gif b/docs/manual/images/home.gif Binary files differdeleted file mode 100644 index 11299c1cb7..0000000000 --- a/docs/manual/images/home.gif +++ /dev/null diff --git a/docs/manual/images/index.gif b/docs/manual/images/index.gif Binary files differdeleted file mode 100644 index 741c8939d7..0000000000 --- a/docs/manual/images/index.gif +++ /dev/null diff --git a/docs/manual/images/mod_rewrite_fig1.gif b/docs/manual/images/mod_rewrite_fig1.gif Binary files differdeleted file mode 100644 index 664ac1e7bb..0000000000 --- a/docs/manual/images/mod_rewrite_fig1.gif +++ /dev/null diff --git a/docs/manual/images/mod_rewrite_fig2.gif b/docs/manual/images/mod_rewrite_fig2.gif Binary files differdeleted file mode 100644 index 3ea8cb65a3..0000000000 --- a/docs/manual/images/mod_rewrite_fig2.gif +++ /dev/null diff --git a/docs/manual/images/sub.gif b/docs/manual/images/sub.gif Binary files differdeleted file mode 100644 index 93061c5ad7..0000000000 --- a/docs/manual/images/sub.gif +++ /dev/null diff --git a/docs/manual/install.html b/docs/manual/install.html deleted file mode 100644 index dd53b73a2e..0000000000 --- a/docs/manual/install.html +++ /dev/null @@ -1,109 +0,0 @@ -<!--%hypertext --> -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Compiling and Installing Apache</TITLE> -</HEAD> - -<BODY> -<!--/%hypertext --> - -<h1>Compiling and Installing Apache</h1> -<h2>Downloading Apache</h2> -Information on the latest version of Apache can be found on the Apache -web server at http://www.apache.org/. This will list the current release, -any more recent beta-test release, together with details of mirror -web and anonymous ftp sites. - -<h2>Compiling Apache</h2> -This release of Apache supports the notion of `optional modules'. -However, the server has to know which modules are compiled into it, in -order for those modules to be effective; this requires generation of a -short bit of code (`<code>modules.c</code>') which simply has a list of them. -<p> -If you are satisfied with our standard module set, and expect to -continue to be satisfied with it, then you can just edit the stock -<code>Makefile</code> and compile as you have been doing previously. If you -would -like to select optional modules, however, you need to run the -configuration script. -<p> -To do this: -<ol> -<li>Edit the file `<code>Configuration</code>'. This contains the per-machine -config settings of the Makefile, and also an additional section at -the bottom which lists the modules which have been compiled in, and -also names the files containing them. You will need to: -<ol> -<li> Select a compiler and compilation options as appropriate to -your machine. -<li> Uncomment lines corresponding to those optional modules you wish -to include (among the Module lines at the bottom of the file) -or add new lines corresponding to custom modules you have written. -<p> -Note that DBM auth has to be explicitly configured in, if you want -it; just uncomment the corresponding line. -</ol> -<li> Run the `Configure' script: -<blockquote><code> -% Configure<br> -Using 'Configuration' as config file<br> -%</code></blockquote> - -This generates new versions of the Makefile and of modules.c. If -you want to maintain multiple configurations, you can say, e.g., -<blockquote><code> -% Configure -file Configuration.ai<br> -Using alternate config file Configuration.ai<br> -%</code></blockquote> - -<li>Type `make'. -<p> -The modules we place in the Apache distribution are the ones we have -tested and are used regularly by various members of the Apache -development group. Additional modules contributed by members or third -parties with specific needs or functions are available at -<A HREF="http://www.apache.org/dist/contrib/modules/"><URL:http://www.apache.org/dist/contrib/modules/></A>. There are instructions on that page for -linking these modules into the core Apache code. -</ol> - -<h2>Installing Apache</h2> -After compilation, you will have a binary called `httpd' in the -<code>src/</code> directory. A binary distribution of Apache will supply this -file. -<p> -The next step is to edit the configuration files for the server. In -the subdirectory called `conf' you should find distribution versions -of the three configuration files: <code>srm.conf-dist</code>, -<code>access.conf-dist</code> and <code>httpd.conf-dist</code>. Copy them to -<code>srm.conf</code>, <code>access.conf</code> and <code>httpd.conf</code> -respectively. -<p> -First edit <code>httpd.conf</code>. This sets up general attributes about the -server; the port number, the user it runs as, etc. Next edit the -<code>srm.conf</code> file; this sets up the root of the document tree, -special functions like server-parsed HTML or internal imagemap parsing, etc. -Finally, edit the <code>access.conf</code> file to at least set the base cases -of access. -<p> -Finally, make a call to httpd, with a -f to the full path to the -httpd.conf file. I.e., the common case: -<blockquote><code> - /usr/local/etc/apache/src/httpd -f /usr/local/etc/apache/conf/httpd.conf -</code></blockquote> -The server should be now running. -<p> -By default the <code>srm.conf</code> and <code>access.conf</code> files are -located by name; to specifically call them by other names, use the -<A HREF="core.html#accessconfig">AccessConfig</A> and -<A HREF="core.html#resourceconfig">ResourceConfig</A> directives in -<code>httpd.conf</code>. - -<!--%hypertext --> -<hr> -<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> -<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> - -</BODY> -</HTML> -<!--/%hypertext --> diff --git a/docs/manual/install.html.en b/docs/manual/install.html.en deleted file mode 100644 index dd53b73a2e..0000000000 --- a/docs/manual/install.html.en +++ /dev/null @@ -1,109 +0,0 @@ -<!--%hypertext --> -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Compiling and Installing Apache</TITLE> -</HEAD> - -<BODY> -<!--/%hypertext --> - -<h1>Compiling and Installing Apache</h1> -<h2>Downloading Apache</h2> -Information on the latest version of Apache can be found on the Apache -web server at http://www.apache.org/. This will list the current release, -any more recent beta-test release, together with details of mirror -web and anonymous ftp sites. - -<h2>Compiling Apache</h2> -This release of Apache supports the notion of `optional modules'. -However, the server has to know which modules are compiled into it, in -order for those modules to be effective; this requires generation of a -short bit of code (`<code>modules.c</code>') which simply has a list of them. -<p> -If you are satisfied with our standard module set, and expect to -continue to be satisfied with it, then you can just edit the stock -<code>Makefile</code> and compile as you have been doing previously. If you -would -like to select optional modules, however, you need to run the -configuration script. -<p> -To do this: -<ol> -<li>Edit the file `<code>Configuration</code>'. This contains the per-machine -config settings of the Makefile, and also an additional section at -the bottom which lists the modules which have been compiled in, and -also names the files containing them. You will need to: -<ol> -<li> Select a compiler and compilation options as appropriate to -your machine. -<li> Uncomment lines corresponding to those optional modules you wish -to include (among the Module lines at the bottom of the file) -or add new lines corresponding to custom modules you have written. -<p> -Note that DBM auth has to be explicitly configured in, if you want -it; just uncomment the corresponding line. -</ol> -<li> Run the `Configure' script: -<blockquote><code> -% Configure<br> -Using 'Configuration' as config file<br> -%</code></blockquote> - -This generates new versions of the Makefile and of modules.c. If -you want to maintain multiple configurations, you can say, e.g., -<blockquote><code> -% Configure -file Configuration.ai<br> -Using alternate config file Configuration.ai<br> -%</code></blockquote> - -<li>Type `make'. -<p> -The modules we place in the Apache distribution are the ones we have -tested and are used regularly by various members of the Apache -development group. Additional modules contributed by members or third -parties with specific needs or functions are available at -<A HREF="http://www.apache.org/dist/contrib/modules/"><URL:http://www.apache.org/dist/contrib/modules/></A>. There are instructions on that page for -linking these modules into the core Apache code. -</ol> - -<h2>Installing Apache</h2> -After compilation, you will have a binary called `httpd' in the -<code>src/</code> directory. A binary distribution of Apache will supply this -file. -<p> -The next step is to edit the configuration files for the server. In -the subdirectory called `conf' you should find distribution versions -of the three configuration files: <code>srm.conf-dist</code>, -<code>access.conf-dist</code> and <code>httpd.conf-dist</code>. Copy them to -<code>srm.conf</code>, <code>access.conf</code> and <code>httpd.conf</code> -respectively. -<p> -First edit <code>httpd.conf</code>. This sets up general attributes about the -server; the port number, the user it runs as, etc. Next edit the -<code>srm.conf</code> file; this sets up the root of the document tree, -special functions like server-parsed HTML or internal imagemap parsing, etc. -Finally, edit the <code>access.conf</code> file to at least set the base cases -of access. -<p> -Finally, make a call to httpd, with a -f to the full path to the -httpd.conf file. I.e., the common case: -<blockquote><code> - /usr/local/etc/apache/src/httpd -f /usr/local/etc/apache/conf/httpd.conf -</code></blockquote> -The server should be now running. -<p> -By default the <code>srm.conf</code> and <code>access.conf</code> files are -located by name; to specifically call them by other names, use the -<A HREF="core.html#accessconfig">AccessConfig</A> and -<A HREF="core.html#resourceconfig">ResourceConfig</A> directives in -<code>httpd.conf</code>. - -<!--%hypertext --> -<hr> -<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> -<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> - -</BODY> -</HTML> -<!--/%hypertext --> diff --git a/docs/manual/invoking.html b/docs/manual/invoking.html deleted file mode 100644 index f00b68e459..0000000000 --- a/docs/manual/invoking.html +++ /dev/null @@ -1,108 +0,0 @@ -<!--%hypertext --> -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Starting Apache</TITLE> -</HEAD> - -<BODY> -<!--/%hypertext --> - -<h1>Starting Apache</h1> -<h2>Invoking Apache</h2> -The <code>httpd</code> program is either invoked by the Internet -daemon <code>inetd</code> each time a connection to the HTTP service is made, -or alternatively it may run as a daemon which executes continuously, handling -requests. Whatever method is chosen, the -<A HREF="core.html#servertype">ServerType</A> directive must be set -to tell the server how it is to run. - -<h2>Command line options</h2> -The following options are recognised on the httpd command line: -<dl> -<dt><code>-d</code> <em>serverroot</em> -<dd>Set the initial value for the -<A HREF="core.html#serverroot">ServerRoot</A> variable to -<em>serverroot</em>. This can be overridden by the ServerRoot command in the -configuration file. The default is <code>/usr/local/etc/httpd</code>. - -<dt><code>-f</code> <em>config</em> -<dd>Execute the commands in the file <em>config</em> on startup. If -<em>config</em> does not begin with a <code>/</code>, then it is taken to be a -path relative to the <A HREF="core.html#serverroot">ServerRoot</A>. The -default is <code>conf/httpd.conf</code>. - -<dt><code>-X</code> -<dd>Run in single-process mode, for internal debugging purposes only; the -daemon does not detach from the terminal or fork any children. Do <em>NOT</em> -use this mode to provide ordinary web service. - -<dt><code>-v</code> -<dd>Print the version of httpd, and then exit. - -<dt><code>-?</code> -<dd>Print a list of the httpd options, and then exit. -</dl> - -<h2>Configuration files</h2> -The server will read three files for configuration directives. Any directive -may appear in any of these files. The the names of these files are taken -to be relative to the server root; this is set by the -<A HREF="core.html#serverroot">ServerRoot</A> directive, or the -<code>-d</code> command line flag. - -Conventionally, the files are: -<dl> -<dt><code>conf/httpd.conf</code> -<dd>Contains directives that control the operation of the server daemon. -The filename may be overridden with the <code>-f</code> command line flag. - -<dt><code>conf/srm.conf</code> -<dd>Contains directives that control the specification of documents that -the server can provide to clients. The filename may be overridden with -the <A HREF="core.html#resourceconfig">ResourceConfig</A> directive. - -<dt><code>conf/acces.conf</code> -<dd>Contains directives that control access to documents. -The filename may be overridden with the -<A HREF="core.html#accessconfig">AccessConfig</A> directive. -</dl> -However, these conventions need not be adhered to. -<p> -The server also reads a file containing mime document types; the filename -is set by the <A HREF="mod_mime.html#typesconfig">TypesConfig</A> directive, -and is <code>conf/mime.types</code> by default. - -<h2>Log files</h2> -<h3>pid file</h3> -On daemon startup, it 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="core.html#pidfile">PidFile</A> directive. The process-id is for -use by the administrator in restarting and terminating the daemon; -A HUP signal causes the daemon to re-read its configuration files and -a TERM signal causes it to die gracefully. -<p> -If the process dies (or is killed) abnormally, then it will be necessary to -kill the children httpd processes. - -<h3>Error log</h3> -The server will log error messages to a log file, <code>logs/error_log</code> -by default. The filename can be set using the -<A HREF="core.html#errorlog">ErrorLog</A> directive; different error logs can -be set for different <A HREF="core.html#virtualhost">virtual hosts</A>. - -<h3>Transfer log</h3> -The server will typically log each request to a transfer file, -<code>logs/access_log</code> by default. The filename can be set using a -<A HREF="mod_log_common.html#transferlog">TransferLog</A> directive; different -transfer logs can be set for different <A HREF="core.html#virtualhost">virtual -hosts</A>. - -<!--%hypertext --> -<hr> -<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> -<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> - -</BODY> -</HTML> -<!--/%hypertext --> diff --git a/docs/manual/invoking.html.en b/docs/manual/invoking.html.en deleted file mode 100644 index f00b68e459..0000000000 --- a/docs/manual/invoking.html.en +++ /dev/null @@ -1,108 +0,0 @@ -<!--%hypertext --> -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Starting Apache</TITLE> -</HEAD> - -<BODY> -<!--/%hypertext --> - -<h1>Starting Apache</h1> -<h2>Invoking Apache</h2> -The <code>httpd</code> program is either invoked by the Internet -daemon <code>inetd</code> each time a connection to the HTTP service is made, -or alternatively it may run as a daemon which executes continuously, handling -requests. Whatever method is chosen, the -<A HREF="core.html#servertype">ServerType</A> directive must be set -to tell the server how it is to run. - -<h2>Command line options</h2> -The following options are recognised on the httpd command line: -<dl> -<dt><code>-d</code> <em>serverroot</em> -<dd>Set the initial value for the -<A HREF="core.html#serverroot">ServerRoot</A> variable to -<em>serverroot</em>. This can be overridden by the ServerRoot command in the -configuration file. The default is <code>/usr/local/etc/httpd</code>. - -<dt><code>-f</code> <em>config</em> -<dd>Execute the commands in the file <em>config</em> on startup. If -<em>config</em> does not begin with a <code>/</code>, then it is taken to be a -path relative to the <A HREF="core.html#serverroot">ServerRoot</A>. The -default is <code>conf/httpd.conf</code>. - -<dt><code>-X</code> -<dd>Run in single-process mode, for internal debugging purposes only; the -daemon does not detach from the terminal or fork any children. Do <em>NOT</em> -use this mode to provide ordinary web service. - -<dt><code>-v</code> -<dd>Print the version of httpd, and then exit. - -<dt><code>-?</code> -<dd>Print a list of the httpd options, and then exit. -</dl> - -<h2>Configuration files</h2> -The server will read three files for configuration directives. Any directive -may appear in any of these files. The the names of these files are taken -to be relative to the server root; this is set by the -<A HREF="core.html#serverroot">ServerRoot</A> directive, or the -<code>-d</code> command line flag. - -Conventionally, the files are: -<dl> -<dt><code>conf/httpd.conf</code> -<dd>Contains directives that control the operation of the server daemon. -The filename may be overridden with the <code>-f</code> command line flag. - -<dt><code>conf/srm.conf</code> -<dd>Contains directives that control the specification of documents that -the server can provide to clients. The filename may be overridden with -the <A HREF="core.html#resourceconfig">ResourceConfig</A> directive. - -<dt><code>conf/acces.conf</code> -<dd>Contains directives that control access to documents. -The filename may be overridden with the -<A HREF="core.html#accessconfig">AccessConfig</A> directive. -</dl> -However, these conventions need not be adhered to. -<p> -The server also reads a file containing mime document types; the filename -is set by the <A HREF="mod_mime.html#typesconfig">TypesConfig</A> directive, -and is <code>conf/mime.types</code> by default. - -<h2>Log files</h2> -<h3>pid file</h3> -On daemon startup, it 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="core.html#pidfile">PidFile</A> directive. The process-id is for -use by the administrator in restarting and terminating the daemon; -A HUP signal causes the daemon to re-read its configuration files and -a TERM signal causes it to die gracefully. -<p> -If the process dies (or is killed) abnormally, then it will be necessary to -kill the children httpd processes. - -<h3>Error log</h3> -The server will log error messages to a log file, <code>logs/error_log</code> -by default. The filename can be set using the -<A HREF="core.html#errorlog">ErrorLog</A> directive; different error logs can -be set for different <A HREF="core.html#virtualhost">virtual hosts</A>. - -<h3>Transfer log</h3> -The server will typically log each request to a transfer file, -<code>logs/access_log</code> by default. The filename can be set using a -<A HREF="mod_log_common.html#transferlog">TransferLog</A> directive; different -transfer logs can be set for different <A HREF="core.html#virtualhost">virtual -hosts</A>. - -<!--%hypertext --> -<hr> -<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> -<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> - -</BODY> -</HTML> -<!--/%hypertext --> diff --git a/docs/manual/misc/index.html b/docs/manual/misc/index.html deleted file mode 100644 index b8d7fbe27a..0000000000 --- a/docs/manual/misc/index.html +++ /dev/null @@ -1,112 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> - <HEAD> - <TITLE>Apache Miscellaneous Documentation</TITLE> - </HEAD> - - <BODY> - <!--#include virtual="header.html" --> - <H1>Apache Miscellaneous Documentation</h1> - - <P> - Below is a list of additional documentation pages that apply to the - Apache web server development project. - </P> - <DL> - <DT><A - HREF="API.html" - >API</A> - </DT> - <DD>Description of Apache's Application Programming Interface. - </DD> - <DT><A - HREF="FAQ.html" - >FAQ</A> - </DT> - <DD>Frequently-Asked Questions concerning the Apache project and server - </DD> - <DT><A - HREF="client_block_api.html" - >Reading Client Input in Apache 1.2</A> - </DT> - <DD>Describes differences between Apache 1.1 and 1.2 in how modules - read information from the client - </DD> - <DT><A - HREF="compat_notes.html" - >Compatibility with NCSA</A> - </DT> - <DD>Notes about Apache's compatibility with the NCSA server - </DD> - <DT><A - HREF="fin_wait_2.html" - ><SAMP>FIN_WAIT_2</SAMP></A> - </DT> - <DD>A description of the causes of Apache processes going into the - <SAMP>FIN_WAIT_2</SAMP> state, and what you can do about it - </DD> - <DT><A - HREF="howto.html" - >"How-To"</A> - </DT> - <DD>Instructions about how to accomplish some commonly-desired server - functionality changes - </DD> - <DT><A - HREF="known_bugs.html" - >Known Bugs</A> - </DT> - <DD>Just what it says - a list of known bugs in each of the Apache releases - </DD> - <DT><A - HREF="nopgp.html" - >No PGP</A> - </DT> - <DD>Why we took PEM and PGP support out of the base Apache distribution - </DD> - <DT><A - HREF="perf-bsd44.html" - >Performance Notes (BSD 4.4)</A> - </DT> - <DD>Some notes about ways to improve/optimise Apache performance on - BSD 4.4 systems - </DD> - <DT><A - HREF="perf-dec.html" - >Performance Notes (Digital UNIX)</A> - </DT> - <DD>Extracts of USENET postings describing how to optimise Apache - performance on Digital UNIX systems - </DD> - <DT><A - HREF="perf.html" - >Performance Notes (General)</A> - </DT> - <DD>Some generic note about how to improve Apache performance - </DD> - <DT><A - HREF="security_tips.html" - >Security Tips</A> - </DT> - <DD>Some "do"s - and "don't"s - for keeping your - Apache web site secure - </DD> - <DT><A - HREF="vif-info.html" - >Virtual Hosts (IP-based)</A> - </DT> - <DD>Excerpts and notes about configuring and using Apache IP-based virtual - hosts - </DD> - <DT><A - HREF="windoz_keepalive.html" - >Windows Bug with Web Keepalive</A> - </DT> - <DD>A brief description of a known problem with Microsoft Windows and - web sites accessed using keepalive connections - </DD> - </DL> - - <!--#include virtual="footer.html" --> - </BODY> -</HTML> diff --git a/docs/manual/misc/perf-tuning.html b/docs/manual/misc/perf-tuning.html deleted file mode 100644 index 16f8c835ef..0000000000 --- a/docs/manual/misc/perf-tuning.html +++ /dev/null @@ -1,820 +0,0 @@ -<html> -<head> -<title>Apache Performance Notes</title> -</head> -<body bgcolor="#ffffff" text="#000000" link="#0000ff" vlink="#000080" alink="#ff0000"> - -<h1>Apache Performance Notes</h1> - -<p>Author: Dean Gaudet - -<h3>Introduction</h3> -<p>Apache is a general webserver, which is designed to be correct first, and -fast second. Even so, it's performance is quite satisfactory. Most -sites have less than 10Mbits of outgoing bandwidth, which Apache can -fill using only a low end Pentium-based webserver. In practice sites -with more bandwidth require more than one machine to fill the bandwidth -due to other constraints (such as CGI or database transaction overhead). -For these reasons the development focus has been mostly on correctness -and configurability. - -<p>Unfortunately many folks overlook these facts and cite raw performance -numbers as if they are some indication of the quality of a web server -product. There is a bare minimum performance that is acceptable, beyond -that extra speed only caters to a much smaller segment of the market. -But in order to avoid this hurdle to the acceptance of Apache in some -markets, effort was put into Apache 1.3 to bring performance up to a -point where the difference with other high-end webservers is minimal. - -<p>Finally there are the folks who just plain want to see how fast something -can go. The author falls into this category. The rest of this document -is dedicated to these folks who want to squeeze every last bit of -performance out of Apache's current model, and want to understand why -it does some things which slow it down. - -<p>Note that this is tailored towards Apache 1.3 on Unix. Some of it applies -to Apache on NT. Apache on NT has not been tuned for performance yet, -in fact it probably performs very poorly because NT performance requires -a different programming model. - -<h3>Hardware and Operating System Issues</h3> - -<p>The single biggest hardware issue affecting webserver performance -is RAM. A webserver should never ever have to swap, swapping increases -the latency of each request beyond a point that users consider "fast -enough". This causes users to hit stop and reload, further increasing -the load. You can, and should, control the <code>MaxClients</code> -setting so that your server does not spawn so many children it starts -swapping. - -<p>Beyond that the rest is mundane: get a fast enough CPU, a fast enough -network card, and fast enough disks, where "fast enough" is something -that needs to be determined by experimentation. - -<p>Operating system choice is largely a matter of local concerns. But -a general guideline is to always apply the latest vendor TCP/IP patches. -HTTP serving completely breaks many of the assumptions built into Unix -kernels up through 1994 and even 1995. Good choices include -recent FreeBSD, and Linux. - -<h3>Run-Time Configuration Issues</h3> - -<h4>HostnameLookups</h4> -<p>Prior to Apache 1.3, <code>HostnameLookups</code> defaulted to On. -This adds latency -to every request because it requires a DNS lookup to complete before -the request is finished. In Apache 1.3 this setting defaults to Off. -However (1.3 or later), if you use any <code>allow from domain</code> or -<code>deny from domain</code> directives then you will pay for a -double reverse DNS lookup (a reverse, followed by a forward to make sure -that the reverse is not being spoofed). So for the highest performance -avoid using these directives (it's fine to use IP addresses rather than -domain names). - -<p>Note that it's possible to scope the directives, such as within -a <code><Location /server-status></code> section. In this -case the DNS lookups are only performed on requests matching the -criteria. Here's an example which disables -lookups except for .html and .cgi files: - -<blockquote><pre> -HostnameLookups off -<Files ~ "\.(html|cgi)$> - HostnameLookups on -</Files> -</pre></blockquote> - -But even still, if you just need DNS names -in some CGIs you could consider doing the -<code>gethostbyname</code> call in the specific CGIs that need it. - -<h4>FollowSymLinks and SymLinksIfOwnerMatch</h4> -<p>Wherever in your URL-space you do not have an -<code>Options FollowSymLinks</code>, or you do have an -<code>Options SymLinksIfOwnerMatch</code> Apache will have to -issue extra system calls to check up on symlinks. One extra call per -filename component. For example, if you had: - -<blockquote><pre> -DocumentRoot /www/htdocs -<Directory /> - Options SymLinksIfOwnerMatch -</Directory> -</pre></blockquote> - -and a request is made for the URI <code>/index.html</code>. -Then Apache will perform <code>lstat(2)</code> on <code>/www</code>, -<code>/www/htdocs</code>, and <code>/www/htdocs/index.html</code>. The -results of these <code>lstats</code> are never cached, -so they will occur on every single request. If you really desire the -symlinks security checking you can do something like this: - -<blockquote><pre> -DocumentRoot /www/htdocs -<Directory /> - Options FollowSymLinks -</Directory> -<Directory /www/htdocs> - Options -FollowSymLinks +SymLinksIfOwnerMatch -</Directory> -</pre></blockquote> - -This at least avoids the extra checks for the <code>DocumentRoot</code> -path. Note that you'll need to add similar sections if you have any -<code>Alias</code> or <code>RewriteRule</code> paths outside of your -document root. For highest performance, and no symlink protection, -set <code>FollowSymLinks</code> everywhere, and never set -<code>SymLinksIfOwnerMatch</code>. - -<h4>AllowOverride</h4> - -<p>Wherever in your URL-space you allow overrides (typically -<code>.htaccess</code> files) Apache will attempt to open -<code>.htaccess</code> for each filename component. For example, - -<blockquote><pre> -DocumentRoot /www/htdocs -<Directory /> - AllowOverride all -</Directory> -</pre></blockquote> - -and a request is made for the URI <code>/index.html</code>. Then -Apache will attempt to open <code>/.htaccess</code>, -<code>/www/.htaccess</code>, and <code>/www/htdocs/.htaccess</code>. -The solutions are similar to the previous case of <code>Options -FollowSymLinks</code>. For highest performance use -<code>AllowOverride None</code> everywhere in your filesystem. - -<h4>Negotiation</h4> - -<p>If at all possible, avoid content-negotiation if you're really -interested in every last ounce of performance. In practice the -benefits of negotiation outweigh the performance penalties. There's -one case where you can speed up the server. Instead of using -a wildcard such as: - -<blockquote><pre> -DirectoryIndex index -</pre></blockquote> - -Use a complete list of options: - -<blockquote><pre> -DirectoryIndex index.cgi index.pl index.shtml index.html -</pre></blockquote> - -where you list the most common choice first. - -<h4>Process Creation</h4> - -<p>Prior to Apache 1.3 the <code>MinSpareServers</code>, -<code>MaxSpareServers</code>, and <code>StartServers</code> settings -all had drastic effects on benchmark results. In particular, Apache -required a "ramp-up" period in order to reach a number of children -sufficient to serve the load being applied. After the initial -spawning of <code>StartServers</code> children, only one child per -second would be created to satisfy the <code>MinSpareServers</code> -setting. So a server being accessed by 100 simultaneous clients, -using the default <code>StartServers</code> of 5 would take on -the order 95 seconds to spawn enough children to handle the load. This -works fine in practice on real-life servers, because they aren't restarted -frequently. But does really poorly on benchmarks which might only run -for ten minutes. - -<p>The one-per-second rule was implemented in an effort to avoid -swamping the machine with the startup of new children. If the machine -is busy spawning children it can't service requests. But it has such -a drastic effect on the perceived performance of Apache that it had -to be replaced. As of Apache 1.3, -the code will relax the one-per-second rule. It -will spawn one, wait a second, then spawn two, wait a second, then spawn -four, and it will continue exponentially until it is spawning 32 children -per second. It will stop whenever it satisfies the -<code>MinSpareServers</code> setting. - -<p>This appears to be responsive enough that it's -almost unnecessary to twiddle the <code>MinSpareServers</code>, -<code>MaxSpareServers</code> and <code>StartServers</code> knobs. When -more than 4 children are spawned per second, a message will be emitted -to the <code>ErrorLog</code>. If you see a lot of these errors then -consider tuning these settings. Use the <code>mod_status</code> output -as a guide. - -<p>Related to process creation is process death induced by the -<code>MaxRequestsPerChild</code> setting. By default this is 30, which -is probably far too low unless your server is using a module such as -<code>mod_perl</code> which causes children to have bloated memory -images. If your server is serving mostly static pages then consider -raising this value to something like 10000. The code is robust enough -that this shouldn't be a problem. - -<p>When keep-alives are in use, children will be kept busy -doing nothing waiting for more requests on the already open -connection. The default <code>KeepAliveTimeout</code> of -15 seconds attempts to minimize this effect. The tradeoff -here is between network bandwidth and server resources. -In no event should you raise this above about 60 seconds, as -<a href="http://www.research.digital.com/wrl/techreports/abstracts/95.4.html"> -most of the benefits are lost</a>. - -<h3>Compile-Time Configuration Issues</h3> - -<h4>mod_status and Rule STATUS=yes</h4> - -<p>If you include <code>mod_status</code> -and you also set <code>Rule STATUS=yes</code> when building -Apache, then on every request Apache will perform two calls to -<code>gettimeofday(2)</code> (or <code>times(2)</code> depending -on your operating system), and (pre-1.3) several extra calls to -<code>time(2)</code>. This is all done so that the status report -contains timing indications. For highest performance, set <code>Rule -STATUS=no</code>. - -<h4>accept Serialization - multiple sockets</h4> - -<p>This discusses a shortcoming in the Unix socket API. -Suppose your -web server uses multiple <code>Listen</code> statements to listen on -either multiple ports or multiple addresses. In order to test each -socket to see if a connection is ready Apache uses <code>select(2)</code>. -<code>select(2)</code> indicates that a socket has <i>none</i> or -<i>at least one</i> connection waiting on it. Apache's model includes -multiple children, and all the idle ones test for new connections at the -same time. A naive implementation looks something like this -(these examples do not match the code, they're contrived for -pedagogical purposes): - -<blockquote><pre> - for (;;) { - for (;;) { - fd_set accept_fds; - - FD_ZERO (&accept_fds); - for (i = first_socket; i <= last_socket; ++i) { - FD_SET (i, &accept_fds); - } - rc = select (last_socket+1, &accept_fds, NULL, NULL, NULL); - if (rc < 1) continue; - new_connection = -1; - for (i = first_socket; i <= last_socket; ++i) { - if (FD_ISSET (i, &accept_fds)) { - new_connection = accept (i, NULL, NULL); - if (new_connection != -1) break; - } - } - if (new_connection != -1) break; - } - process the new_connection; - } -</pre></blockquote> - -But this naive implementation has a serious starvation problem. Recall -that multiple children execute this loop at the same time, and so multiple -children will block at <code>select</code> when they are in between -requests. All those blocked children will awaken and return from -<code>select</code> when a single request appears on any socket -(the number of children which awaken varies depending on the operating -system and timing issues). -They will all then fall down into the loop and try to <code>accept</code> -the connection. But only one will succeed (assuming there's still only -one connection ready), the rest will be <i>blocked</i> in <code>accept</code>. -This effectively locks those children into serving requests from that -one socket and no other sockets, and they'll be stuck there until enough -new requests appear on that socket to wake them all up. -This starvation problem was first documented in -<a href="http://bugs.apache.org/index/full/467">PR#467</a>. There -are at least two solutions. - -<p>One solution is to make the sockets non-blocking. In this case the -<code>accept</code> won't block the children, and they will be allowed -to continue immediately. But this wastes CPU time. Suppose you have -ten idle children in <code>select</code>, and one connection arrives. -Then nine of those children will wake up, try to <code>accept</code> the -connection, fail, and loop back into <code>select</code>, accomplishing -nothing. Meanwhile none of those children are servicing requests that -occurred on other sockets until they get back up to the <code>select</code> -again. Overall this solution does not seem very fruitful unless you -have as many idle CPUs (in a multiprocessor box) as you have idle children, -not a very likely situation. - -<p>Another solution, the one used by Apache, is to serialize entry into -the inner loop. The loop looks like this (differences highlighted): - -<blockquote><pre> - for (;;) { - <b>accept_mutex_on ();</b> - for (;;) { - fd_set accept_fds; - - FD_ZERO (&accept_fds); - for (i = first_socket; i <= last_socket; ++i) { - FD_SET (i, &accept_fds); - } - rc = select (last_socket+1, &accept_fds, NULL, NULL, NULL); - if (rc < 1) continue; - new_connection = -1; - for (i = first_socket; i <= last_socket; ++i) { - if (FD_ISSET (i, &accept_fds)) { - new_connection = accept (i, NULL, NULL); - if (new_connection != -1) break; - } - } - if (new_connection != -1) break; - } - <b>accept_mutex_off ();</b> - process the new_connection; - } -</pre></blockquote> - -<a name="serialize"></a> -The functions <code>accept_mutex_on</code> and <code>accept_mutex_off</code> -implement a mutual exclusion semaphore. Only one child can have the -mutex at any time. There are several choices for implementing these -mutexes. The choice is defined in <code>src/conf.h</code> (pre-1.3) or -<code>src/main/conf.h</code> (1.3 or later). Some architectures -do not have any locking choice made, on these architectures it is unsafe -to use multiple <code>Listen</code> directives. - -<dl> -<dt><code>USE_FLOCK_SERIALIZED_ACCEPT</code> -<dd>This method uses the <code>flock(2)</code> system call to lock a -lock file (located by the <code>LockFile</code> directive). - -<dt><code>USE_FCNTL_SERIALIZED_ACCEPT</code> -<dd>This method uses the <code>fcntl(2)</code> system call to lock a -lock file (located by the <code>LockFile</code> directive). - -<dt><code>USE_SYSVSEM_SERIALIZED_ACCEPT</code> -<dd>(1.3 or later) This method uses SysV-style semaphores to implement the -mutex. Unfortunately SysV-style semaphores have some bad side-effects. -One is that it's possible Apache will die without cleaning up the semaphore -(see the <code>ipcs(8)</code> man page). The other is that the semaphore -API allows for a denial of service attack by any CGIs running under the -same uid as the webserver (i.e. all CGIs unless you use something -like suexec or cgiwrapper). For these reasons this method is not used -on any architecture except IRIX (where the previous two are prohibitively -expensive on most IRIX boxes). - -<dt><code>USE_USLOCK_SERIALIZED_ACCEPT</code> -<dd>(1.3 or later) This method is only available on IRIX, and uses -<code>usconfig(2)</code> to create a mutex. While this method avoids -the hassles of SysV-style semaphores, it is not the default for IRIX. -This is because on single processor IRIX boxes (5.3 or 6.2) the -uslock code is two orders of magnitude slower than the SysV-semaphore -code. On multi-processor IRIX boxes the uslock code is an order of magnitude -faster than the SysV-semaphore code. Kind of a messed up situation. -So if you're using a multiprocessor IRIX box then you should rebuild your -webserver with <code>-DUSE_USLOCK_SERIALIZED_ACCEPT</code> on the -<code>EXTRA_CFLAGS</code>. - -<dt><code>USE_PTHREADS_SERIALIZED_ACCEPT</code> -<dd>(1.3 or later) This method uses POSIX mutexes and should work on -any architecture implementing the full POSIX threads specification, -however appears to only work on Solaris (2.5 or later). This is the -default for Solaris 2.5 or later. -</dl> - -<p>If your system has another method of serialization which isn't in the -above list then it may be worthwhile adding code for it (and submitting -a patch back to Apache). - -<p>Another solution that has been considered but never implemented is -to partially serialize the loop -- that is, let in a certain number -of processes. This would only be of interest on multiprocessor boxes -where it's possible multiple children could run simultaneously, and the -serialization actually doesn't take advantage of the full bandwidth. -This is a possible area of future investigation, but priority remains -low because highly parallel web servers are not the norm. - -<p>Ideally you should run servers without multiple <code>Listen</code> -statements if you want the highest performance. But read on. - -<h4>accept Serialization - single socket</h4> - -<p>The above is fine and dandy for multiple socket servers, but what -about single socket servers? In theory they shouldn't experience -any of these same problems because all children can just block in -<code>accept(2)</code> until a connection arrives, and no starvation -results. In practice this hides almost the same "spinning" behaviour -discussed above in the non-blocking solution. The way that most TCP -stacks are implemented, the kernel actually wakes up all processes blocked -in <code>accept</code> when a single connection arrives. One of those -processes gets the connection and returns to user-space, the rest spin in -the kernel and go back to sleep when they discover there's no connection -for them. This spinning is hidden from the user-land code, but it's -there nonetheless. This can result in the same load-spiking wasteful -behaviour that a non-blocking solution to the multiple sockets case can. - -<p>For this reason we have found that many architectures behave more -"nicely" if we serialize even the single socket case. So this is -actually the default in almost all cases. Crude experiments under -Linux (2.0.30 on a dual Pentium pro 166 w/128Mb RAM) have shown that -the serialization of the single socket case causes less than a 3% -decrease in requests per second over unserialized single-socket. -But unserialized single-socket showed an extra 100ms latency on -each request. This latency is probably a wash on long haul lines, -and only an issue on LANs. If you want to override the single socket -serialization you can define <code>SAFE_UNSERIALIZED_ACCEPT</code> -and then single-socket servers will not serialize at all. - -<h4>Lingering Close</h4> - -<p>As discussed in -<a href="ftp://ds.internic.net/internet-drafts/draft-ietf-http-connection-00.txt">draft-ietf-http-connection-00.txt</a> section 8, -in order for an HTTP server to <b>reliably</b> implement the protocol -it needs to shutdown each direction of the communication independently -(recall that a TCP connection is bi-directional, each half is independent -of the other). This fact is often overlooked by other servers, but -is correctly implemented in Apache as of 1.2. - -<p>When this feature was added to Apache it caused a flurry of -problems on various versions of Unix because of a shortsightedness. -The TCP specification does not state that the FIN_WAIT_2 state has a -timeout, but it doesn't prohibit it. On systems without the timeout, -Apache 1.2 induces many sockets stuck forever in the FIN_WAIT_2 state. -In many cases this can be avoided by simply upgrading to the latest -TCP/IP patches supplied by the vendor, in cases where the vendor has -never released patches (i.e. SunOS4 -- although folks with a source -license can patch it themselves) we have decided to disable this feature. - -<p>There are two ways of accomplishing this. One is the -socket option <code>SO_LINGER</code>. But as fate would have it, -this has never been implemented properly in most TCP/IP stacks. Even -on those stacks with a proper implementation (i.e. Linux 2.0.31) this -method proves to be more expensive (cputime) than the next solution. - -<p>For the most part, Apache implements this in a function called -<code>lingering_close</code> (in <code>http_main.c</code>). The -function looks roughly like this: - -<blockquote><pre> - void lingering_close (int s) - { - char junk_buffer[2048]; - - /* shutdown the sending side */ - shutdown (s, 1); - - signal (SIGALRM, lingering_death); - alarm (30); - - for (;;) { - select (s for reading, 2 second timeout); - if (error) break; - if (s is ready for reading) { - read (s, junk_buffer, sizeof (junk_buffer)); - /* just toss away whatever is here */ - } - } - - close (s); - } -</pre></blockquote> - -This naturally adds some expense at the end of a connection, but it -is required for a reliable implementation. As HTTP/1.1 becomes more -prevalent, and all connections are persistent, this expense will be -amortized over more requests. If you want to play with fire and -disable this feature you can define <code>NO_LINGCLOSE</code>, but -this is not recommended at all. In particular, as HTTP/1.1 pipelined -persistent connections come into use <code>lingering_close</code> -is an absolute necessity (and -<a href="http://www.w3.org/Protocols/HTTP/Performance/Pipeline.html"> -pipelined connections are faster</a>, so you -want to support them). - -<h4>Scoreboard File</h4> - -<p>Apache's parent and children communicate with each other through -something called the scoreboard. Ideally this should be implemented -in shared memory. For those operating systems that we either have -access to, or have been given detailed ports for, it typically is -implemented using shared memory. The rest default to using an -on-disk file. The on-disk file is not only slow, but it is unreliable -(and less featured). Peruse the <code>src/main/conf.h</code> file -for your architecture and look for either <code>HAVE_MMAP</code> or -<code>HAVE_SHMGET</code>. Defining one of those two enables the -supplied shared memory code. If your system has another type of -shared memory then edit the file <code>src/main/http_main.c</code> and -add the hooks necessary to use it in Apache. (Send us back a patch -too please.) - -<p>Historical note: The Linux port of Apache didn't start to use -shared memory until version 1.2 of Apache. This oversight resulted -in really poor and unreliable behaviour of earlier versions of Apache -on Linux. - -<h4><code>DYNAMIC_MODULE_LIMIT</code></h4> - -<p>If you have no intention of using dynamically loaded modules -(you probably don't if you're reading this and tuning your -server for every last ounce of performance) then you should add -<code>-DDYNAMIC_MODULE_LIMIT=0</code> when building your server. -This will save RAM that's allocated only for supporting dynamically -loaded modules. - -<h3>Appendix: Detailed Analysis of a Trace</h3> - -Here is a system call trace of Apache 1.3 running on Linux. The run-time -configuration file is essentially the default plus: - -<blockquote><pre> -<Directory /> - AllowOverride none - Options FollowSymLinks -</Directory> -</pre></blockquote> - -The file being requested is a static 6K file of no particular content. -Traces of non-static requests or requests with content negotiation -look wildly different (and quite ugly in some cases). First the -entire trace, then we'll examine details. (This was generated by -the <code>strace</code> program, other similar programs include -<code>truss</code>, <code>ktrace</code>, and <code>par</code>.) - -<blockquote><pre> -accept(15, {sin_family=AF_INET, sin_port=htons(22283), sin_addr=inet_addr("127.0.0.1")}, [16]) = 3 -flock(18, LOCK_UN) = 0 -sigaction(SIGUSR1, {SIG_IGN}, {0x8059954, [], SA_INTERRUPT}) = 0 -getsockname(3, {sin_family=AF_INET, sin_port=htons(8080), sin_addr=inet_addr("127.0.0.1")}, [16]) = 0 -setsockopt(3, IPPROTO_TCP1, [1], 4) = 0 -read(3, "GET /6k HTTP/1.0\r\nUser-Agent: "..., 4096) = 60 -sigaction(SIGUSR1, {SIG_IGN}, {SIG_IGN}) = 0 -time(NULL) = 873959960 -gettimeofday({873959960, 404935}, NULL) = 0 -stat("/home/dgaudet/ap/apachen/htdocs/6k", {st_mode=S_IFREG|0644, st_size=6144, ...}) = 0 -open("/home/dgaudet/ap/apachen/htdocs/6k", O_RDONLY) = 4 -mmap(0, 6144, PROT_READ, MAP_PRIVATE, 4, 0) = 0x400ee000 -writev(3, [{"HTTP/1.1 200 OK\r\nDate: Thu, 11"..., 245}, {"\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0"..., 6144}], 2) = 6389 -close(4) = 0 -time(NULL) = 873959960 -write(17, "127.0.0.1 - - [10/Sep/1997:23:39"..., 71) = 71 -gettimeofday({873959960, 417742}, NULL) = 0 -times({tms_utime=5, tms_stime=0, tms_cutime=0, tms_cstime=0}) = 446747 -shutdown(3, 1 /* send */) = 0 -oldselect(4, [3], NULL, [3], {2, 0}) = 1 (in [3], left {2, 0}) -read(3, "", 2048) = 0 -close(3) = 0 -sigaction(SIGUSR1, {0x8059954, [], SA_INTERRUPT}, {SIG_IGN}) = 0 -munmap(0x400ee000, 6144) = 0 -flock(18, LOCK_EX) = 0 -</pre></blockquote> - -<p>Notice the accept serialization: - -<blockquote><pre> -flock(18, LOCK_UN) = 0 -... -flock(18, LOCK_EX) = 0 -</pre></blockquote> - -These two calls can be removed by defining -<code>SAFE_UNSERIALIZED_ACCEPT</code> as described earlier. - -<p>Notice the <code>SIGUSR1</code> manipulation: - -<blockquote><pre> -sigaction(SIGUSR1, {SIG_IGN}, {0x8059954, [], SA_INTERRUPT}) = 0 -... -sigaction(SIGUSR1, {SIG_IGN}, {SIG_IGN}) = 0 -... -sigaction(SIGUSR1, {0x8059954, [], SA_INTERRUPT}, {SIG_IGN}) = 0 -</pre></blockquote> - -This is caused by the implementation of graceful restarts. When the -parent receives a <code>SIGUSR1</code> it sends a <code>SIGUSR1</code> -to all of its children (and it also increments a "generation counter" -in shared memory). Any children that are idle (between connections) -will immediately die -off when they receive the signal. Any children that are in keep-alive -connections, but are in between requests will die off immediately. But -any children that have a connection and are still waiting for the first -request will not die off immediately. - -<p>To see why this is necessary, consider how a browser reacts to a closed -connection. If the connection was a keep-alive connection and the request -being serviced was not the first request then the browser will quietly -reissue the request on a new connection. It has to do this because the -server is always free to close a keep-alive connection in between requests -(i.e. due to a timeout or because of a maximum number of requests). -But, if the connection is closed before the first response has been -received the typical browser will display a "document contains no data" -dialogue (or a broken image icon). This is done on the assumption that -the server is broken in some way (or maybe too overloaded to respond -at all). So Apache tries to avoid ever deliberately closing the connection -before it has sent a single response. This is the cause of those -<code>SIGUSR1</code> manipulations. - -<p>Note that it is theoretically possible to eliminate all three of -these calls. But in rough tests the gain proved to be almost unnoticeable. - -<p>In order to implement virtual hosts, Apache needs to know the -local socket address used to accept the connection: - -<blockquote><pre> -getsockname(3, {sin_family=AF_INET, sin_port=htons(8080), sin_addr=inet_addr("127.0.0.1")}, [16]) = 0 -</pre></blockquote> - -It is possible to eliminate this call in many situations (such as when -there are no virtual hosts, or when <code>Listen</code> directives are -used which do not have wildcard addresses). But no effort has yet been -made to do these optimizations. - -<p>Apache turns off the Nagle algorithm: - -<blockquote><pre> -setsockopt(3, IPPROTO_TCP1, [1], 4) = 0 -</pre></blockquote> - -because of problems described in -<a href="http://www.isi.edu/~johnh/PAPERS/Heidemann97a.html">a -paper by John Heidemann</a>. - -<p>Notice the two <code>time</code> calls: - -<blockquote><pre> -time(NULL) = 873959960 -... -time(NULL) = 873959960 -</pre></blockquote> - -One of these occurs at the beginning of the request, and the other occurs -as a result of writing the log. At least one of these is required to -properly implement the HTTP protocol. The second occurs because the -Common Log Format dictates that the log record include a timestamp of the -end of the request. A custom logging module could eliminate one of the -calls. - -<p>As described earlier, <code>Rule STATUS=yes</code> causes two -<code>gettimeofday</code> calls and a call to <code>times</code>: - -<blockquote><pre> -gettimeofday({873959960, 404935}, NULL) = 0 -... -gettimeofday({873959960, 417742}, NULL) = 0 -times({tms_utime=5, tms_stime=0, tms_cutime=0, tms_cstime=0}) = 446747 -</pre></blockquote> - -These can be removed by either removing <code>mod_status</code> or -setting <code>Rule STATUS=no</code>. - -<p>It might seem odd to call <code>stat</code>: - -<blockquote><pre> -stat("/home/dgaudet/ap/apachen/htdocs/6k", {st_mode=S_IFREG|0644, st_size=6144, ...}) = 0 -</pre></blockquote> - -This is part of the algorithm which calculates the -<code>PATH_INFO</code> for use by CGIs. In fact if the request had been -for the URI <code>/cgi-bin/printenv/foobar</code> then there would be -two calls to <code>stat</code>. The first for -<code>/home/dgaudet/ap/apachen/cgi-bin/printenv/foobar</code> -which does not exist, and the second for -<code>/home/dgaudet/ap/apachen/cgi-bin/printenv</code>, which does exist. -Regardless, at least one <code>stat</code> call is necessary when -serving static files because the file size and modification times are -used to generate HTTP headers (such as <code>Content-Length</code>, -<code>Last-Modified</code>) and implement protocol features (such -as <code>If-Modified-Since</code>). A somewhat more clever server -could avoid the <code>stat</code> when serving non-static files, -however doing so in Apache is very difficult given the modular structure. - -<p>All static files are served using <code>mmap</code>: - -<blockquote><pre> -mmap(0, 6144, PROT_READ, MAP_PRIVATE, 4, 0) = 0x400ee000 -... -munmap(0x400ee000, 6144) = 0 -</pre></blockquote> - -On some architectures it's slower to <code>mmap</code> small -files than it is to simply <code>read</code> them. The define -<code>MMAP_THRESHOLD</code> can be set to the minimum size required before -using <code>mmap</code>. By default it's set to 0 (except on SunOS4 -where experimentation has shown 8192 to be a better value). Using a -tool such as -<a href="http://reality.sgi.com/lm_engr/lmbench/lmbench.html">lmbench</a> -you can determine the optimal setting for your -environment. It may even be the case that <code>mmap</code> isn't used -on your architecture, if so then defining <code>USE_MMAP_FILES</code> -might work (if it works then report back to us). - - -<p>Apache does its best to avoid copying bytes around in memory. The -first write of any request typically is turned into a <code>writev</code> -which combines both the headers and the first hunk of data: - -<blockquote><pre> -writev(3, [{"HTTP/1.1 200 OK\r\nDate: Thu, 11"..., 245}, {"\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0"..., 6144}], 2) = 6389 -</pre></blockquote> - -When doing HTTP/1.1 chunked encoding Apache will generate up to four -element <code>writev</code>s. The goal is to push the byte copying -into the kernel, where it typically has to happen anyhow (to assemble -network packets). On testing, various Unixes (BSDI 2.x, Solaris 2.5, -Linux 2.0.31+) properly combine the elements into network packets. -Pre-2.0.31 Linux will not combine, and will create a packet for -each element, so upgrading is a good idea. Defining <code>NO_WRITEV</code> -will disable this combining, but result in very poor chunked encoding -performance. - -<p>The log write: - -<blockquote><pre> -write(17, "127.0.0.1 - - [10/Sep/1997:23:39"..., 71) = 71 -</pre></blockquote> - -can be deferred by defining <code>BUFFERED_LOGS</code>. In this case -up to <code>PIPE_BUF</code> bytes (a POSIX defined constant) of log entries -are buffered before writing. At no time does it split a log entry -across a <code>PIPE_BUF</code> boundary because those writes may not -be atomic. (i.e. entries from multiple children could become mixed together). -The code does it best to flush this buffer when a child dies. - -<p>The lingering close code causes four system calls: - -<blockquote><pre> -shutdown(3, 1 /* send */) = 0 -oldselect(4, [3], NULL, [3], {2, 0}) = 1 (in [3], left {2, 0}) -read(3, "", 2048) = 0 -close(3) = 0 -</pre></blockquote> - -which were described earlier. - -<p>Let's apply some of these optimizations: -<code>-DSAFE_UNSERIALIZED_ACCEPT -DBUFFERED_LOGS</code> and -<code>Rule STATUS=no</code>. Here's the final trace: - -<blockquote><pre> -accept(15, {sin_family=AF_INET, sin_port=htons(22286), sin_addr=inet_addr("127.0.0.1")}, [16]) = 3 -sigaction(SIGUSR1, {SIG_IGN}, {0x8058c98, [], SA_INTERRUPT}) = 0 -getsockname(3, {sin_family=AF_INET, sin_port=htons(8080), sin_addr=inet_addr("127.0.0.1")}, [16]) = 0 -setsockopt(3, IPPROTO_TCP1, [1], 4) = 0 -read(3, "GET /6k HTTP/1.0\r\nUser-Agent: "..., 4096) = 60 -sigaction(SIGUSR1, {SIG_IGN}, {SIG_IGN}) = 0 -time(NULL) = 873961916 -stat("/home/dgaudet/ap/apachen/htdocs/6k", {st_mode=S_IFREG|0644, st_size=6144, ...}) = 0 -open("/home/dgaudet/ap/apachen/htdocs/6k", O_RDONLY) = 4 -mmap(0, 6144, PROT_READ, MAP_PRIVATE, 4, 0) = 0x400e3000 -writev(3, [{"HTTP/1.1 200 OK\r\nDate: Thu, 11"..., 245}, {"\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0"..., 6144}], 2) = 6389 -close(4) = 0 -time(NULL) = 873961916 -shutdown(3, 1 /* send */) = 0 -oldselect(4, [3], NULL, [3], {2, 0}) = 1 (in [3], left {2, 0}) -read(3, "", 2048) = 0 -close(3) = 0 -sigaction(SIGUSR1, {0x8058c98, [], SA_INTERRUPT}, {SIG_IGN}) = 0 -munmap(0x400e3000, 6144) = 0 -</pre></blockquote> - -That's 19 system calls, of which 4 remain relatively easy to remove, -but don't seem worth the effort. - -<h3>Appendix: The Pre-Forking Model</h3> - -<p>Apache (on Unix) is a <i>pre-forking</i> model server. The -<i>parent</i> process is responsible only for forking <i>child</i> -processes, it does not serve any requests or service any network -sockets. The child processes actually process connections, they serve -multiple connections (one at a time) before dying. -The parent spawns new or kills off old -children in response to changes in the load on the server (it does so -by monitoring a scoreboard which the children keep up to date). - -<p>This model for servers offers a robustness that other models do -not. In particular, the parent code is very simple, and with a high -degree of confidence the parent will continue to do its job without -error. The children are complex, and when you add in third party -code via modules, you risk segmentation faults and other forms of -corruption. Even should such a thing happen, it only affects one -connection and the server continues serving requests. The parent -quickly replaces the dead child. - -<p>Pre-forking is also very portable across dialects of Unix. -Historically this has been an important goal for Apache, and it continues -to remain so. - -<p>The pre-forking model comes under criticism for various -performance aspects. Of particular concern are the overhead -of forking a process, the overhead of context switches between -processes, and the memory overhead of having multiple processes. -Furthermore it does not offer as many opportunities for data-caching -between requests (such as a pool of <code>mmapped</code> files). -Various other models exist and extensive analysis can be found in the -<a href="http://www.cs.wustl.edu/~jxh/research/research.html"> papers -of the JAWS project</a>. In practice all of these costs vary drastically -depending on the operating system. - -<p>Apache's core code is already multithread aware, and Apache version -1.3 is multithreaded on NT. There have been at least two other experimental -implementations of threaded Apache (one using the 1.3 code base on DCE, -and one using a custom user-level threads package and the 1.0 code base, -neither are available publically). Part of our redesign for version 2.0 -of Apache will include abstractions of the server model so that we -can continue to support the pre-forking model, and also support various -threaded models. - -</body> -</html> diff --git a/docs/manual/misc/security_tips.html b/docs/manual/misc/security_tips.html deleted file mode 100644 index a805d8cbed..0000000000 --- a/docs/manual/misc/security_tips.html +++ /dev/null @@ -1,92 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Apache HTTP Server Documentation</TITLE> -</HEAD> - -<BODY> -<IMG SRC="../images/apache_sub.gif" ALT=""> -<H1>Security tips for server configuration</H1> - -<hr> - -<P>Some hints and tips on security issues in setting up a web server. Some of -the suggestions will be general, other, specific to Apache - -<HR> - -<H2>Server Side Includes</H2> -<P>Server side includes (SSI) can be configured so that users can execute -arbitrary programs on the server. That thought alone should send a shiver -down the spine of any sys-admin.<p> - -One solution is to disable that part of SSI. To do that you use the -IncludesNOEXEC option to the <A HREF="core.html#options">Options</A> -directive.<p> - -<HR> - -<H2>Non Script Aliased CGI</H2> -<P>Allowing users to execute <B>CGI</B> scripts in any directory should only -be considered if; -<OL> - <LI>You trust your users not to write scripts which will deliberately or -accidentally expose your system to an attack. - <LI>You consider security at your site to be so feeble in other areas, as to -make one more potential hole irrelevant. - <LI>You have no users, and nobody ever visits your server. -</OL><p> -<HR> - -<H2>Script Alias'ed CGI</H2> -<P>Limiting <B>CGI</B> to special directories gives the admin control over -what goes into those directories. This is inevitably more secure than -non script aliased CGI, but <strong>only if users with write access to the -directories are trusted</strong> or the admin is willing to test each new CGI -script/program for potential security holes.<P> - -Most sites choose this option over the non script aliased CGI approach.<p> - -<HR> -<H2>CGI in general</H2> -<P>Always remember that you must trust the writers of the CGI script/programs -or your ability to spot potential security holes in CGI, whether they were -deliberate or accidental.<p> - -All the CGI scripts will run as the same user, so they have potential to -conflict (accidentally or deliberately) with other scripts e.g. User A hates -User B, so he writes a script to trash User B's CGI database.<P> - -<HR> - -Please send any other useful security tips to -<A HREF="mailto:apache-bugs@mail.apache.org">apache-bugs@mail.apache.org</A> -<p> -<HR> - -<H2>Stopping users overriding system wide settings...</H2> -<P>To run a really tight ship, you'll want to stop users from setting -up <CODE>.htaccess</CODE> files which can override security features -you've configured. Here's one way to do it...<p> - -In the server configuration file, put -<blockquote><code> -<Directory> <br> -AllowOverride None <br> -Options None <br> -<Limit GET PUT POST> <br> -allow from all <br> -</Limit> <br> -</Directory> <br> -</code></blockquote> - -Then setup for specific directories<P> - -This stops all overrides, Includes and accesses in all directories apart -from those named.<p><hr> - -<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> -<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> - -</BODY> -</HTML> diff --git a/docs/manual/mod/core.html b/docs/manual/mod/core.html deleted file mode 100644 index c7225d732b..0000000000 --- a/docs/manual/mod/core.html +++ /dev/null @@ -1,946 +0,0 @@ -<!--%hypertext --> -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Apache Core Features</TITLE> -</HEAD> - -<BODY> -<IMG SRC="../images/apache_sub.gif" ALT=""> -<!--/%hypertext --> -<H1>Apache Core Features</h1> - -These configuration parameters control the core Apache features, and are -always available. - -<!--%hypertext --> -<ul> -<li><A HREF="#accessconfig">AccessConfig</A> -<li><A HREF="#accessfilename">AccessFileName</A> -<li><A HREF="#allowoverride">AllowOverride</A> -<li><A HREF="#authname">AuthName</A> -<li><A HREF="#authtype">AuthType</A> -<li><A HREF="#bindaddress">BindAdress</A> -<li><A HREF="#defaulttype">DefaultType</A> -<li><A HREF="#directory"><Directory></A> -<li><A HREF="#documentroot">DocumentRoot</A> -<li><A HREF="#errordocument">ErrorDocument</A> -<li><A HREF="#errorlog">ErrorLog</A> -<li><A HREF="#group">Group</A> -<li><A HREF="#identitycheck">IdentityCheck</A> -<li><A HREF="#keepalive">KeepAlive</A> -<li><A HREF="#keepalivetimeout">KeepAliveTimeout</A> -<li><A HREF="#limit"><Limit></A> -<li><A HREF="#listen">Listen;</A> -<li><A HREF="#location"><Location></A> -<li><A HREF="#maxclients">MaxClients</A> -<li><A HREF="#maxrequestsperchild">MaxRequestsPerChild</A> -<li><A HREF="#maxspareservers">MaxSpareServers</A> -<li><A HREF="#minspareservers">MinSpareServers</A> -<li><A HREF="#options">Options</A> -<li><A HREF="#pidfile">PidFile</A> -<li><A HREF="#port">Port</A> -<li><A HREF="#require">require</A> -<li><A HREF="#resourceconfig">ResourceConfig</A> -<li><A HREF="#serveradmin">ServerAdmin</A> -<li><A HREF="#serveralias">ServerAlias</A> -<li><A HREF="#servername">ServerName</A> -<li><A HREF="#serverpath">ServerPath</A> -<li><A HREF="#serverroot">ServerRoot</A> -<li><A HREF="#servertype">ServerType</A> -<li><A HREF="#startservers">StartServers</A> -<li><A HREF="#timeout">TimeOut</A> -<li><A HREF="#user">User</A> -<li><A HREF="#virtualhost"><VirtualHost></A> -</ul> -<hr> -<!--/%hypertext --> - -<A name="accessconfig"><h2>AccessConfig directive</h2></A> -<!--%plaintext <?INDEX {\tt AccessConfig} directive> --> -<strong>Syntax:</strong> AccessConfig <em>filename</em><br> -<strong>Default:</strong> <code>AccessConfig conf/access.conf</code><br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> core<p> - -The server will read this file for more directives after reading the -<A HREF="#resourceconfig">ResourceConfig</A> file. <em>Filename</em> is -relative to the <A HREF="#serverroot">ServerRoot</A>. -This feature can be disabled using: -<blockquote><code>AccessConfig /dev/null</code></blockquote> -Historically, this file only contained -<A HREF="#directory"><Directory></A> sections; in fact it can now -contain any server directive allowed in the <em>server config</em> context. -<p><hr> - -<A name="accessfilename"><h2>AccessFileName directive</h2></A> -<!--%plaintext <?INDEX {\tt AccessFileName} directive> --> -<strong>Syntax:</strong> AccessFileName <em>filename</em><br> -<strong>Default:</strong> <code>AccessFileName .htaccess</code><br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> core<p> - -When returning a document to the client the server looks for an -access control file with this name in every directory of the path to -the document, if access control files are enabled for that directory. - -For example: -<blockquote><code>AccessFileName .acl</code></blockquote> -before returning the document /usr/local/web/index.html, the -server will read /.acl, /usr/.acl, /usr/local/.acl and /usr/local/web/.acl -for directives, unless they have been disabled with -<blockquote><code> -<Directory /><br> -AllowOverride None<br> -</Directory></code></blockquote><p><hr> - -<A name="allowoverride"><h2>AllowOverride directive</h2></A> -<!--%plaintext <?INDEX {\tt AllowOverride} directive> --> -<strong>Syntax:</strong> AllowOverride <em>override override ...</em><br> -<strong>Default:</strong> <code>AllowOverride All</code><br> -<strong>Context:</strong> directory<br> -<strong>Status:</strong> core<p> - -When the server finds an .htaccess file (as specified by -<A HREF="#accessfilename">AccessFileName</A>) it needs to know which -directives declared in that file can override earlier access information.<p> - -<em>Override</em> can be set to <code>None</code>, in which case the server -will not read the file, <code>All</code> in which case the server will -allow all the directives, or one or more of the following: -<dl> -<dt>AuthConfig -<dd> -<!--%plaintext <?INDEX {\tt AuthConfig} override> --> -Allow use of the authorization directives -(<A HREF="mod_auth_dbm.html#authdbmgroupfile">AuthDBMGroupFile</A>, -<A HREF="mod_auth_dbm.html#authdbmuserfile">AuthDBMUserFile</A>, -<A HREF="mod_auth.html#authgroupfile">AuthGroupFile</A>, -<A HREF="#authname">AuthName</A>, <A HREF="#authtype">AuthType</A>, -<A HREF="mod_auth.html#authuserfile">AuthUserFile</A> and -<A HREF="#require">require</A>). -<dt>FileInfo -<dd> -<!--%plaintext <?INDEX {\tt FileInfo} override> --> -Allow use of the directives controlling document types -(<A HREF="mod_mime.html#addencoding">AddEncoding</A>, -<A HREF="mod_mime.html#addlanguage">AddLanguage</A>, -<A HREF="mod_mime.html#addtype">AddType</A>, -<A HREF="#defaulttype">DefaultType</A> and -<A HREF="mod_negotiation.html#languagepriority">LanguagePriority</A>). -<dt>Indexes -<dd> -<!--%plaintext <?INDEX {\tt Indexes} override> --> -Allow use of the directives controlling directory indexing -(<A HREF="mod_dir.html#adddescription">AddDescription</A>, -<A HREF="mod_dir.html#addicon">AddIcon</A>, -<A HREF="mod_dir.html#addiconbyencoding">AddIconByEncoding</A>, -<A HREF="mod_dir.html#addiconbytype">AddIconByType</A>, -<A HREF="mod_dir.html#defaulticon">DefaultIcon</A>, -<A HREF="mod_dir.html#directoryindex">DirectoryIndex</A>, -<A HREF="mod_dir.html#fancyindexing">FancyIndexing</A>, -<A HREF="mod_dir.html#headername">HeaderName</A>, -<A HREF="mod_dir.html#indexignore">IndexIgnore</A>, -<A HREF="mod_dir.html#indexoptions">IndexOptions</A> and -<A HREF="mod_dir.html#readmename">ReadmeName</A>). -<dt>Limit -<dd> -<!--%plaintext <?INDEX {\tt Limit} override> --> -Allow use of the directives controlling host access (allow, deny and order). -<dt>Options -<dd> -<!--%plaintext <?INDEX {\tt Options} override> --> -Allow use of the directives controlling specific directory features -(<A HREF="#options">Options</A> and -<A HREF="mod_include.html#xbithack">XBitHack</A>). -</dl><p><hr> - -<A name="authname"><h2>AuthName directive</h2></A> -<!--%plaintext <?INDEX {\tt AuthName} directive> --> -<strong>Syntax:</strong> AuthName <em>auth-domain</em><br> -<strong>Context:</strong> directory, .htaccess<br> -<strong>Override:</strong> AuthConfig<br> -<strong>Status:</strong> core<p> - -This directive sets the name of the authorization realm for a directory. -This realm is given to the client so that the user knows which username and -password to send. -It must be accompanied by <A HREF="#authtype">AuthType</A> and -<A HREF="#require">require</A> directives, and directives such as -<A HREF="mod_auth.html#authuserfile">AuthUserFile</A> and -<A HREF="mod_auth.html#authgroupfile">AuthGroupFile</A> to work.<p><hr> - -<A name="authtype"><h2>AuthType directive</h2></A> -<!--%plaintext <?INDEX {\tt AuthType} directive> --> -<strong>Syntax:</strong> AuthType <em>type</em><br> -<strong>Context:</strong> directory, .htaccess<br> -<strong>Override:</strong> AuthConfig<br> -<strong>Status:</strong> core<p> - -This directive selects the type of user authentication for a directory. -Only <code>Basic</code> is currently implemented. -<!--%plaintext <?INDEX {\tt Basic} authentication scheme> --> -It must be accompanied by <A HREF="#authname">AuthName</A> and -<A HREF="#require">require</A> directives, and directives such as -<A HREF="mod_auth.html#authuserfile">AuthUserFile</A> and -<A HREF="mod_auth.html#authgroupfile">AuthGroupFile</A> to work.<p><hr> - - -<A name="bindaddress"><h2>BindAddress directive</h2></A> -<!--%plaintext <?INDEX {\tt BindAddress} directive> --> -<strong>Syntax:</strong> BindAddress <em>saddr</em><br> -<strong>Default:</strong> <code>BindAddress *</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> core<p> - -A Unix® http server can either listen on for connections to every -IP address of the server machine, or just one IP address of the server -machine. <em>Saddr</em> can be - -<menu> -<li>* -<li>An IP address -<li>A fully-qualified internet domain name -</menu> -If the value is *, then the server will listen for connections on -every IP address, otherwise it will only listen on the IP address -specified. <p> - -This option can be used as an alternative method for supporting -<A HREF="virtual-host.html">virtual hosts</A> instead of using -<A HREF="#virtualhost"><VirtualHost></A> sections.<p><hr> - -<p><strong>See Also:</strong> -<a href="bind.html">Setting which addresses and ports Apache uses</a></p> - -<A name="defaulttype"><h2>DefaultType directive</h2></A> -<!--%plaintext <?INDEX {\tt DefaultType} directive> --> -<strong>Syntax:</strong> DefaultType <em>mime-type</em><br> -<strong>Default:</strong> <code>DefaultType text/html</code><br> -<strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<strong>Override:</strong> FileInfo<br> -<strong>Status:</strong> core<p> - -There will be times when the server is asked to provide a document -whose type cannot be determined by its MIME types mappings.<p> - -The server must inform the client of the content-type of the document, so in -the event of an unknown type it uses the <CODE>DefaultType</CODE>. For -example: -<blockquote><code>DefaultType image/gif</code></blockquote> -would be appropriate for a directory which contained many gif images -with filenames missing the .gif extension.<p><hr> - -<A name="directory"><h2><Directory> directive</h2></A> -<!--%plaintext <?INDEX {\tt Directory} section directive> --> -<strong>Syntax:</strong> <Directory <em>directory</em>> ... -</Directory> <br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> Core. <p> - -<Directory> and </Directory> are used to enclose a group of -directives which will apply only to the named directory and sub-directories -of that directory. Any directive which is allowed in a directory -context may be used. <em>Directory</em> is either the full path to a directory, -or a wildcard string. In a wildcard string, `?' matches any single character, -and `*' matches any sequences of characters. Example: -<blockquote> -<code> -<Directory /usr/local/httpd/htdocs><br> -Options Indexes FollowSymLinks<br> -</Directory></code></blockquote> -If multiple directory sections match the directory (or its parents) containing -a document, then the directives are applied in the order of shortest match -first, interspersed with the directives from the -<A HREF="#accessfilename">.htaccess</A> files. For example, with -<blockquote><code> -<Directory /><br> -AllowOverride None<br> -</Directoy><br><br> -<Directory /home/*><br> -AllowOverride FileInfo<br> -</Directory></code></blockquote> -The for access to the document <code>/home/web/dir/doc.html</code> the -steps are: -<menu> -<li>Apply directive <code>AllowOverride None</code> (disabling -<code>.htaccess</code> files). -<li>Apply directive <code>AllowOverride FileInfo</code> (for directory -<code>/home/web</code>). -<li>Apply any FileInfo directives in <code>/home/web/.htaccess</code> -</menu> - -The directory sections typically occur in the access.conf file, but they -may appear in any configuration file. <Directory> directives cannot -nest, and cannot appear in a <A HREF="#limit"><Limit></A> section. -<p><hr> - -<A NAME="documentroot"><h2>DocumentRoot directive</h2></A> -<!--%plaintext <?INDEX {\tt DocumentRoot} directive> --> -<strong>Syntax:</strong> DocumentRoot <em>directory-filename</em><br> -<strong>Default:</strong> <code>DocumentRoot -/usr/local/etc/httpd/htdocs</code><br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> core<p> - -This directive sets the directory from which httpd will serve files. -Unless matched by a directive like Alias, the server appends the path -from the requested URL to the document root to make the path to the -document. Example: -<blockquote><code>DocumentRoot /usr/web</code></blockquote> -then an access to <code>http://www.my.host.com/index.html</code> refers -to <code>/usr/web/index.html</code>. - -<P>There appears to be a bug in mod_dir which causes problems when the -DocumentRoot has a trailing slash (i.e. "DocumentRoot /usr/web/") so -please avoid that. - -<p><hr> - -<A name="errordocument"><h2>ErrorDocument directive</h2></A> -<!--%plaintext <?INDEX {\tt ErrorDocument} directive> --> -<strong>Syntax:</strong> ErrorDocument <em>error-code document</em><br> -<strong>Context</strong> server config, virtual host, directory, .htaccess<br> -<strong>Status:</strong> core<br> -<strong>Compatibility:</strong> The directory and .htaccess contexts -are only available in Apache 1.1 and later.<p> - -In the event of a problem or error, Apache can be configured to do -one of four things, - -<OL> -<LI>behave like NCSA httpd 1.3 -<LI>output a customized message -<LI>redirect to a local URL to handle the problem/error -<LI>redirect to an external URL to handle the problem/error -</OL> - -<P>2-4 are configured using <CODE>ErrorDocument</CODE>, which -is followed by the HTTP response code and a message or URL. - -<P><em>Messages</em> in this context, begin with a single quote -(<code>"</code>), which does not form part of the message itself. Apache will -sometime offer additional information regarding the problem/error. This can be -embedded into the message using <code>%s</code> - -<P>URLs will begin with a slash (/) for local URLs, or will be a full -URL which the client can resolve. Examples: -<blockquote><code> -ErrorDocument 500 /cgi-bin/tester<br> -ErrorDocument 404 /cgi-bin/bad_urls.pl<br> -ErrorDocument 401 http://www2.foo.bar/subscription_info.html<br> -ErrorDocument 403 "Sorry can't allow you access today -</code></blockquote> - -See Also: <A HREF="custom-error.html">documentation of customizable -responses.</A><p><hr> - -<A name="errorlog"><h2>ErrorLog directive</h2></A> -<!--%plaintext <?INDEX {\tt ErrorLog} directive> --> -<strong>Syntax:</strong> ErrorLog <em>filename</em><br> -<strong>Default:</strong> <code>ErrorLog logs/error_log</code><br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> core<p> - -The error log directive sets the name of the file to which the server will log -any errors it encounters. If the filename does not begin with a slash (/) -then it is assumed to be relative to the <A HREF="#serverroot">ServerRoot</A>. -Example: -<blockquote><code>ErrorLog /dev/null</code></blockquote> -This effectively turns off error logging.<p><hr> - -<A name="group"><h2>Group directive</h2></A> -<!--%plaintext <?INDEX {\tt Group} directive> --> -<strong>Syntax:</strong> Group <em>unix-group</em><br> -<strong>Default:</strong> <code>Group #-1</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> core<p> - -The Group directive sets the group under which the server will answer requests. -In order to use this directive, the standalone server must be run initially -as root. <em>Unix-group</em> is one of: -<dl> -<dt>A group name -<dd>Refers to the given group by name. -<dt># followed by a group number. -<dd>Refers to a group by its number. -</dl> - -It is recommended that you set up a new group specifically for running the -server. Some admins use user <code>nobody</code>, but this is not always -possible or desirable.<p> - -Note: if you start the server as a non-root user, it will fail to change -to the specified, and will instead continue to run as the group of the -original user. <p> - -SECURITY: See <A HREF="#user">User</A> for a discussion of the security -considerations.<p><hr> - -<A name="identitycheck"><h2>IdentityCheck directive</h2></A> -<!--%plaintext <?INDEX {\tt IdentityCheck} directive> --> -<strong>Syntax:</strong> IdentityCheck <em>boolean</em><br> -<strong>Default:</strong> <code>IdentityCheck off</code><br> -<strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<strong>Status:</strong> core<p> - -This directive enables RFC931-compliant logging of the remote user name -for each connection, where the client machine runs identd or something similar. -This information is logged in the access log. <em>Boolean</em> is either -<code>on</code> or <code>off</code>.<p> - -The information should not trusted in any way except for rudimentary usage -tracking.<p><hr> - -<h2><a name="keepalive">KeepAlive</a></h2> -<strong>Syntax:</strong> KeepAlive <em>max-requests</em><br> -<strong>Default:</strong> <code>KeepAlive 5</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Core<br> -<strong>Compatibility:</strong> KeepAlive is only available in Apache -1.1 and later.<p> - -This directive enables -<a href="keepalive.html">Keep-Alive</a> -support. Set <em>max-requests</em> -to the maximum number of requests you want Apache to entertain per -request. A limit is imposed to prevent a client from hogging your -server resources. Set this to <code>0</code> to disable support. - -<h2><a name="keepalivetimeout">KeepAliveTimeout</a></h2> -<strong>Syntax:</strong> KeepAliveTimeout <em>seconds</em><br> -<strong>Default:</strong> <code>KeepAliveTimeout 15</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Core<br> -<strong>Compatibility:</strong> KeepAliveTimeout is only available in Apache -1.1 and later.<p> - -The number of seconds Apache will wait for a subsequent request before -closing the connection. Once a request has been received, the timeout -value specified by the <a -href="../core.html#timeout"><code>Timeout</code></a> directive -applies. - - -<A name="listen"><h2>Listen</h2></A> -<strong>Syntax:</strong> -Listen [<em>IP address</em>:]<em>port number</em><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> core<br> -<strong>Compatibility:</strong> Listen is only available in Apache -1.1 and later.<p> - -<p>The Listen directive instructs Apache to listen to more than one IP -address or port; by default it responds to requests on all IP -interfaces, but only on the port given by the <a href="#port">Port</a> -directive.</p> - -<p><strong>See Also</strong>: -<a href="bind.html">Setting which addresses and ports Apache uses</a></p> - -<A name="limit"><h2><Limit> directive</h2></A> -<!--%plaintext <?INDEX {\tt Limit} section directive> --> -<strong>Syntax:</strong> - <Limit <em>method method</em> ... > ... </Limit><br> -<strong>Context:</strong> any<br> -<strong>Status:</strong> core<p> - -<Limit> and </Limit> are used to enclose a group of -access control directives which will then apply only to the specified -access methods, where <em>method</em> is any valid HTTP method. -Any directive except another <Limit> or -<A HREF="#directory"><Directory></A> may be used; the majority will be -unaffected by the <Limit>. Example: -<blockquote><code> -<Limit GET POST><br> -require valid-user<br> -</Limit></code></blockquote> -If an access control directive appears outside a <Limit> directive, -then it applies to all access methods.<p><hr> - -<h2><a name="location"><Location></a></h2> - -<strong>Syntax:</strong> <Location <em>URL prefix</em>><br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> core<br> -<strong>Compatibility:</strong> Location is only available in Apache -1.1 and later.<p> - -<p>The <Location> directive provides for access control by -URL. It is comprable to the <a -href="#directory"><Directory></a> directive, and -should be matched with a </Location> directive. Directives that -apply to the URL given should be listen -within. <code><Location></code> sections are processed in the -order they appear in the configuration file, after the -<Directory> sections and <code>.htaccess</code> files are -read.</p> - -<p>Note that, due to the way HTTP functions, <em>URL prefix</em> -should, save for proxy requests, be of the form <code>/path/</code>, -and should not include the <code>http://servername</code>. It doesn't -neccessarily have to protect a directory (it can be an individual -file, or a number of files), and can include wildcards. In a wildcard -string, `?' matches any single character, and `*' matches any -sequences of characters. - -<p>This functionality is especially useful when combined with the -<code><a href="mod_mime.html#sethandler">SetHandler</a></code> -directive. For example, to enable status requests, but allow them only -from browsers at foo.com, you might use: - -<pre> - <Location /status> - SetHandler server-status - <Limit GET> - order deny,allow - deny from all - allow from .foo.com - </Limit> - </Location> -</pre> - - -<A name="maxclients"><h2>MaxClients directive</h2></A> -<!--%plaintext <?INDEX {\tt MaxClients} directive> --> -<strong>Syntax:</strong> MaxClients <em>number</em><br> -<strong>Default:</strong> <code>MaxClients 150</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> core<p> - -The MaxClients directive sets the limit on the number of simultaneous -requests that can be supported; not more than this number of child server -processes will be created.<p><hr> - -<A name="maxrequestsperchild"><h2>MaxRequestsPerChild directive</h2></A> -<!--%plaintext <?INDEX {\tt MaxRequestsPerChild} directive> --> -<strong>Syntax:</strong> MaxRequestsPerChild <em>number</em><br> -<strong>Default:</strong> <code>MaxRequestsPerChild 0</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> core<p> - -The MaxRequestsPerChild directive sets the limit on the number of requests -that an individual child server process will handle. After MaxRequestsPerChild -requests, the child process will die. If MaxRequestsPerChild is 0, then -the process will never expire.<p> - -Setting MaxRequestsPerChild to a non-zero limit has two beneficial effects: -<ul> -<li>it limits the amount of memory that process can consume by (accidental) -memory leakage; -<li> by giving processes a finite lifetime, it helps reduce the -number of processes when the server load reduces. -</ul><p><hr> - -<A name="maxspareservers"><h2>MaxSpareServers directive</h2></A> -<!--%plaintext <?INDEX {\tt MaxSpareServers} directive> --> -<strong>Syntax:</strong> MaxSpareServers <em>number</em><br> -<strong>Default:</strong> <code>MaxSpareServers 10</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> core<p> - -The MaxSpareServers directive sets the desired maximum number of <em>idle</em> -child server processes. An idle process is one which is not handling -a request. If there are more than MaxSpareServers idle, then the parent -process will kill off the excess processes.<p> - -Tuning of this parameter should only be necessary on very busy sites. -Setting this parameter to a large number is almost always a bad idea.<p> - -See also <A HREF="#minspareservers">MinSpareServers</A> and -<A HREF="#startservers">StartServers</A>.<p><hr> - -<A name="minspareservers"><h2>MinSpareServers directive</h2></A> -<!--%plaintext <?INDEX {\tt MinSpareServers} directive> --> -<strong>Syntax:</strong> MinSpareServers <em>number</em><br> -<strong>Default:</strong> <code>MinSpareServers 5</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> core<p> - -The MinSpareServers directive sets the desired minimum number of <em>idle</em> -child server processes. An idle process is one which is not handling -a request. If there are fewer than MinSpareServers idle, then the parent -process creates new children at a maximum rate of 1 per second.<p> - -Tuning of this parameter should only be necessary on very busy sites. -Setting this parameter to a large number is almost always a bad idea.<p> - -See also <A HREF="#maxspareservers">MaxSpareServers</A> and -<A HREF="#startservers">StartServers</A>.<p><hr> - -<A name="options"><h2>Options directive</h2></A> -<!--%plaintext <?INDEX {\tt Options} directive> --> -<strong>Syntax:</strong> Options <em>option option ...</em><br> -<strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<strong>Override:</strong> Options<br> -<strong>Status:</strong> core<p> - -The Options directive controls which server features are available in -a particular directory.<p> -<em>option</em> can be set to <code>None</code>, in which case none of -the extra features are enabled, or one or more of the following: -<dl> -<dt>All -<dd>All options except for MultiViews. -<dt>ExecCGI -<dd> -<!--%plaintext <?INDEX {\tt ExecCGI} option> --> -Execution of CGI scripts is permitted. -<dt>FollowSymLinks -<dd> -<!--%plaintext <?INDEX {\tt FollowSymLinks} option> --> -The server will follow symbolic links in this directory. -<dt>Includes -<dd> -<!--%plaintext <?INDEX {\tt Includes} option> --> -Server-side includes are permitted. -<dt>IncludesNOEXEC -<dd> -<!--%plaintext <?INDEX {\tt IncludesNOEXEC} option> --> -Server-side includes are permitted, but the #exec command and -#include of CGI scripts are disabled. -<dt>Indexes -<dd> -<!--%plaintext <?INDEX {\tt Indexes} option> --> -If a URL which maps to a directory is requested, and the there is no -DirectoryIndex (e.g. index.html) in that directory, then the server will -return a formatted listing of the directory. -<dt>MultiViews -<dd> -<!--%plaintext <?INDEX {\tt MultiViews} option> --> -<A HREF="content-negotiation.html">Ccontent negotiatad</A> MultiViews are -allowed. -<dt>SymLinksIfOwnerMatch -<dd> -<!--%plaintext <?INDEX {\tt SymLinksIfOwnerMatch} option> --> -The server will only follow symbolic links for which the target -file or directory is owned by the same user id as the link. -</dl> - -If multiple Options could apply to a directory, then the most specific one is -taken complete; the options are not merged. For example: -<blockquote><code> -<Directory /web/docs> <br> -Options Indexes FollowSymLinks<br> -</Directory><br> -<Directory /web/docs/spec> <br> -Options Includes<br> -</Directory> -</code></blockquote> -then only <code>Includes</code> will be set for the /web/docs/spec -directory.<p><hr> - -<A name="pidfile"><h2>PidFile directive</h2></A> -<!--%plaintext <?INDEX {\tt PidFile} directive> --> -<strong>Syntax:</strong> PidFile <em>filename</em><br> -<strong>Default:</strong> <code>PidFile logs/httpd.pid</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> core<p> - -The PidFile directive sets the file to which the server records the -process id of the daemon. If the filename does not begin with a slash (/) -then it is assumed to be relative to the <A HREF="#serverroot">ServerRoot</A>. -The PidFile is only used in <A HREF="#servertype">standalone</A> mode.<p> - -It is often useful to be able to send the server a signal, so that it closes -and then reopens its <A HREF="#errorlog">ErrorLog</A> and TransferLog, and -re-reads its configuration files. This is done by sending a SIGHUP (kill -1) -signal to the process id listed in the PidFile.<p><hr> - -<A name="port"><h2>Port directive</h2></A> -<!--%plaintext <?INDEX {\tt Port} directive> --> -<strong>Syntax:</strong> Port <em>number</em><br> -<strong>Default:</strong> <code>Port 80</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> core<p> - -The Port directive sets the network port on which the server listens. -<em>Num</em> is a number from 0 to 65535; some port numbers (especially below -1024) are reserved for particular protocols. See <code>/etc/services</code> -for a list of some defined ports; the standard port for the http protocol -is 80.<p> - -Port 80 is one of Unix's special ports. All ports numbered -below 1024 are reserved for system use, i.e. regular (non-root) users cannot -make use of them; instead they can only use higher port numbers.<p> - -To use port 80, you must start the server from the root account. -After binding to the port and before accepting requests, Apache will change -to a low privileged user as set by the <A HREF="#user">User directive</A>.<p> - -If you cannot use port 80, choose any other unused port. Non-root users -will have to choose a port number higher than 1023, such as 8000.<p> - -SECURITY: if you do start the server as root, be sure -not to set <A HREF="#user">User</A> to root. If you run the server as -root whilst handling connections, your site may be open to a major security -attack.<p><hr> - -<A name="require"><h2>require directive</h2></A> -<!--%plaintext <?INDEX {\tt require} directive> --> -<strong>Syntax:</strong> require <em>entity-name entity entity...</em><br> -<strong>Context:</strong> directory, .htaccess<br> -<strong>Override:</strong> AuthConfig<br> -<strong>Status:</strong> core<p> - -This directive selects which authenticated users can access a directory. -The allowed syntaxes are: -<ul> -<li>require user <em>userid userid ...</em><p> -Only the named users can access the directory.<p> -<li>require group <em>group-name group-name ...</em><p> -Only users in the named groups can access the directory.<p> -<li>require valid-user<p> -All valid users can access the directory. -</ul> -<p> -If <code>require</code> appears in a <A HREF="#limit"><Limit></A> -section, then it restricts access to the named methods, otherwise -it restricts access for all methods. Example: -<blockquote><code> -AuthType Basic<br> -AuthName somedomain<br> -AuthUserFile /web/users<br> -AuthGroupFile /web/groups<br> -Limit <GET POST><br> -require group admin<br> -</Limit> -</code></blockquote> - -Require must be accompanied by <A HREF="#authname">AuthName</A> and -<A HREF="#authtype">AuthType</A> directives, and directives such as -<A HREF="mod_auth.html#authuserfile">AuthUserFile</A> and -<A HREF="mod_auth.html#authgroupfile">AuthGroupFile</A> (to define users and -groups) in order to work correctly.<p><hr> - -<A name="resourceconfig"><h2>ResourceConfig directive</h2></A> -<!--%plaintext <?INDEX {\tt ResourceConfig} directive> --> -<strong>Syntax:</strong> ResourceConfig <em>filename</em><br> -<strong>Default:</strong> <code>ResourceConfig conf/srm.conf</code><br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> core<p> - -The server will read this file for more directives after reading the -httpd.conf file. <em>Filename</em> is relative to the -<A HREF="#serverroot">ServerRoot</A>. -This feature can be disabled using: -<blockquote><code>ResourceConfig /dev/null</code></blockquote> -Historically, this file contained most directives except for server -configuration directives and <A HREF="#directory"><Directory></A>. -sections; in fact it can now contain any server directive allowed in the -<em>server config</em> context.<p> - -See also <A HREF="#accessconfig">AccessConfig</A>.<p><hr> - -<A name="serveradmin"><h2>ServerAdmin directive</h2></A> -<!--%plaintext <?INDEX {\tt ServerAdmin} directive> --> -<strong>Syntax:</strong> ServerAdmin <em>email-address</em><br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> core<p> - -The ServerAdmin sets the e-mail address that the server includes in any -error messages it returns to the client.<p> - -It may be worth setting up a dedicated address for this, e.g. -<blockquote><code>ServerAdmin www-admin@foo.bar.com</code></blockquote> -as users do not always mention that they are talking about the server!<p><hr> - -<A name="serveralias"><h2>ServerAlias directive</h2></A> - -<strong>Syntax:</strong> ServerAlias <em>host1 host2 ...</em><br> -<strong>Context:</strong> virtual host<br> -<strong>Status:</strong> core<br> -<strong>Compatibility:</strong> ServerAlias is only available in Apache -1.1 and later.<p> - -The ServerAlias directive sets the alternate names for a host, for use -with -<a href="host.html">Host-header based virtual hosts</a>. - -<p><hr> - -<A name="servername"><h2>ServerName directive</h2></A> -<!--%plaintext <?INDEX {\tt ServerName} directive> --> -<strong>Syntax:</strong> ServerName <em>fully-qualified domain name</em><br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> core<p> - -The ServerName directive sets the hostname of the server; this is only -used when creating redirection URLs. If it is not specified, then the -server attempts to deduce it from its own IP address; however this may -not work reliably, or may not return the preferred hostname. For example: -<blockquote><code>ServerName www.wibble.com</code></blockquote> -would be used if the canonical (main) name of the actual machine -were <code>monster.wibble.com</code>.<p><hr> - -<A name="serverpath"><h2>ServerPath directive</h2></A> - -<strong>Syntax:</strong> ServerPath <em>pathname</em><br> -<strong>Context:</strong> virtual host<br> -<strong>Status:</strong> core<br> -<strong>Compatibility:</strong> ServerPath is only available in Apache -1.1 and later.<p> - -The ServerAlias directive sets the legacy URL pathname for a host, for -use with <a href="host.html">Host-header based virtual hosts</a>. - -<A name="serverroot"><h2>ServerRoot directive</h2></A> -<!--%plaintext <?INDEX {\tt ServerRoot} directive> --> -<strong>Syntax:</strong> ServerRoot <em>directory-filename</em><br> -<strong>Default:</strong> <code>ServerRoot /usr/local/etc/httpd</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> core<p> - -The ServerRoot directive sets the directory in which the server lives. -Typically it will contain the subdirectories <code>conf/</code> and -<code>logs/</code>. Relative paths for other configuration files are taken -as relative to this directory.<p><hr> - -<A name="servertype"><h2>ServerType directive</h2></A> -<!--%plaintext <?INDEX {\tt ServerType} directive> --> -<strong>Syntax:</strong> ServerType <em>type</em><br> -<strong>Default:</strong> <code>ServerType standalone</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> core<p> - -The ServerType directive sets how the server is executed by the system. -<em>Type</em> is one of -<dl> -<dt>inetd -<dd>The server will be run from the system process inetd; the command to start -the server is added to <code>/etc/inetd.conf</code> -<dt>standalone -<dd>The server will run as a daemon process; the command to start the server -is added to the system startup scripts. (<code>/etc/rc.local</code> or -<code>/etc/rc3.d/...</code>.) -</dl> - -Inetd is the lesser used of the two options. For each http -connection received, a new copy of the server is started from scratch; -after the connection is complete, this program exits. There is a high price to -pay per connection, but for security reasons, some admins prefer this option. -<p> - -Standalone is the most common setting for ServerType since -it is far more efficient. The server is started once, and services all -subsequent connections. If you intend running Apache to serve a busy site, -standalone will probably be your only option.<p> - -SECURITY: if you are paranoid about security, run in inetd mode. Security -cannot be guaranteed in either, but whilst most people are happy to use -standalone, inetd is probably least prone to attack.<p><hr> - -<A name="startservers"><h2>StartServers directive</h2></A> -<!--%plaintext <?INDEX {\tt StartServers} directive> --> -<strong>Syntax:</strong> StartServers <em>number</em><br> -<strong>Default:</strong> <code>StartServers 5</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> core<p> - -The StartServers directive sets the number of child server processes created -on startup. As the number of processes is dynamically controlled depending -on the load, there is usually little reason to adjust this parameter.<p> - -See also <A HREF="#minspareservers">MinSpareServers</A> and -<A HREF="#maxspareservers">MaxSpareServers</A>.<p><hr> - -<A name="timeout"><h2>TimeOut directive</h2></A> -<!--%plaintext <?INDEX {\tt TimeOut} directive> --> -<strong>Syntax:</strong> TimeOut <em>number</em><br> -<strong>Default:</strong> <code>TimeOut 1200</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> core<p> - -The TimeOut directive sets the maximum time that the server will wait -for the receipt of a request and the completion of a request, in seconds. -So if it takes more than TimeOut seconds for a client to send a request or -receive a response, the server will break off the connection. Thus TimeOut -limits the maximum a transfer can take; for large files, and slow networks -transfer times can be large. -<p><hr> - -<A name="user"><h2>User directive</h2></A> -<!--%plaintext <?INDEX {\tt User} directive> --> -<strong>Syntax:</strong> User <em>unix-userid</em><br> -<strong>Default:</strong> <code>User #-1</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> core<p> - -The User directive sets the userid as which the server will answer requests. -In order to use this directive, the standalone server must be run initially -as root. <em>Unix-userid</em> is one of: -<dl> -<dt>A username -<dd>Refers to the given user by name. -<dt># followed by a user number. -<dd>Refers to a user by their number. -</dl> - -The user should have no privileges which result in it being able to access -files which are not intended to be visible to the outside world, and -similarly, the user should not be able to execute code which is not -meant for httpd requests. It is recommended that you set up a new user and -group specifically for running the server. Some admins use user -<code>nobody</code>, but this is not always possible or desirable.<p> - -Notes: If you start the server as a non-root user, it will fail to change -to the lesser privileged user, and will instead continue to run as -that original user. If you do start the server as root, then it is normal -for the parent process to remain running as root.<p> - -SECURITY: Don't set User (or <A HREF="#group">Group</A>) to -<code>root</code> unless you know exactly what you are doing, and what the -dangers are.<p><hr> - -<A name="virtualhost"><h2><VirtualHost> directive</h2></A> -<!--%plaintext <?INDEX {\tt VirtualHost} section directive> --> -<strong>Syntax:</strong> <VirtualHost <em>addr</em>[:<em>port</em>]> ... -</VirtualHost> <br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Core. <p> - -<VirtualHost> and </VirtualHost> are used to enclose a group of -directives which will apply only to a particular virtual host. -Any directive which is allowed in a virtual host context may be used. -When the server receives a request for a document on a particular virtual -host, it uses the configuration directives enclosed in the <VirtualHost> -section. <em>Addr</em> can be -<menu> -<li>The IP address of the virtual host -<li>A fully qualified domain name for the IP address of the virtual host. -</menu> Example: -<blockquote> -<code> -<VirtualHost host.foo.com> <br> -ServerAdmin webmaster@host.foo.com <br> -DocumentRoot /www/docs/host.foo.com <br> -ServerName host.foo.com <br> -ErrorLog logs/host.foo.com-error_log <br> -TransferLog logs/host.foo.com-access_log <br> -</VirtualHost> -</code></blockquote> - -Currently, each VirtualHost must correspond to a different IP address for -the server, so the server machine must be configured to accept IP packets for -multiple addresses. If the machine does not have multiple network interfaces, -then this can be accomplished with the <code>ifconfig alias</code> command -(if your OS supports it), or with kernel patches like -<A HREF="vif.info.txt">VIF</A> (for SunOS(TM) 4.1.x).<p> - -<!--%hypertext --> -<p><strong>See also:</strong> -<A HREF="virtual-host.html">Information on Virtual Hosts. -(multihome)</A><br> -<strong>See also:</strong> -<a href="host.html">Non-IP address-based Virtual Hosts</a> -<!--/%hypertext --></p> - -<hr> - -<!--%hypertext --> -<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> -<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> - -</BODY> -</HTML> -<!--/%hypertext --> diff --git a/docs/manual/mod/directive-dict.html b/docs/manual/mod/directive-dict.html deleted file mode 100644 index 780ac3a627..0000000000 --- a/docs/manual/mod/directive-dict.html +++ /dev/null @@ -1,262 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Definitions of terms used to describe Apache directives - </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">Terms Used to Describe Apache Directives</H1> - - <P> - Each Apache configuration directive is described using a common format - that looks like this: - </P> - <DL> - <DD><A - HREF="#Syntax" - REL="Help" - ><STRONG>Syntax:</STRONG></A> <EM>directive-name</EM> <EM>some args</EM> - <BR> - <A - HREF="#Default" - REL="Help" - ><STRONG>Default:</STRONG></A> - <SAMP><EM>directive-name default-value</EM></SAMP> - <BR> - <A - HREF="#Context" - REL="Help" - ><STRONG>Context:</STRONG></A> <EM>context-list</EM> - <BR> - <A - HREF="#Override" - REL="Help" - ><STRONG>Override:</STRONG></A> <EM>override</EM> - <BR> - <A - HREF="#Status" - REL="Help" - ><STRONG>Status:</STRONG></A> <EM>status</EM> - <BR> - <A - HREF="#Module" - REL="Help" - ><STRONG>Module:</STRONG></A> <EM>module-name</EM> - <BR> - <A - HREF="#Compatibility" - REL="Help" - ><STRONG>Compatibility:</STRONG></A> <EM>compatibility notes</EM> - </DD> - </DL> - <P> - Each of the directive's attributes, complete with possible values - where possible, are described in this document. - </P> - - <H2>Directive Terms</H2> - <UL> - <LI><A HREF="#Syntax">Syntax</A> - </LI> - <LI><A HREF="#Default">Default</A> - </LI> - <LI><A HREF="#Context">Context</A> - </LI> - <LI><A HREF="#Override">Override</A> - </LI> - <LI><A HREF="#Status">Status</A> - </LI> - <LI><A HREF="#Module">Module</A> - </LI> - <LI><A HREF="#Compatibility">Compatibility</A> - </LI> - </UL> - - <HR> - <H2><A NAME="Syntax">Syntax</A></H2> - <P> - This indicates the format of the directive as it would appear in a - configuration file. This syntax is extremely directive-specific, so - refer to the text of the directive's description for details. - </P> - - <HR> - <H2><A NAME="Default">Default</A></H2> - <P> - If the directive has a default value (<EM>i.e.</EM>, if you omit it - from your configuration entirely, the Apache Web server will behave as - though you set it to a particular value), it is described here. If - there is no default value, this section should say - "<EM>None</EM>". - </P> - - <HR> - <H2><A NAME="Context">Context</A></H2> - <P> - This indicates where in the server's configuration files the directive - is legal. It's a comma-separated list of one or more of the following - values: - </P> - <DL> - <DT><STRONG>server config</STRONG> - </DT> - <DD>This means that the directive may be used in the server - configuration files (<EM>e.g.</EM>, <SAMP>httpd.conf</SAMP>, - <SAMP>srm.conf</SAMP>, and <SAMP>access.conf</SAMP>), but - <STRONG>not</STRONG> within any <SAMP><VirtualHost></SAMP> or - <Directory> containers. It is not allowed in - <SAMP>.htaccess</SAMP> files at all. - <P> - </P> - </DD> - <DT><STRONG>virtual host</STRONG> - </DT> - <DD>This context means that the directive may appear inside - <SAMP><VirtualHost></SAMP> containers in the server - configuration files. - <P> - </P> - </DD> - <DT><STRONG>directory</STRONG> - </DT> - <DD>A directive marked as being valid in this context may be used - inside <SAMP><Directory></SAMP> containers in the server - configuration files. - <P> - </P> - </DD> - <DT><STRONG>.htaccess</STRONG> - </DT> - <DD>If a directive is valid in this context, it means that it can - appear inside <EM>per</EM>-directory <SAMP>.htaccess</SAMP> files. - It may not be processed, though depending upon the - <A - HREF="#Override" - REL="Help" - >overrides</A> - currently active. - <P> - </P> - </DD> - </DL> - <P> - The directive is <EM>only</EM> allowed within the designated context; - if you try to use it elsewhere, you'll get a configuration error that - will either prevent the server from handling requests in that context - correctly, or will keep the server from operating at all -- - <EM>i.e.</EM>, the server won't even start. - </P> - <P> - The valid locations for the directive are actually the result of a - Boolean OR of all of the listed contexts. In other words, a directive - that is marked as being valid in "<SAMP>server config, - .htaccess</SAMP>" can be used in the <SAMP>httpd.conf</SAMP> file - and in <SAMP>.htaccess</SAMP> files, but not within any - <Directory> or <VirtualHost> containers. - </P> - - <HR> - <H2><A NAME="Override">Override</A></H2> - <P> - This directive attribute indicates which configuration override must - be active in order for the directive to be processed when it appears - in a <SAMP>.htaccess</SAMP> file. If the directive's - <A - HREF="#Context" - REL="Help" - >context</A> - doesn't permit it to appear in <SAMP>.htaccess</SAMP> files, this - attribute should say "<EM>Not applicable</EM>". - </P> - <P> - Overrides are activated by the - <A - HREF="core.html#allowoverrides" - REL="Help" - ><SAMP>AllowOverrides</SAMP></A> - directive, and apply to a particular scope (such as a directory) and - all descendants, unless further modified by other - <SAMP>AllowOverrides</SAMP> directives at lower levels. The - documentation for that directive also lists the possible override - names available. - </P> - - <HR> - <H2><A NAME="Status">Status</A></H2> - <P> - This indicates how tightly bound into the Apache Web server the - directive is; in other words, you may need to recompile the server - with an enhanced set of modules in order to gain access to the - directive and its functionality. Possible values for this attribute - are: - </P> - <DL> - <DT><STRONG>Core</STRONG> - </DT> - <DD>If a directive is listed as having "Core" status, that - means it is part of the innermost portions of the Apache Web server, - and is always available. - <P> - </P> - </DD> - <DT><STRONG>Base</STRONG> - </DT> - <DD>A directive labeled as having "Base" status is - supported by one of the standard Apache modules which is compiled - into the server by default, and is therefore normally available - unless you've taken steps to remove the module from your configuration. - <P> - </P> - </DD> - <DT><STRONG>Extension</STRONG> - </DT> - <DD>A directive with "Extension" status is provided by one - of the modules included with the Apache server kit, but the module - isn't normally compiled into the server. To enable the directive - and its functionality, you will need to change the server build - configuration files and re-compile Apache. - <P> - </P> - </DD> - <DT><STRONG>Experimental</STRONG> - </DT> - <DD>"Experimental" status indicates that the directive is - available as part of the Apache kit, but you're on your own if you - try to use it. The directive is being documented for completeness, - and is not necessarily supported. The module which provides the - directive may or may not be compiled in by default; check the top of - the page which describes the directive and its module to see if it - remarks on the availability. - <P> - </P> - </DD> - </DL> - - <HR> - <H2><A NAME="Module">Module</A></H2> - <P> - This quite simply lists the name of the source module which defines - the directive. - </P> - - <HR> - <H2><A NAME="Compatibility">Compatibility</A></H2> - <P> - If the directive wasn't part of the original Apache version 1 - distribution, the version in which it was introduced should be listed - here. If the directive has the same name as one from the NCSA HTTPd - server, any inconsistencies in behaviour between the two should also - be mentioned. Otherwise, this attribute should say "<EM>No - compatibility issues.</EM>" - </P> -<!--#include virtual="footer.html" --> - </BODY> -</HTML> diff --git a/docs/manual/mod/directive-dict.html.en b/docs/manual/mod/directive-dict.html.en deleted file mode 100644 index 780ac3a627..0000000000 --- a/docs/manual/mod/directive-dict.html.en +++ /dev/null @@ -1,262 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Definitions of terms used to describe Apache directives - </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">Terms Used to Describe Apache Directives</H1> - - <P> - Each Apache configuration directive is described using a common format - that looks like this: - </P> - <DL> - <DD><A - HREF="#Syntax" - REL="Help" - ><STRONG>Syntax:</STRONG></A> <EM>directive-name</EM> <EM>some args</EM> - <BR> - <A - HREF="#Default" - REL="Help" - ><STRONG>Default:</STRONG></A> - <SAMP><EM>directive-name default-value</EM></SAMP> - <BR> - <A - HREF="#Context" - REL="Help" - ><STRONG>Context:</STRONG></A> <EM>context-list</EM> - <BR> - <A - HREF="#Override" - REL="Help" - ><STRONG>Override:</STRONG></A> <EM>override</EM> - <BR> - <A - HREF="#Status" - REL="Help" - ><STRONG>Status:</STRONG></A> <EM>status</EM> - <BR> - <A - HREF="#Module" - REL="Help" - ><STRONG>Module:</STRONG></A> <EM>module-name</EM> - <BR> - <A - HREF="#Compatibility" - REL="Help" - ><STRONG>Compatibility:</STRONG></A> <EM>compatibility notes</EM> - </DD> - </DL> - <P> - Each of the directive's attributes, complete with possible values - where possible, are described in this document. - </P> - - <H2>Directive Terms</H2> - <UL> - <LI><A HREF="#Syntax">Syntax</A> - </LI> - <LI><A HREF="#Default">Default</A> - </LI> - <LI><A HREF="#Context">Context</A> - </LI> - <LI><A HREF="#Override">Override</A> - </LI> - <LI><A HREF="#Status">Status</A> - </LI> - <LI><A HREF="#Module">Module</A> - </LI> - <LI><A HREF="#Compatibility">Compatibility</A> - </LI> - </UL> - - <HR> - <H2><A NAME="Syntax">Syntax</A></H2> - <P> - This indicates the format of the directive as it would appear in a - configuration file. This syntax is extremely directive-specific, so - refer to the text of the directive's description for details. - </P> - - <HR> - <H2><A NAME="Default">Default</A></H2> - <P> - If the directive has a default value (<EM>i.e.</EM>, if you omit it - from your configuration entirely, the Apache Web server will behave as - though you set it to a particular value), it is described here. If - there is no default value, this section should say - "<EM>None</EM>". - </P> - - <HR> - <H2><A NAME="Context">Context</A></H2> - <P> - This indicates where in the server's configuration files the directive - is legal. It's a comma-separated list of one or more of the following - values: - </P> - <DL> - <DT><STRONG>server config</STRONG> - </DT> - <DD>This means that the directive may be used in the server - configuration files (<EM>e.g.</EM>, <SAMP>httpd.conf</SAMP>, - <SAMP>srm.conf</SAMP>, and <SAMP>access.conf</SAMP>), but - <STRONG>not</STRONG> within any <SAMP><VirtualHost></SAMP> or - <Directory> containers. It is not allowed in - <SAMP>.htaccess</SAMP> files at all. - <P> - </P> - </DD> - <DT><STRONG>virtual host</STRONG> - </DT> - <DD>This context means that the directive may appear inside - <SAMP><VirtualHost></SAMP> containers in the server - configuration files. - <P> - </P> - </DD> - <DT><STRONG>directory</STRONG> - </DT> - <DD>A directive marked as being valid in this context may be used - inside <SAMP><Directory></SAMP> containers in the server - configuration files. - <P> - </P> - </DD> - <DT><STRONG>.htaccess</STRONG> - </DT> - <DD>If a directive is valid in this context, it means that it can - appear inside <EM>per</EM>-directory <SAMP>.htaccess</SAMP> files. - It may not be processed, though depending upon the - <A - HREF="#Override" - REL="Help" - >overrides</A> - currently active. - <P> - </P> - </DD> - </DL> - <P> - The directive is <EM>only</EM> allowed within the designated context; - if you try to use it elsewhere, you'll get a configuration error that - will either prevent the server from handling requests in that context - correctly, or will keep the server from operating at all -- - <EM>i.e.</EM>, the server won't even start. - </P> - <P> - The valid locations for the directive are actually the result of a - Boolean OR of all of the listed contexts. In other words, a directive - that is marked as being valid in "<SAMP>server config, - .htaccess</SAMP>" can be used in the <SAMP>httpd.conf</SAMP> file - and in <SAMP>.htaccess</SAMP> files, but not within any - <Directory> or <VirtualHost> containers. - </P> - - <HR> - <H2><A NAME="Override">Override</A></H2> - <P> - This directive attribute indicates which configuration override must - be active in order for the directive to be processed when it appears - in a <SAMP>.htaccess</SAMP> file. If the directive's - <A - HREF="#Context" - REL="Help" - >context</A> - doesn't permit it to appear in <SAMP>.htaccess</SAMP> files, this - attribute should say "<EM>Not applicable</EM>". - </P> - <P> - Overrides are activated by the - <A - HREF="core.html#allowoverrides" - REL="Help" - ><SAMP>AllowOverrides</SAMP></A> - directive, and apply to a particular scope (such as a directory) and - all descendants, unless further modified by other - <SAMP>AllowOverrides</SAMP> directives at lower levels. The - documentation for that directive also lists the possible override - names available. - </P> - - <HR> - <H2><A NAME="Status">Status</A></H2> - <P> - This indicates how tightly bound into the Apache Web server the - directive is; in other words, you may need to recompile the server - with an enhanced set of modules in order to gain access to the - directive and its functionality. Possible values for this attribute - are: - </P> - <DL> - <DT><STRONG>Core</STRONG> - </DT> - <DD>If a directive is listed as having "Core" status, that - means it is part of the innermost portions of the Apache Web server, - and is always available. - <P> - </P> - </DD> - <DT><STRONG>Base</STRONG> - </DT> - <DD>A directive labeled as having "Base" status is - supported by one of the standard Apache modules which is compiled - into the server by default, and is therefore normally available - unless you've taken steps to remove the module from your configuration. - <P> - </P> - </DD> - <DT><STRONG>Extension</STRONG> - </DT> - <DD>A directive with "Extension" status is provided by one - of the modules included with the Apache server kit, but the module - isn't normally compiled into the server. To enable the directive - and its functionality, you will need to change the server build - configuration files and re-compile Apache. - <P> - </P> - </DD> - <DT><STRONG>Experimental</STRONG> - </DT> - <DD>"Experimental" status indicates that the directive is - available as part of the Apache kit, but you're on your own if you - try to use it. The directive is being documented for completeness, - and is not necessarily supported. The module which provides the - directive may or may not be compiled in by default; check the top of - the page which describes the directive and its module to see if it - remarks on the availability. - <P> - </P> - </DD> - </DL> - - <HR> - <H2><A NAME="Module">Module</A></H2> - <P> - This quite simply lists the name of the source module which defines - the directive. - </P> - - <HR> - <H2><A NAME="Compatibility">Compatibility</A></H2> - <P> - If the directive wasn't part of the original Apache version 1 - distribution, the version in which it was introduced should be listed - here. If the directive has the same name as one from the NCSA HTTPd - server, any inconsistencies in behaviour between the two should also - be mentioned. Otherwise, this attribute should say "<EM>No - compatibility issues.</EM>" - </P> -<!--#include virtual="footer.html" --> - </BODY> -</HTML> diff --git a/docs/manual/mod/directives.html b/docs/manual/mod/directives.html deleted file mode 100644 index 3e55089f53..0000000000 --- a/docs/manual/mod/directives.html +++ /dev/null @@ -1,121 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Apache directives</TITLE> -</HEAD> - -<BODY> -<!--#include virtual="header.html" --> -<H1>Apache directives</H1> - -<ul> -<li><A HREF="core.html#accessconfig">AccessConfig</A> -<li><A HREF="core.html#accessfilename">AccessFileName</A> -<li><A HREF="mod_actions.html#action">Action</A> -<li><A HREF="mod_dir.html#adddescription">AddDescription</A> -<li><A HREF="mod_mime.html#addencoding">AddEncoding</A> -<li><A HREF="mod_mime.html#addhandler">AddHandler</A> -<li><A HREF="mod_dir.html#addicon">AddIcon</A> -<li><A HREF="mod_dir.html#addiconbyencoding">AddIconByEncoding</A> -<li><A HREF="mod_dir.html#addiconbytype">AddIconByType</A> -<li><A HREF="mod_mime.html#addlanguage">AddLanguage</A> -<li><A HREF="mod_mime.html#addtype">AddType</A> -<li><A HREF="mod_alias.html#alias">Alias</A> -<li><A HREF="mod_log_agent.html#agentlog">AgentLog</A> -<li><A HREF="mod_access.html#allow">allow</A> -<li><A HREF="core.html#allowoverride">AllowOverride</A> -<li><A HREF="mod_auth_anon.html#anonymous">Anonymous</A> -<li><A HREF="mod_auth_anon.html#LogEmail">Anonymous_LogEmail</A> -<li><A HREF="mod_auth_anon.html#VerifyEmail">Anonymous_VerifyEmail</A> -<li><A HREF="mod_auth_anon.html#NoUser">Anonymous_NoUser</A> -<li><A HREF="mod_auth_anon.html#Authorative">Anonymous_Authorative</A> -<li><A HREF="mod_digest.html#authdigestfile">AuthDigestFile</A> -<li><A HREF="mod_auth_dbm.html#authdbgroupfile">AuthDBGroupFile</A> -<li><A HREF="mod_auth_dbm.html#authdbuserfile">AuthDBUserFile</A> -<li><A HREF="mod_auth_dbm.html#authdbmgroupfile">AuthDBMGroupFile</A> -<li><A HREF="mod_auth_dbm.html#authdbmuserfile">AuthDBMUserFile</A> -<li><A HREF="mod_auth.html#authgroupfile">AuthGroupFile</A> -<li><A HREF="mod_auth.html#authuserfile">AuthUserFile</A> -<li><A HREF="core.html#authname">AuthName</A> -<li><A HREF="core.html#authtype">AuthType</A> -<li><A HREF="core.html#bindaddress">BindAdress</A> -<li><A HREF="mod_proxy.html#cachedefaultexpire">CacheDefaultExpire</A> -<li><A HREF="mod_proxy.html#cachegcinterval">CacheGcInterval</A> -<li><A HREF="mod_proxy.html#cachelastmodfied">CacheLastModified</A> -<li><A HREF="mod_proxy.html#cachemaxexpire">CacheMaxExpire</A> -<li><A HREF="mod_negotiation.html#cachenegotiateddocs">CacheNegotiatedDocs</A> -<li><A HREF="mod_proxy.html#cacheroot">CacheRoot</A> -<li><A HREF="mod_proxy.html#cachesize">CacheSize</A> -<li><A HREF="mod_cookies.html#cookielog">CookieLog</A> -<li><A HREF="mod_dir.html#defaulticon">DefaultIcon</A> -<li><A HREF="core.html#defaulttype">DefaultType</A> -<li><A HREF="mod_access.html#deny">deny</A> -<li><A HREF="core.html#directory"><Directory></A> -<li><A HREF="mod_dir.html#directoryindex">DirectoryIndex</A> -<li><A HREF="core.html#documentroot">DocumentRoot</A> -<li><A HREF="core.html#errordocument">ErrorDocument</A> -<li><A HREF="core.html#errorlog">ErrorLog</A> -<li><A HREF="mod_dir.html#fancyindexing">FancyIndexing</A> -<li><A HREF="mod_mime.html#forcetype">ForceType</A> -<li><A HREF="core.html#group">Group</A> -<li><A HREF="mod_dir.html#headername">HeaderName</A> -<li><A HREF="core.html#identitycheck">IdentityCheck</A> -<li><A HREF="mod_imap.html#imapbase">ImapBase</A> -<li><A HREF="mod_imap.html#imapdefault">ImapDefault</A> -<li><A HREF="mod_imap.html#imapmenu">ImapMenu</A> -<li><A HREF="mod_dir.html#indexignore">IndexIgnore</A> -<li><A HREF="mod_dir.html#indexoptions">IndexOptions</A> -<li><A HREF="core.html#keepalive">KeepAlive</A> -<li><A HREF="core.html#keepalivetimeout">KeepAliveTimeout</A> -<li><A HREF="mod_negotiation.html#languagepriority">LanguagePriority</A> -<li><A HREF="core.html#limit"><Limit></A> -<li><A HREF="core.html#listen">Listen</A> -<li><A HREF="mod_dld.html#loadfile">LoadFile</A> -<li><A HREF="mod_dld.html#loadmodule">LoadModule</A> -<li><A HREF="core.html#location"><Location></A> -<li><A HREF="mod_log_config.html#logformat">LogFormat</A> -<li><A HREF="core.html#maxclients">MaxClients</A> -<li><A HREF="core.html#maxrequestsperchild">MaxRequestsPerChild</A> -<li><A HREF="core.html#maxspareservers">MaxSpareServers</A> -<li><A HREF="mod_cern_meta.html#metadir">MetaDir</A> -<li><A HREF="mod_cern_meta.html#metasuffix">MetaSuffix</A> -<li><A HREF="core.html#minspareservers">MinSpareServers</A> -<li><A HREF="mod_proxy.html#nocache">NoCache</A> -<li><A HREF="core.html#options">Options</A> -<li><A HREF="mod_access.html#order">order</A> -<li><A HREF="mod_env.html#passenv">PassEnv</A> -<li><A HREF="core.html#pidfile">PidFile</A> -<li><A HREF="core.html#port">Port</A> -<li><A HREF="mod_proxy.html#proxyrequests">ProxyRequests</A> -<li><A HREF="mod_proxy.html#proxyremote">ProxyRemote</A> -<li><A HREF="mod_proxy.html#proxypass">ProxyPass</A> -<li><A HREF="mod_dir.html#readmename">ReadmeName</A> -<li><A HREF="mod_log_referer.html#refererignore">RefererIgnore</A> -<li><A HREF="mod_log_referer.html#refererlog">RefererLog</A> -<li><A HREF="core.html#require">require</A> -<li><A HREF="mod_alias.html#redirect">Redirect</A> -<li><A HREF="core.html#resourceconfig">ResourceConfig</A> -<li><A HREF="mod_actions.html#script">Script</A> -<li><A HREF="mod_alias.html#scriptalias">ScriptAlias</A> -<li><A HREF="core.html#serveradmin">ServerAdmin</A> -<li><A HREF="core.html#serveralias">ServerAlias</A> -<li><A HREF="core.html#servername">ServerName</A> -<li><A HREF="core.html#serverpath">ServerPath</A> -<li><A HREF="core.html#serverroot">ServerRoot</A> -<li><A HREF="core.html#servertype">ServerType</A> -<li><A HREF="mod_env.html#setenv">SetEnv</A> -<li><A HREF="mod_mime.html#sethandler">SetHandler</A> -<li><A HREF="core.html#startservers">StartServers</A> -<li><A HREF="core.html#timeout">TimeOut</A> -<li><A HREF="mod_log_common.html#transferlog">TransferLog</A> (mod_log_common) -<li><A HREF="mod_log_config.html#transferlog">TransferLog</A> (mod_log_config) -<li><A HREF="mod_mime.html#typesconfig">TypesConfig</A> -<li><A HREF="core.html#user">User</A> -<li><A HREF="mod_userdir.html#userdir">UserDir</A> -<li><A HREF="core.html#virtualhost"><VirtualHost></A> -<li><A HREF="mod_include.html#xbithack">XBitHack</A> -</ul> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/mod/index.html b/docs/manual/mod/index.html deleted file mode 100644 index 6a4fcfd1a5..0000000000 --- a/docs/manual/mod/index.html +++ /dev/null @@ -1,78 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Apache modules</TITLE> -</HEAD> - -<BODY> -<IMG SRC="../images/apache_sub.gif" ALT=""> -<H1>Apache modules</h1> - -<dl> -<dt><A HREF="core.html">Core</A> -<dd>Core Apache features. -<dt><A HREF="mod_access.html">mod_access</A> -<dd>Host based access control. -<dt><A HREF="mod_actions.html">mod_actions</A> Apache 1.1 and later. -<dd>Filetype/method-based script execution -<dt><A HREF="mod_alias.html">mod_alias</A> -<dd>Aliase and redirects. -<dt><A HREF="mod_asis.html">mod_asis</A> -<dd>The .asis file handler. -<dt><A HREF="mod_auth.html">mod_auth</A> -<dd>User authentication using text files. -<dt><A HREF="mod_auth_anon.html">mod_auth_anon</A> -<dd>Anonymous user authentication, FTP-style. -<dt><A HREF="mod_auth_db.html">mod_auth_db</A> -<dd>User authentication using Berkeley DB files. -<dt><A HREF="mod_auth_dbm.html">mod_auth_dbm</A> -<dd>User authentication using DBM files. -<dt><A HREF="mod_auth_msql.html">mod_auth_msql</A> -<dd>User authentication using mSQL files. -<dt><A HREF="mod_cern_meta.html">mod_cern_meta</a> -<dd>Support for HTTP header metafiles. -<dt><A HREF="mod_cgi.html">mod_cgi</A> -<dd>Invoking CGI scripts. -<dt><A HREF="mod_cookies.html">mod_cookies</A> -<dd>Support for Netscape-like cookies. -<dt><A HREF="mod_digest.html">mod_digest</A> -<dd>MD5 authentication -<dt><A HREF="mod_dir.html">mod_dir</A> -<dd>Automatic directory listings. -<dt><A HREF="mod_env.html">mod_env</A> -<dd>Passing of environments to CGI scripts -<dt><A HREF="mod_dld.html">mod_dld</A> -<dd>Start-time linking with the GNU libdld. -<dt><A HREF="mod_imap.html">mod_imap</A> -<dd>The imagemap file handler. -<dt><A HREF="mod_include.html">mod_include</A> -<dd>Server-parsed documents. -<dt><A HREF="mod_info.html">mod_info</a> -<dd>Server configuration information -<dt><A HREF="mod_log_agent.html">mod_log_agent</A> -<dd>Logging of User Agents. -<dt><A HREF="mod_log_common.html">mod_log_common</A> -<dd>Standard logging in the Common Logfile Format. -<dt><A HREF="mod_log_config.html">mod_log_config</A> -<dd>User-configurable logging replacement for mod_log_common. -<dt><A HREF="mod_log_referer.html">mod_log_referer</A> -<dd>Logging of document references. -<dt><A HREF="mod_mime.html">mod_mime</A> -<dd>Determining document types. -<dt><A HREF="mod_negotiation.html">mod_negotiation</A> -<dd>Content negotation. -<dt><A HREF="mod_proxy.html">mod_proxy</A> -<dd>Caching proxy abilities -<dt><A HREF="mod_status.html">mod_status</a> -<dd>Server status display -<dt><A HREF="mod_userdir.html">mod_userdir</A> -<dd>User home directories. -</dl> - -<hr> - -<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> -<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> - -</BODY> -</HTML> diff --git a/docs/manual/mod/mod_actions.html b/docs/manual/mod/mod_actions.html deleted file mode 100644 index 297df17ba8..0000000000 --- a/docs/manual/mod/mod_actions.html +++ /dev/null @@ -1,81 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_actions</TITLE> -</HEAD> - -<BODY> -<IMG SRC="../images/apache_sub.gif" ALT=""> -<H1>Apache module mod_actions</h1> - -This module is contained in the <code>mod_actions.c</code> file, and -is compiled in by default. It provides for -executing CGI scripts based on media type or request method. It is not -present in versions prior to Apache 1.1. - -<h2>Summary</h2> - -This module lets you run CGI scripts whenever a file of a certain type -is requested. This makes it much easier to execute scripts that -process files. - -<h2>Directives</h2> -<ul> -<li><A HREF="#action">Action</A> -<li><A HREF="#script">Script</A> -</ul> - -<hr> - -<A name="action"><h2>Action</h2></A> -<strong>Syntax:</strong> Action <em>mime-type cgi-script</em><br> -<strong>Context:</strong> server config, virutal host, directory, .htaccess<br> -<strong>Override:</strong> FileInfo<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_actions<br> -<strong>Compatibility:</strong> Action is only available in Apache 1.1 -and later<p> - -This directive adds an action, which will activate <em>cgi-script</em> when -a file of content type <em>mime-type</em> is requested. It sends the -URL and file path of the requested document using the standard -CGI PATH_INFO and PATH_TRANSLATED environment variables. - -<hr> - -<A name="script"><h2>Script</h2></A> -<strong>Syntax:</strong> Script <em>method cgi-script</em><br> -<strong>Context:</strong> server config, virutal host, directory<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_actions<br> -<strong>Compatibility:</strong> Script is only available in Apache 1.1 -and later<p> - -<p>This directive adds an action, which will activate <em>cgi-script</em> when -a file is requested using the method of <em>method</em>, which can be -one of <code>GET</code>, <code>POST</code>, <code>PUT</code> or -<code>DELETE</code>. It sends the -URL and file path of the requested document using the standard -CGI PATH_INFO and PATH_TRANSLATED environment variables. - -<p>Note that the Script command defines default actions only. If a CGI -script is called, or some other resource that is capable of handling -the requested method internally, it will do so. Also note that script -with a method of <code>GET</code> will only be called if there are -query arguments present (e.g. foo.html?hi). Otherwise, the request -will proceed normally. - -<p>Examples: -<pre> - Script GET /cgi-bin/search #e.g. for <ISINDEX>-style searching - Script PUT /~bob/put.cgi -</pre> - -<p><hr> - -<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> -<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> - -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_alias.html b/docs/manual/mod/mod_alias.html deleted file mode 100644 index f217051c95..0000000000 --- a/docs/manual/mod/mod_alias.html +++ /dev/null @@ -1,93 +0,0 @@ -<!--%hypertext --> -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_alias</TITLE> -</HEAD> - -<BODY> -<IMG SRC="../images/apache_sub.gif" ALT=""> -<!--/%hypertext --> -<H1>Module mod_alias</h1> - -This module is contained in the <code>mod_alias.c</code> file, and -is compiled in by default. It provides for mapping different parts of the -host filesystem in the the document tree, and for URL redirection. - -<!--%hypertext --> -<menu> -<li><A HREF="#alias">Alias</A> -<li><A HREF="#redirect">Redirect</A> -<li><A HREF="#scriptalias">ScriptAlias</A> -</menu> -<hr> -<!--/%hypertext --> - -<A name="alias"><h2>Alias</h2></A> -<!--%plaintext <?INDEX {\tt Alias} directive> --> -<strong>Syntax:</strong> Alias <em>url-path directory-filename</em><br> -<Strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_alias<br> -<strong>Compatibility:</strong> Alias is only available in Apache 1.1 -and later<p> - -The Alias directive allows documents to be stored in the local filesystem -other than under the <A HREF="core.html#documentroot">DocumentRoot</A>. -URLs with a (%-decoded) path beginning with <em>url-path</em> will be -mapped to local files beginning with <em>directory-filename</em>. -Example: -<blockquote><code>Alias /image /ftp/pub/image</code></blockquote> -A request for http://myserver/image/foo.gif would cause the server to -return the file /ftp/pub/image/foo.gif.<p> -See also <A HREF="#scriptalias">ScriptAlias</A>.<p><hr> - -<A name="redirect"><h2>Redirect</h2></A> -<!--%plaintext <?INDEX {\tt Redirect} directive> --> -<strong>Syntax:</strong> Redirect <em>url-path url</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_alias<br> -<strong>Compatibility:</strong> The directory and .htaccess context's -are only available in versions 1.1 and later<p> - -The Redirect directive maps an old URL into a new one. The new URL is returned -to the client which attempts to fetch it again with the new address. -<em>Url-path</em> a (%-decoded) path; any requests for documents beginning with -this path will be returned a redirect error to a new (%-encoded) url -beginning with <em>url</em>. Example: -<blockquote><code>Redirect /service -http://foo2.bar.com/service</code></blockquote> -If the client requests http://myserver/service/foo.txt, it will be told to -access http://foo2.bar.com/service/foo.txt instead.<p> -Note: Redirect directives take precedence over Alias and ScriptAlias -directives, irrespective of their ordering in the configuration file.<p><hr> - -<A name="scriptalias"><h2>ScriptAlias</h2></A> -<!--%plaintext <?INDEX {\tt ScriptAlias} directive> --> -<strong>Syntax:</strong> ScriptAlias <em>url-path directory-filename</em><br> -<Strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_alias<br> -<strong>Compatibility:</strong> ScriptAlias is only available in Apache 1.1 -and later<p> - -The ScriptAlias directive has the same behaviour as the -<A HREF="#alias">Alias</A> directive, except that in addition it -marks the target directory as containing CGI scripts. -URLs with a (%-decoded) path beginning with <em>url-path</em> will be -mapped to scripts beginning with <em>directory-filename</em>. -Example: -<blockquote><code>ScriptAlias /cgi-bin/ /web/cgi-bin/</code></blockquote> -A request for http://myserver/cgi-bin/foo would cause the server to -run the script /web/cgi-bin/foo.<p> - -<!--%hypertext --> -<hr> - -<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> -<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> - -</BODY> -</HTML> -<!--/%hypertext --> diff --git a/docs/manual/mod/mod_asis.html b/docs/manual/mod/mod_asis.html deleted file mode 100644 index 3597e1618f..0000000000 --- a/docs/manual/mod/mod_asis.html +++ /dev/null @@ -1,67 +0,0 @@ -<!--%hypertext --> -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_asis</TITLE> -</HEAD> - -<BODY> -<IMG SRC="../images/apache_sub.gif" ALT=""> -<!--/%hypertext --> -<H1>Module mod_asis</h1> - -This module is contained in the <code>mod_asis.c</code> file, and -is compiled in by default. It provides for <code>.asis</code> files. Any -document with mime type <code>httpd/send-as-is</code> will be processed by -this module. -<!--%plaintext <?INDEX {\tt httpd/send-as-is} mime type> --> - -<h2>Purpose</h2> -To allow file types to be defined such that Apache sends them without -adding HTTP headers.<P> - -This can be used to send any kind of data from the server, including redirects -and other special HTTP responses, without requiring a cgi-script or an nph -script. -<h2>Usage</h2> -In the server configuration file, define a new mime type called -<code>httpd/send-as-is</code> e.g. -<blockquote><code>AddType httpd/send-as-is asis</code></blockquote> -this defines the <code>.asis</code> file extension as being of the new -<code>httpd/send-as-is</code> mime type. The contents of any file with a -<code>.asis</code> extension will then be sent by Apache to the client with -almost no changes. Clients will need HTTP headers to be attached, so do not -forget them. A Status: header is also required; the data should be the -3-digit HTTP response code, followed by a textual message.<p> - -Here's an example of a file whose contents are sent <em>as is</em> so as to -tell the client that a file has redirected. -<blockquote><code> -Status: 302 Now where did I leave that URL <br> -Location: http://xyz.abc.com/foo/bar.html <br> -Content-type: text/html <br> -<br> -<HTML> <br> -<HEAD> <br> -<TITLE>Lame excuses'R'us</TITLE> <br> -</HEAD> <br> -<BODY> <br> -<H1>Fred's exceptionally wonderful page has moved to <br> -<A HREF="http://xyz.abc.com/foo/bar.html">Joe's</A> site. <br> -</H1> <br> -</BODY> <br> -</HTML> -</code></blockquote> -Notes: the server always adds a Date: and Server: header to the data returned -to the client, so these should not be included in the file. -The server does <em>not</em> add a Last-Modified header; it probably should. -<P> - -<!--%hypertext --> -<HR> - -<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> -<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> -</BODY> -</HTML> -<!--/%hypertext --> diff --git a/docs/manual/mod/mod_autoindex.html b/docs/manual/mod/mod_autoindex.html deleted file mode 100644 index 960c89ca13..0000000000 --- a/docs/manual/mod/mod_autoindex.html +++ /dev/null @@ -1,309 +0,0 @@ -<!--%hypertext --> -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_dir</TITLE> -</HEAD> - -<BODY> -<IMG SRC="../images/apache_sub.gif" ALT=""> -<!--/%hypertext --> -<H1>Module mod_dir</h1> - -This module is contained in the <code>mod_dir.c</code> file, and -is compiled in by default. It provides for directory indexing. - -<h2>Summary</h2> -This module controls the directory indexing. The index of a directory -can come from one of two sources: -<ul> -<li>A file written by the user, typically called <code>index.html</code>. -The <A HREF="#directoryindex">DirectoryIndex</A> directive sets the name -of this file. -<li>Otherwise, a listing generated by the server. The other directives -control the format of this listing. The <A HREF="#addicon">AddIcon</A>, -<A HREF="#addiconbyencoding">AddIconByEncoding</A> and -<A HREF="#addiconbytype">AddIconByType</A> are used to set a list of -icons to display for various file types; for each file listed, the -first icon listed that matches the file is displayed. -</ul> - -<!--%hypertext --> -<h2>Directives</h2> - -<menu> -<li><A HREF="#adddescription">AddDescription</A> -<li><A HREF="#addicon">AddIcon</A> -<li><A HREF="#addiconbyencoding">AddIconByEncoding</A> -<li><A HREF="#addiconbytype">AddIconByType</A> -<li><A HREF="#defaulticon">DefaultIcon</A> -<li><A HREF="#directoryindex">DirectoryIndex</A> -<li><A HREF="#fancyindexing">FancyIndexing</A> -<li><A HREF="#headername">HeaderName</A> -<li><A HREF="#indexignore">IndexIgnore</A> -<li><A HREF="#indexoptions">IndexOptions</A> -<li><A HREF="#readmename">ReadmeName</A> -</menu> -<hr> -<!--/%hypertext --> - -<A name="adddescription"><h2>AddDescription</h2></A> -<!--%plaintext <?INDEX {\tt AddDescription} directive> --> -<strong>Syntax:</strong> AddDescription <em>string file file...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -This sets the description to display for a file, for -<A HREF="#fancyindexing">FancyIndexing</A>. <em>File</em> is a file -extension, partial filename, wildcard expression or full filename for files -to describe. <em>String</em> is enclosed in double quotes -(<code>"</code>). Example: -<blockquote><code>AddDescription "The planet Mars" /web/pics/mars.gif -</code></blockquote><p><hr> - -<A name="addicon"><h2>AddIcon</h2></A> -<!--%plaintext <?INDEX {\tt AddIcon} directive> --> -<strong>Syntax:</strong> AddIcon <em>icon name name ...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -This sets the icon to display next to a file ending in <em>name</em> for -<A HREF="#fancyindexing">FancyIndexing</A>. <em>Icon</em> is either a -(%-escaped) relative URL to the icon, or of the format -(<em>alttext</em>,<em>url</em>) where <em>alttext</em> is the text tag given -for an icon for non-graphical browsers.<p> - -<em>Name</em> is either ^^DIRECTORY^^ for directories, ^^BLANKICON^^ for -blank lines (to format the list correctly), a file extension, a wildcard -expression, a partial filename or a complete filename. Examples: -<blockquote><code> -AddIcon (IMG,/icons/image.xbm) .gif .jpg .xbm <br> -AddIcon /icons/dir.xbm ^^DIRECTORY^^ <br> -AddIcon /icons/backup.xbm *~ -</code></blockquote> -<A HREF="#addiconbytype">AddIconByType</A> should be used in preference to -AddIcon, when possible.<p><hr> - -<A name="addiconbyencoding"><h2>AddIconByEncoding</h2></A> -<!--%plaintext <?INDEX {\tt AddIconByEncoding} directive> --> -<strong>Syntax:</strong> AddIconByEncoding <em>icon mime-encoding mime-encoding -...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -This sets the icon to display next to files with -<em>mime-encoding</em> for <A HREF="#fancyindexing">FancyIndexing</A>. -<em>Icon</em> is either a (%-escaped) relative URL to the icon, or of the -format (<em>alttext</em>,<em>url</em>) where <em>alttext</em> is the text tag -given for an icon for non-graphical browsers.<p> - -<em>Mime-encoding</em> is a wildcard expression matching required the -content-encoding. Examples: -<blockquote><code> -AddIconByEncoding /icons/compress.xbm x-compress -</code></blockquote><p><hr> - -<A name="addiconbytype"><h2>AddIconByType</h2></A> -<!--%plaintext <?INDEX {\tt AddIconByType} directive> --> -<strong>Syntax:</strong> AddIconByType <em>icon mime-type mime-type ...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -This sets the icon to display next to files of type <em>mime-type</em> for -<A HREF="#fancyindexing">FancyIndexing</A>. <em>Icon</em> is either a -(%-escaped) relative URL to the icon, or of the format -(<em>alttext</em>,<em>url</em>) where <em>alttext</em> is the text tag given -for an icon for non-graphical browsers.<p> -<em>Mime-type</em> is a wildcard expression matching required the mime types. -Examples: -<blockquote><code> -AddIconByType (IMG,/icons/image.xbm) image/* -</code></blockquote><p><hr> - -<A name="defaulticon"><h2>DefaultIcon</h2></A> -<!--%plaintext <?INDEX {\tt DefaultIcon} directive> --> -<strong>Syntax:</strong> DefaultIcon <em>url</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -The DefaultIcon directive sets the icon to display for files when no -specific icon is known, for <A HREF="#fancyindexing">FancyIndexing</A>. -<em>Url</em> is a (%-escaped) relative URL to the icon. Examples: -<blockquote><code> -DefaultIcon /icon/unknown.xbm -</code></blockquote><p><hr> - -<A name="directoryindex"><h2>DirectoryIndex</h2></A> -<!--%plaintext <?INDEX {\tt DirectoryIndex} directive> --> -<strong>Syntax:</strong> DirectoryIndex <em>local-url local-url ...</em><br> -<strong>Default:</strong> <code>DirectoryIndex index.html</code><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -The DirectoryIndex directive sets the list of resources to look for, when -the client requests an index of the directory by specifying a NULL file -at the end of the a directory name. <em>Local-url</em> is the (%-encoded) URL -of a document on the server relative to the requested directory; it is usually -the name of a file in the directory. Several URLs may be given; the server -will return the first one that it finds. If none of the resources exist, -then the server will generate its own listing of the directory. -Example: -<blockquote><code> -DirectoryIndex index.html -</code></blockquote> -then a request for <code>http://myserver/docs/</code> would return -<code>http://myserver/docs/index.html</code> if it exists, or would list -the directory if it did not. <p> - -Note that the documents do not need to be relative to the directory; -<blockquote><code> -DirectoryIndex index.html index.txt /cgi-bin/index.pl</code></blockquote> -would cause the CGI script <code>/cgi-bin/index.pl</code> to be executed -if neither <code>index.html</code> or <code>index.txt</code> existed in -a directory.<p><hr> - -<A name="fancyindexing"><h2>FancyIndexing</h2></A> -<!--%plaintext <?INDEX {\tt FancyIndexing} directive> --> -<strong>Syntax:</strong> FancyIndexing <em>boolean</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -The FancyIndexing directive sets the FancyIndexing option for a directory. -<em>Boolean</em> can be <code>on</code> or <code>off</code>. The -<A HREF="#indexoptions">IndexOptions</A> directive should be used in -preference.<p><hr> - -<A name="headername"><h2>HeaderName</h2></A> -<!--%plaintext <?INDEX {\tt HeaderName} directive> --> -<strong>Syntax:</strong> HeaderName <em>filename</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -The HeaderName directive sets the name of the file that will be inserted -at the top of the index listing. <em>Filename</em> is the name of the file -to include, and is taken to be relative to the directory being indexed. -The server first attempts to include <em>filename</em><code>.html</code> -as an HTML document, otherwise it will include <em>filename</em> as plain -text. Example: -<blockquote><code>HeaderName HEADER</code></blockquote> -when indexing the directory <code>/web</code>, the server will first look for -the HTML file <code>/web/HEADER.html</code> and include it if found, otherwise -it will include the plain text file <code>/web/HEADER</code>, if it exists. - -<p>See also <A HREF="#readmename">ReadmeName</A>.<p><hr> - -<A name="indexignore"><h2>IndexIgnore</h2></A> -<!--%plaintext <?INDEX {\tt IndexIgnore} directive> --> -<strong>Syntax:</strong> IndexIgnore <em>file file ...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -The IndexIgnore directive adds to the list of files to hide when listing -a directory. <em>File</em> is a file extension, partial filename, -wildcard expression or full filename for files to ignore. Multiple -IndexIgnore directives add to the list, rather than the replacing the list -of ignored files. By default, the list contains `<code>.</code>'. Example: -<blockquote><code> -IndexIgnore README .htaccess *~ -</code></blockquote><p><hr> - -<A name="indexoptions"><h2>IndexOptions</h2></A> -<!--%plaintext <?INDEX {\tt IndexOptions} directive> --> -<strong>Syntax:</strong> IndexOptions <em>option option ...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -The IndexOptions directive specifies the behaviour of the directory indexing. -<em>Option</em> can be one of -<dl> -<dt>FancyIndexing -<dd><!--%plaintext <?INDEX {\tt FancyIndexing} index option> --> -This turns on fancy indexing of directories. -<dt>IconsAreLinks -<dd> -<!--%plaintext <?INDEX {\tt IconsAreLinks} index option> --> -This makes the icons part of the anchor for the filename, for -fancy indexing. -<dt>ScanHTMLTitles -<dd><!--%plaintext <?INDEX {\tt ScanHTMLTitles} index option> --> -This enables the extraction of the title from HTML documents for fancy -indexing. If the file does not have a description given by -<A HREF="#adddescription">AddDescription</A> then httpd will read the -document for the value of the TITLE tag. This is CPU and disk intensive. -<dt>SuppressLastModified -<dd> -<!--%plaintext <?INDEX {\tt SuppressLastModified} index option> --> -This will suppress the display of the last modification date, in fancy -indexing listings. -<dt>SuppressSize -<dd> -<!--%plaintext <?INDEX {\tt SuppressSize} index option> --> -This will suppress the file size in fancy indexing listings. -<dt>SuppressDescription -<dd> -<!--%plaintext <?INDEX {\tt SuppressDescription} index option> --> -This will suppress the file description in fancy indexing listings. -</dl> -This default is that no options are enabled. If multiple IndexOptions -could apply to a directory, then the most specific one is taken complete; -the options are not merged. For example: -<blockquote><code> -<Directory /web/docs> <br> -IndexOptions FancyIndexing <br> -</Directory><br> -<Directory /web/docs/spec> <br> -IndexOptions ScanHTMLTitles <br> -</Directory> -</code></blockquote> -then only <code>ScanHTMLTitles</code> will be set for the /web/docs/spec -directory.<p><hr> - -<A name="readmename"><h2>ReadmeName</h2></A> -<!--%plaintext <?INDEX {\tt ReadmeName} directive> --> -<strong>Syntax:</strong> ReadmeName <em>filename</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -The ReadmeName directive sets the name of the file that will be appended -to the end of the index listing. <em>Filename</em> is the name of the file -to include, and is taken to be relative to the directory being indexed. -The server first attempts to include <em>filename</em><code>.html</code> -as an HTML document, otherwise it will include <em>filename</em> as plain -text. Example: -<blockquote><code>ReadmeName README</code></blockquote> -when indexing the directory <code>/web</code>, the server will first look for -the HTML file <code>/web/README.html</code> and include it if found, otherwise -it will include the plain text file <code>/web/README</code>, if it exists. - -<p>See also <A HREF="#headername">HeaderName</A>.<p> - -<!--%hypertext --> -<hr> -<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> -<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> - -</BODY> -</HTML> -<!--/%hypertext --> diff --git a/docs/manual/mod/mod_cern_meta.html b/docs/manual/mod/mod_cern_meta.html deleted file mode 100644 index b48dfffe2b..0000000000 --- a/docs/manual/mod/mod_cern_meta.html +++ /dev/null @@ -1,76 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_cern_meta</TITLE> -</HEAD> - -<BODY> -<IMG SRC="../images/apache_sub.gif" ALT=""> -<H1>Apache module mod_cern_meta</h1> - -This module is contained in the <code>mod_cern_meta.c</code> file, and -is not compiled in by default. It provides for CERN httpd metafile -semantics. It is only available in Apache 1.1 and later. - -<h2>Summary</h2> - -Emulate the CERN HTTPD Meta file semantics. Meta files are HTTP -headers that can be output in addition to the normal range of headers -for each file accessed. They appear rather like the Apache -.asis files, and are able to provide a crude way of influencing -the Expires: header, as well as providing other curiosities. -There are many ways to manage meta information, this one was -chosen because there is already a large number of CERN users -who can exploit this module. - -<p>More information on the -<a href="http://www.w3.org/hypertext/WWW/Daemon/User/Config/General.html#MetaDir -">CERN metafile semantics</a> is available. - -<h2>Directives</h2> -<ul> -<li><A HREF="#metadir">MetaDir</A> -<li><A HREF="#metasuffix">MetaSuffix</A> -</ul> - -<hr> - -<A name="metadir"><h2>MetaDir</h2></A> -<strong>Syntax:</strong> MetaDir <em>directory name</em><br> -<strong>Default:</strong> <code>MetaDir .web</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_cern_meta<br> -<strong>Compatibility:</strong> MetaDir is only available in Apache 1.1 -and later.<p> - -Specifies the name of the directory in which Apache can find -meta information files. The directory is usually a 'hidden' -subdirectory of the directory that contains the file being -accessed. Set to "<code>.</code>" to look in the same directory as the -file. - -<A name="metadir"><h2>MetaSuffix</h2></A> -<strong>Syntax:</strong> MetaSuffix <em>suffix</em><br> -<strong>Default:</strong> <code>MetaSuffix .meta</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_cern_meta<br> -<strong>Compatibility:</strong> MetaSuffix is only available in Apache 1.1 -and later.<p> - -Specifies the file name suffix for the file containing the -meta information. For example, the default values for the two -directives will cause a request to <code> -DOCUMENT_ROOT/somedir/index.html</code> to look in -<code>DOCUMENT_ROOT/somedir/.web/index.html.meta</code> and will use -its contents to generate additional MIME header information. - -<p><hr> - -<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> -<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> - -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_cgi.html b/docs/manual/mod/mod_cgi.html deleted file mode 100644 index 5bf6ea78c9..0000000000 --- a/docs/manual/mod/mod_cgi.html +++ /dev/null @@ -1,53 +0,0 @@ -<!--%hypertext --> -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<html> -<head> -<title>Apache module mod_cgi</title> -</head> - -<body> -<IMG SRC="../images/apache_sub.gif" ALT=""> -<!--/%hypertext --> -<h1>Module mod_cgi</h1> - -This module is contained in the <code>mod_cgi.c</code> file, and -is compiled in by default. It provides for execution of CGI scripts. -Any file with mime type <code>application/x-httpd-cgi</code> will be -processed by this module. -<!--%plaintext <?INDEX {\tt application/x-httpd-cgi} mime type> --> -<!--%plaintext <?INDEX CGI scripts> --> - -<h2>Summary</h2> -Any file that has the mime type <code>application/x-httpd-cgi</code> -will be treated as a CGI script, and run by the server, with its output -being returned to the client. Files acquire this type either by -having a name ending in an extension defined by the -<A HREF="mod_mime.html#addtype">AddType</A> directive, or by being in -a <A HREF="mod_alias.html#scriptalias">ScriptAlias</A> directory. <p> - -When the server invokes a CGI script, it will add a variable called -<code>DOCUMENT_ROOT</code> to the environment. This variable will contain the -value of the <A HREF="core.html#documentroot">DocumentRoot</A> -configuration variable. - -<h2>CGI Environment variables</h2> -The server will set the CGI environment variables as described in the CGI -specification, with the following provisos: -<dl> -<dt>REMOTE_HOST -<dd>This will only be set if the server has not been compiled with -<code>MINIMAL_DNS</code>. -<dt>REMOTE_IDENT -<dd>This will only be set if -<A HREF="core.html#identitycheck">IdentityCheck</A> is set to <code>on</code>. -<dt>REMOTE_USER -<dd>This will only be set if the CGI script is subject to authentication. -</dl> -<P> -<!--%hypertext --> -<HR> -<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> -<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> -</BODY> -</HTML> -<!--/%hypertext --> diff --git a/docs/manual/mod/mod_dir.html b/docs/manual/mod/mod_dir.html deleted file mode 100644 index 960c89ca13..0000000000 --- a/docs/manual/mod/mod_dir.html +++ /dev/null @@ -1,309 +0,0 @@ -<!--%hypertext --> -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_dir</TITLE> -</HEAD> - -<BODY> -<IMG SRC="../images/apache_sub.gif" ALT=""> -<!--/%hypertext --> -<H1>Module mod_dir</h1> - -This module is contained in the <code>mod_dir.c</code> file, and -is compiled in by default. It provides for directory indexing. - -<h2>Summary</h2> -This module controls the directory indexing. The index of a directory -can come from one of two sources: -<ul> -<li>A file written by the user, typically called <code>index.html</code>. -The <A HREF="#directoryindex">DirectoryIndex</A> directive sets the name -of this file. -<li>Otherwise, a listing generated by the server. The other directives -control the format of this listing. The <A HREF="#addicon">AddIcon</A>, -<A HREF="#addiconbyencoding">AddIconByEncoding</A> and -<A HREF="#addiconbytype">AddIconByType</A> are used to set a list of -icons to display for various file types; for each file listed, the -first icon listed that matches the file is displayed. -</ul> - -<!--%hypertext --> -<h2>Directives</h2> - -<menu> -<li><A HREF="#adddescription">AddDescription</A> -<li><A HREF="#addicon">AddIcon</A> -<li><A HREF="#addiconbyencoding">AddIconByEncoding</A> -<li><A HREF="#addiconbytype">AddIconByType</A> -<li><A HREF="#defaulticon">DefaultIcon</A> -<li><A HREF="#directoryindex">DirectoryIndex</A> -<li><A HREF="#fancyindexing">FancyIndexing</A> -<li><A HREF="#headername">HeaderName</A> -<li><A HREF="#indexignore">IndexIgnore</A> -<li><A HREF="#indexoptions">IndexOptions</A> -<li><A HREF="#readmename">ReadmeName</A> -</menu> -<hr> -<!--/%hypertext --> - -<A name="adddescription"><h2>AddDescription</h2></A> -<!--%plaintext <?INDEX {\tt AddDescription} directive> --> -<strong>Syntax:</strong> AddDescription <em>string file file...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -This sets the description to display for a file, for -<A HREF="#fancyindexing">FancyIndexing</A>. <em>File</em> is a file -extension, partial filename, wildcard expression or full filename for files -to describe. <em>String</em> is enclosed in double quotes -(<code>"</code>). Example: -<blockquote><code>AddDescription "The planet Mars" /web/pics/mars.gif -</code></blockquote><p><hr> - -<A name="addicon"><h2>AddIcon</h2></A> -<!--%plaintext <?INDEX {\tt AddIcon} directive> --> -<strong>Syntax:</strong> AddIcon <em>icon name name ...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -This sets the icon to display next to a file ending in <em>name</em> for -<A HREF="#fancyindexing">FancyIndexing</A>. <em>Icon</em> is either a -(%-escaped) relative URL to the icon, or of the format -(<em>alttext</em>,<em>url</em>) where <em>alttext</em> is the text tag given -for an icon for non-graphical browsers.<p> - -<em>Name</em> is either ^^DIRECTORY^^ for directories, ^^BLANKICON^^ for -blank lines (to format the list correctly), a file extension, a wildcard -expression, a partial filename or a complete filename. Examples: -<blockquote><code> -AddIcon (IMG,/icons/image.xbm) .gif .jpg .xbm <br> -AddIcon /icons/dir.xbm ^^DIRECTORY^^ <br> -AddIcon /icons/backup.xbm *~ -</code></blockquote> -<A HREF="#addiconbytype">AddIconByType</A> should be used in preference to -AddIcon, when possible.<p><hr> - -<A name="addiconbyencoding"><h2>AddIconByEncoding</h2></A> -<!--%plaintext <?INDEX {\tt AddIconByEncoding} directive> --> -<strong>Syntax:</strong> AddIconByEncoding <em>icon mime-encoding mime-encoding -...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -This sets the icon to display next to files with -<em>mime-encoding</em> for <A HREF="#fancyindexing">FancyIndexing</A>. -<em>Icon</em> is either a (%-escaped) relative URL to the icon, or of the -format (<em>alttext</em>,<em>url</em>) where <em>alttext</em> is the text tag -given for an icon for non-graphical browsers.<p> - -<em>Mime-encoding</em> is a wildcard expression matching required the -content-encoding. Examples: -<blockquote><code> -AddIconByEncoding /icons/compress.xbm x-compress -</code></blockquote><p><hr> - -<A name="addiconbytype"><h2>AddIconByType</h2></A> -<!--%plaintext <?INDEX {\tt AddIconByType} directive> --> -<strong>Syntax:</strong> AddIconByType <em>icon mime-type mime-type ...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -This sets the icon to display next to files of type <em>mime-type</em> for -<A HREF="#fancyindexing">FancyIndexing</A>. <em>Icon</em> is either a -(%-escaped) relative URL to the icon, or of the format -(<em>alttext</em>,<em>url</em>) where <em>alttext</em> is the text tag given -for an icon for non-graphical browsers.<p> -<em>Mime-type</em> is a wildcard expression matching required the mime types. -Examples: -<blockquote><code> -AddIconByType (IMG,/icons/image.xbm) image/* -</code></blockquote><p><hr> - -<A name="defaulticon"><h2>DefaultIcon</h2></A> -<!--%plaintext <?INDEX {\tt DefaultIcon} directive> --> -<strong>Syntax:</strong> DefaultIcon <em>url</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -The DefaultIcon directive sets the icon to display for files when no -specific icon is known, for <A HREF="#fancyindexing">FancyIndexing</A>. -<em>Url</em> is a (%-escaped) relative URL to the icon. Examples: -<blockquote><code> -DefaultIcon /icon/unknown.xbm -</code></blockquote><p><hr> - -<A name="directoryindex"><h2>DirectoryIndex</h2></A> -<!--%plaintext <?INDEX {\tt DirectoryIndex} directive> --> -<strong>Syntax:</strong> DirectoryIndex <em>local-url local-url ...</em><br> -<strong>Default:</strong> <code>DirectoryIndex index.html</code><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -The DirectoryIndex directive sets the list of resources to look for, when -the client requests an index of the directory by specifying a NULL file -at the end of the a directory name. <em>Local-url</em> is the (%-encoded) URL -of a document on the server relative to the requested directory; it is usually -the name of a file in the directory. Several URLs may be given; the server -will return the first one that it finds. If none of the resources exist, -then the server will generate its own listing of the directory. -Example: -<blockquote><code> -DirectoryIndex index.html -</code></blockquote> -then a request for <code>http://myserver/docs/</code> would return -<code>http://myserver/docs/index.html</code> if it exists, or would list -the directory if it did not. <p> - -Note that the documents do not need to be relative to the directory; -<blockquote><code> -DirectoryIndex index.html index.txt /cgi-bin/index.pl</code></blockquote> -would cause the CGI script <code>/cgi-bin/index.pl</code> to be executed -if neither <code>index.html</code> or <code>index.txt</code> existed in -a directory.<p><hr> - -<A name="fancyindexing"><h2>FancyIndexing</h2></A> -<!--%plaintext <?INDEX {\tt FancyIndexing} directive> --> -<strong>Syntax:</strong> FancyIndexing <em>boolean</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -The FancyIndexing directive sets the FancyIndexing option for a directory. -<em>Boolean</em> can be <code>on</code> or <code>off</code>. The -<A HREF="#indexoptions">IndexOptions</A> directive should be used in -preference.<p><hr> - -<A name="headername"><h2>HeaderName</h2></A> -<!--%plaintext <?INDEX {\tt HeaderName} directive> --> -<strong>Syntax:</strong> HeaderName <em>filename</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -The HeaderName directive sets the name of the file that will be inserted -at the top of the index listing. <em>Filename</em> is the name of the file -to include, and is taken to be relative to the directory being indexed. -The server first attempts to include <em>filename</em><code>.html</code> -as an HTML document, otherwise it will include <em>filename</em> as plain -text. Example: -<blockquote><code>HeaderName HEADER</code></blockquote> -when indexing the directory <code>/web</code>, the server will first look for -the HTML file <code>/web/HEADER.html</code> and include it if found, otherwise -it will include the plain text file <code>/web/HEADER</code>, if it exists. - -<p>See also <A HREF="#readmename">ReadmeName</A>.<p><hr> - -<A name="indexignore"><h2>IndexIgnore</h2></A> -<!--%plaintext <?INDEX {\tt IndexIgnore} directive> --> -<strong>Syntax:</strong> IndexIgnore <em>file file ...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -The IndexIgnore directive adds to the list of files to hide when listing -a directory. <em>File</em> is a file extension, partial filename, -wildcard expression or full filename for files to ignore. Multiple -IndexIgnore directives add to the list, rather than the replacing the list -of ignored files. By default, the list contains `<code>.</code>'. Example: -<blockquote><code> -IndexIgnore README .htaccess *~ -</code></blockquote><p><hr> - -<A name="indexoptions"><h2>IndexOptions</h2></A> -<!--%plaintext <?INDEX {\tt IndexOptions} directive> --> -<strong>Syntax:</strong> IndexOptions <em>option option ...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -The IndexOptions directive specifies the behaviour of the directory indexing. -<em>Option</em> can be one of -<dl> -<dt>FancyIndexing -<dd><!--%plaintext <?INDEX {\tt FancyIndexing} index option> --> -This turns on fancy indexing of directories. -<dt>IconsAreLinks -<dd> -<!--%plaintext <?INDEX {\tt IconsAreLinks} index option> --> -This makes the icons part of the anchor for the filename, for -fancy indexing. -<dt>ScanHTMLTitles -<dd><!--%plaintext <?INDEX {\tt ScanHTMLTitles} index option> --> -This enables the extraction of the title from HTML documents for fancy -indexing. If the file does not have a description given by -<A HREF="#adddescription">AddDescription</A> then httpd will read the -document for the value of the TITLE tag. This is CPU and disk intensive. -<dt>SuppressLastModified -<dd> -<!--%plaintext <?INDEX {\tt SuppressLastModified} index option> --> -This will suppress the display of the last modification date, in fancy -indexing listings. -<dt>SuppressSize -<dd> -<!--%plaintext <?INDEX {\tt SuppressSize} index option> --> -This will suppress the file size in fancy indexing listings. -<dt>SuppressDescription -<dd> -<!--%plaintext <?INDEX {\tt SuppressDescription} index option> --> -This will suppress the file description in fancy indexing listings. -</dl> -This default is that no options are enabled. If multiple IndexOptions -could apply to a directory, then the most specific one is taken complete; -the options are not merged. For example: -<blockquote><code> -<Directory /web/docs> <br> -IndexOptions FancyIndexing <br> -</Directory><br> -<Directory /web/docs/spec> <br> -IndexOptions ScanHTMLTitles <br> -</Directory> -</code></blockquote> -then only <code>ScanHTMLTitles</code> will be set for the /web/docs/spec -directory.<p><hr> - -<A name="readmename"><h2>ReadmeName</h2></A> -<!--%plaintext <?INDEX {\tt ReadmeName} directive> --> -<strong>Syntax:</strong> ReadmeName <em>filename</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_dir<p> - -The ReadmeName directive sets the name of the file that will be appended -to the end of the index listing. <em>Filename</em> is the name of the file -to include, and is taken to be relative to the directory being indexed. -The server first attempts to include <em>filename</em><code>.html</code> -as an HTML document, otherwise it will include <em>filename</em> as plain -text. Example: -<blockquote><code>ReadmeName README</code></blockquote> -when indexing the directory <code>/web</code>, the server will first look for -the HTML file <code>/web/README.html</code> and include it if found, otherwise -it will include the plain text file <code>/web/README</code>, if it exists. - -<p>See also <A HREF="#headername">HeaderName</A>.<p> - -<!--%hypertext --> -<hr> -<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> -<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> - -</BODY> -</HTML> -<!--/%hypertext --> diff --git a/docs/manual/mod/mod_env.html b/docs/manual/mod/mod_env.html deleted file mode 100644 index 3e32d26080..0000000000 --- a/docs/manual/mod/mod_env.html +++ /dev/null @@ -1,68 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_env</TITLE> -</HEAD> - -<BODY> -<IMG SRC="../images/apache_sub.gif" ALT=""> -<H1>Apache module mod_env</h1> - -This module is contained in the <code>mod_env.c</code> file, and -is not compiled in by default. It provides for -passing environment variables to CGI/SSI scripts. Is is only available -in Apache 1.1 and later. - -<h2>Summary</h2> - -This module allows Apache's CGI and SSI environment to inherit -environment variables from the shell which invoked the httpd process. -CERN webservers are able to do this, so this module is especially -useful to webadmins who wish to migrate from CERN to Apache without -rewriting all their scripts - -<h2>Directives</h2> -<ul> -<li><A HREF="#passenv">PassEnv</A> -<li><A HREF="#setenv">SetEnv</A> -</ul> - -<hr> - -<A name="passenv"><h2>PassEnv</h2></A> -<strong>Syntax:</strong> PassEnv <em>variable</em><br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_env<br> -<strong>Compatibility:</strong> PassEnv is only available in -Apache 1.1 and later.<p> - -Passes an environment variable to CGI scripts from the servers's own -environment. Example: -<pre> - PassEnv LD_LIBRARY_PATH -</pre> - - -<A name="setenv"><h2>SetEnv</h2></A> -<strong>Syntax:</strong> SetEnv <em>variable value</em><br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_env<br> -<strong>Compatibility:</strong> SetEnv is only available in -Apache 1.1 and later.<p> - -Sets an environment variable, which is then passed on to CGI -scripts. Example: -<pre> - SetEnv SPECIAL_PATH /foo/bin -</pre> - -<p><hr> - -<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> -<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> - -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_example.html b/docs/manual/mod/mod_example.html deleted file mode 100644 index 05fb8ef721..0000000000 --- a/docs/manual/mod/mod_example.html +++ /dev/null @@ -1,133 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> - <HEAD> - <TITLE>Apache module mod_example</TITLE> - </HEAD> - <BODY> - <!--#include virtual="header.html" --> - <H1>Module mod_example</h1> - <P> - This module is contained in the <CODE>modules/mod_example.c</CODE> file, and - <STRONG>is not</STRONG> compiled in by default. It illustrates many of - the aspects of the - <A - HREF="../misc/API.html" - REL="Help" - >Apache 1.2 API</A> - and, when used, demonstrates the manner in which module callbacks are - triggered by the server. - </P> - <H2>Summary</H2> - <P> - The files in the <CODE>src/modules/example directory</CODE> under the - Apache distribution directory tree are provided as an example to those - that wish to write modules that use the Apache API. - </P> - <P> - The main file is <CODE>mod_example.c</CODE>, which illustrates all - the different callback mechanisms and call syntaces. By no means does - an add-on module need to include routines for all of the callbacks - - quite the contrary! - </P> - <P> - The example module is an actual working module. If you link it into - your server, enable the "example-handler" handler for a location, and - then browse to that location, you will see a display of - some of the tracing the example module did as the various callbacks - were made. - </P> - <P> - To include the example module in your server, follow the steps below: - </P> - <OL> - <LI>Uncomment the "Module example_module" line near the bottom of - the <CODE>src/Configuration</CODE> file. If there isn't one, add - it; it should look like this: - <PRE> - Module example_module modules/example/mod_example.o - </PRE> - </LI> - <LI>Run the <CODE>src/Configure</CODE> script - ("<SAMP>cd src; ./Configure</SAMP>"). This will - build the Makefile for the server itself, and update the - <CODE>src/modules/Makefile</CODE> for any additional modules you - have requested from beneath that subdirectory. - </LI> - <LI>Make the server (run "<SAMP>make</SAMP>" in the <CODE>src</CODE> - directory). - </LI> - </OL> - <P> - To add another module of your own: - </P> - <OL TYPE="A"> - <LI><SAMP>mkdir src/modules/<EM>mymodule</EM></SAMP> - </LI> - <LI><SAMP>cp src/modules/example/* src/modules/<EM>mymodule</EM></SAMP> - </LI> - <LI>Modify the files in the new directory. - </LI> - <LI>Follow steps [1] through [3] above, with appropriate changes. - </LI> - </OL> - <H3> - Using the <SAMP>mod_example</SAMP> Module - </H3> - <P> - To activate the example module, include a block similar to the - following in your <SAMP>srm.conf</SAMP> file: - </P> - <PRE> - <Location /example-info> - SetHandler example-handler - </Location> - </PRE> - <P> - As an alternative, you can put the following into a - <A - HREF="core.html#accessfilename" - ><SAMP>.htaccess</SAMP></A> - file and then request the file "test.example" from that - location: - </P> - <PRE> - AddHandler example-handler .example - </PRE> - <P> - After reloading/restarting your server, you should be able to browse - to this location and see the brief display mentioned earlier. - </P> - <H2>Directives</H2> - <P> - <UL> - <LI><A HREF="#example">Example</A> - </LI> - </UL> - </P> - <HR> - <A NAME="example"> - <H2>Example</H2> - </A> - <P> - <STRONG>Syntax:</STRONG> Example - <BR> - <STRONG>Default:</STRONG> None - <BR> - <STRONG>Context:</STRONG> server config, virtual host, directory, .htaccess - <BR> - <STRONG>Override:</STRONG> Options - <BR> - <STRONG>Status:</STRONG> Extension - <BR> - <STRONG>Module:</STRONG> mod_example - </P> - <P> - The Example directive activates the example module's content handler - for a particular location or file type. It takes no arguments. If - you browse to an URL to which the example content-handler applies, you - will get a display of the routines within the module and how and in - what order they were called to service the document request. - </P> - <!--#include virtual="footer.html" --> - </BODY> -</HTML> diff --git a/docs/manual/mod/mod_expires.html b/docs/manual/mod/mod_expires.html deleted file mode 100644 index 4dbab5f246..0000000000 --- a/docs/manual/mod/mod_expires.html +++ /dev/null @@ -1,178 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> - <HEAD> - <TITLE>Apache module mod_expires</TITLE> - </HEAD> - <BODY> - <!--#include virtual="header.html" --> - <H1>Module mod_expires</H1> - <P> - This module is contained in the <CODE>mod_expires.c</CODE> file, and - is <STRONG>not</STRONG> compiled in by default. It provides for the - generation of <CODE>Expires</CODE> headers according to user-specified - criteria. - </P> - <H2>Summary</H2> - <P> - This module controls the setting of the <CODE>Expires</CODE> HTTP - header in server responses. The expiration date can set to be - relative to either the time the source file was last modified, or to - the time of the client access. - </P> - <P> - The <CODE>Expires</CODE> HTTP header is an instruction to the client - about the document's validity and persistence. If cached, the document - may be fetched from the cache rather than from the source until this - time has passed. After that, the cache copy is considered - "expired" and invalid, and a new copy must be obtained from - the source. - </P> - <H2>Directives</H2> - <P> - <MENU> - <LI><A - HREF="#expiresactive" - >ExpiresActive</A> - </LI> - <LI><A - HREF="#expiresbytype" - >ExpiresByType</A> - </LI> - <LI><A - HREF="#expiresdefault" - >ExpiresDefault</A> - </LI> - </MENU> - <HR> - <A NAME="expiresactive"> - <H2>ExpiresActive directive</H2> - </A> - <!--%plaintext <?INDEX {\tt ExpiresActive} directive> --> - <P> - <STRONG>Syntax:</STRONG> ExpiresActive <EM>boolean</EM> - <BR> - <STRONG>Context:</STRONG> server config, virtual host, directory, .htaccess - <br> - <STRONG>Override:</STRONG> Indexes - <br> - <STRONG>Status:</STRONG> Extension - <br> - <STRONG>Module:</STRONG> mod_expires - </P> - <P> - This directive enables or disables the generation of the - <CODE>Expires</CODE> header for the document realm in question. (That - is, if found in an <CODE>.htaccess</CODE> file, for instance, it - applies only to documents generated from that directory.) If set to - <EM><CODE>Off</CODE></EM>, no <CODE>Expires</CODE> header will be - generated for any document in the realm (unless overridden at a lower - level, such as an <CODE>.htaccess</CODE> file overriding a server - config file). If set to <EM><CODE>On</CODE></EM>, the header will be - added to served documents according to the criteria defined by the - <A - HREF="expiresbytype" - >ExpiresByType</A> - and - <A - HREF="#expiresdefault" - >ExpiresDefault</A> - directives (<EM>q.v.</EM>). - </P> - <P> - Note that this directive does not guarantee that an - <CODE>Expires</CODE> header will be generated. If the criteria aren't - met, no header will be sent, and the effect will be as though this - directive wasn't even specified. - </P> - <HR> - <A NAME="expiresbytype"> - <H2>ExpiresByType directive</H2> - </A> - <!--%plaintext <?INDEX {\tt ExpiresByType} directive> --> - <P> - <STRONG>Syntax:</STRONG> ExpiresByType <EM>mime-type <code>seconds</EM> - <BR> - <STRONG>Context:</STRONG> server config, virtual host, directory, .htaccess - <br> - <STRONG>Override:</STRONG> Indexes - <br> - <STRONG>Status:</STRONG> Extension - <br> - <STRONG>Module:</STRONG> mod_expires - </P> - <P> - This directive defines the value of the <CODE>Expires</CODE> header - generated for documents of the specified type (<EM>e.g.</EM>, - <CODE>text/html</CODE>). The second argument sets the number of - seconds that will be added to a base time to construct the expiration - date. - </P> - <P> - The base time is either the last modification time of the file, or the - time of the client's access to the document. Which should be used is - specified by the <CODE><EM><code></EM></CODE> field; - <STRONG>M</STRONG> means that the file's last modification time should - be used as the base time, and <STRONG>A</STRONG> means the client's - access time should be used. - </P> - <P> - The difference in effect is subtle. If <EM>M</EM> is used, all current - copies of the document in all caches will expire at the same time, - which can be good for something like a weekly notice that's always - found at the same URL. If <EM>A</EM> is used, the date of expiration - is different for each client; this can be good for image files that - don't change very often, particularly for a set of related documents - that all refer to the same images (<EM>i.e.</EM>, the images will be - accessed repeatedly within a relatively short timespan). - </P> - <P> - <STRONG>Example:</STRONG> - </P> - <P> - <PRE> - ExpiresActive On # enable expirations - ExpiresByType image/gif A2592000 # expire GIF images after a month - # in the client's cache - ExpiresByType text/html M604800 # HTML documents are good for a - # week from the time they were - # changed, period - </PRE> - </P> - <P> - Note that this directive only has effect if <CODE>ExpiresActive - On</CODE> has been specified. It overrides, for the specified MIME - type <EM>only</EM>, any expiration date set by the - <A - HREF="#expiresdefault" - >ExpiresDefault</A> - directive. - </P> - <HR> - <A NAME="expiresdefault"> - <H2>ExpiresDefault directive</H2> - </A> - <!--%plaintext <?INDEX {\tt ExpiresDefault} directive> --> - <P> - <STRONG>Syntax:</STRONG> ExpiresDefault <EM><code>seconds</EM> - <BR> - <STRONG>Context:</STRONG> server config, virtual host, directory, .htaccess - <br> - <STRONG>Override:</STRONG> Indexes - <br> - <STRONG>Status:</STRONG> Extension - <br> - <STRONG>Module:</STRONG> mod_expires - </P> - <P> - This directive sets the default algorithm for calculating the - expiration time for all documents in the affected realm. It can be - overridden on a type-by-type basis by the - <A - HREF="#expiresbytype" - >ExpiresByType</A> - directive. See the description of that directive for details about - the syntax of the argument. - </P> - <!--#include virtual="footer.html" --> - </BODY> -</HTML> diff --git a/docs/manual/mod/mod_headers.html b/docs/manual/mod/mod_headers.html deleted file mode 100644 index db25271583..0000000000 --- a/docs/manual/mod/mod_headers.html +++ /dev/null @@ -1,97 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_headers</TITLE> -</HEAD> - -<BODY> -<!--#include virtual="header.html" --> -<h1>Headers Module</h1> - -The optional headers module allows for the customisation of HTTP -response headers. Headers can be merged, replaced or removed. The -directives described in this document are only available if Apache is -compiled with <b>mod_headers.c</b>. - -<hr> - -<h2>Directive</h2> -<ul> -<li><A HREF="#header">Header</A> -</ul> - -<hr> - -<A name="header"><h2>Header</h2></A> -<strong>Sytnax:</strong> Header [ set | append | add ] <em>header</em> <em>value</em><br> -<strong>Sytnax:</strong> Header unset <em>header</em><br> -<strong>Context:</strong> server config, virtual host, access.conf, .htaccess<br> -<strong>Status:</strong> optional<br> -<strong>Module:</strong> mod_header<p> - -This directive can replace, merge or remove HTTP response headers. The -action it performs is determined by the first argument. This can be one -of the following values: - -<ul> -<li><b>set</b><br> - The response header is set, replacing any previous header with this name - -<li><b>append</b><br> - The response header is appended to any existing header of the same - name. When a new value is merged onto an existing header it is - separated from the existing header with a comma. This is the HTTP standard - way of giving a header multiple values. - -<li><b>add</b><br> - The response header is added to the existing set of headers, even if - this header already exists. This can result in two (or more) headers - having the same name. This can lead to unforseen consequences, and in - general "append" should be used instead. - -<li><b>unset</b><br> - The response header of this name is removed, if it exists. If there are - multiple headers of the same name, only the first one set will be removed. -</ul> - -This argument is followed by a header name, which can include the -final colon, but it is not required. Case is ignored. For -add, append and set a value is given as the third argument. If this -value contains spaces, it should be surrounded by double quotes. -For unset, no value should be given. - -<h3>Order of Processing</h3> - -The Header directive can occur almost anywhere within the server -configuration. It is valid in the main server config and virtual host -sections, inside <Directory>, <Location> and <Files> -sections, and within .htaccess files. -<p> -The Header directives are processed in the following order: -<ol> -<li>main server -<li>virtual host -<li><Directory> sections and .htaccess -<li><Location> -<li><Files> -</ol> - -Order is important. These two headers have a different effect if reversed: -<pre> -Header append Author "John P. Doe" -Header unset Author -</pre> - -This way round, the Author header is not set. If reversed, the Author -header is set to "John P. Doe". -<p> - -The Header directives are processed just before the response is sent -by its handler. These means that some headers that are added just -before the response is sent cannot be unset or overridden. This -includes headers such as "Date" and "Server". -<P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/mod/mod_imap.html b/docs/manual/mod/mod_imap.html deleted file mode 100644 index 195ae374b4..0000000000 --- a/docs/manual/mod/mod_imap.html +++ /dev/null @@ -1,284 +0,0 @@ -<!--%hypertext --> -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<html> -<head> -<title>Apache module mod_imap</title> -</head> - -<body> -<IMG SRC="../images/apache_sub.gif" ALT=""> -<!--/%hypertext --> -<h1>Module mod_imap</h1> - -This module is contained in the <code>mod_imap.c</code> file, and -is compiled in by default. It provides for <code>.map</code> files, -replacing the functionality of the <code>imagemap</code> CGI program. Any -directory or document type configured to use the handler <code>imap-file</code> -(using either <code><A -HREF="http://www.apache.org/docs/mod_mime.html#addhandler">AddHandler</A> -</code> or <code><A -HREF="http://www.apache.org/docs/mod_mime.html#sethandler">SetHandler</A></code>) - -will be -processed by this module. - -<h2>Summary</h2> - -This module is in the default Apache distribution. The following directive will -activate files ending with <code>.map</code> as imagemap files: - -<blockquote><code>AddHandler imap-file map</code></blockquote> - -Note that the following is still supported: - - <blockquote><code>AddType application/x-httpd-imap map</code></blockquote> - -However, we are trying to phase out "magic MIME types" so we are deprecating -this method. - -<H2>New Features</H2> -The imagemap module adds some new features that were not -possible with previously distributed imagemap programs.<P> - -<ul> -<LI>URL references relative to the Referer: information. -<LI>Default <BASE> assignment through a new map directive -<code>base</code>. -<LI>No need for <code>imagemap.conf</code> file. -<LI>Point references. -<LI>Configurable generation of imagemap menus. -</ul> -<P> - -<h2>Configuration Directives</h2> -<ul> -<li><A HREF="#imapmenu">ImapMenu</A> -<li><A HREF="#imapdefault">ImapDefault</A> -<li><A HREF="#imapbase">ImapBase</A> -</ul> - - -<p> - -<A name="imapmenu"><h3>ImapMenu</h3></A> -<strong>Syntax:</strong> ImapMenu <code>{none, formatted, semiformatted, - unformatted}</code><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Module:</strong> mod_imap.c<br> -<strong>Compatibility:</strong> ImapMenu is only available in Apache -1.1 and later.<p> - -The ImapMenu directive determines the action taken if an imagemap file -is called without valid coordinates. -<dl> - <dt><code>none</code> - <dd>If ImapMenu is - <code>none</code>, no menu is generated, and the <code>default</code> - action is performed. - <dt><code>formatted</code> - <dd>A <code>formatted</code> menu is the simplest menu. Comments - in the imagemap file are ignored. A level one header is - printed, then an hrule, then the links each on a separate line. - The menu has a consistent, plain look close to that of - a directory listing. - <dt><code>semiformatted</code> - <dd>In the <code>semiformatted</code> menu, comments are printed - where they occur in the imagemap file. Blank lines are turned - into HTML breaks. No header or hrule is printed, but otherwise - the menu is the same as a <code>formatted</code> menu. - <dt><code>unformatted</code> - <dd>Comments are printed, blank lines are ignored. Nothing is - printed that does not appear in the imagemap file. All breaks - and headers must be included as comments in the imagemap file. - This gives you the most flexibility over the appearance of your - menus, but requires you to treat your map files as HTML instead - of plaintext. -</dl> - -<p> - -<A name="imapdefault"><h3>ImapDefault</h3></A> -<strong>Syntax:</strong> ImapDefault <code>{error, nocontent, - map, referer, URL}</code><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Module:</strong> mod_imap.c<br> -<strong>Compatibility:</strong> ImapDefault is only available in Apache -1.1 and later.<p> - - -The ImapDefault directive sets the default <code>default</code> used in -the imagemap files. It's value is overridden by a <code>default</code> -directive within the imagemap file. If not present, the -<code>default</code> action is <code>nocontent</code>, which means -that a <code>204 No Content</code> is sent to the client. In this -case, the client should continue to display the original page. - -<p> - -<A name="imapbase"><h3>ImapBase</h3></A> -<strong>Syntax:</strong> ImapBase <code>{map, referer, URL}</code><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Indexes<br> -<strong>Module:</strong> mod_imap.c<br> -<strong>Compatibility:</strong> ImapBase is only available in Apache -1.1 and later.<p> - -The ImapBase directive sets the default <code>base</code> used in -the imagemap files. It's value is overridden by a <code>base</code> -directive within the imagemap file. If not present, the -<code>base</code> defaults to <code>http://servername/</code>. - -<hr> -<p> - -<h2>Imagemap File</h2> -The lines in the imagemap files can have one of several formats: -<blockquote> -<code>directive value [x,y ...]</code><br> -<code>directive value "Menu text" [x,y ...]</code><br> -<code>directive value x,y ... "Menu text"</code><br> -</blockquote> -The directive is one of <code>base</code>, <code>default</code>, -<code>poly</code>, <code>circle</code>, <code>rect</code>, or -<code>point</code>. The value is an absolute or relative URL, or one -of the special values listed below. The coordinates are -<code>x,y</code> pairs seperated by whitespace. The quoted text is -used as the text of the link if a imagemap menu is generated. Lines -beginning with '#' are comments. - -<h3>Imagemap File Directives</h3> -There are six directives allowed in the imagemap file. The directives -can come in any order, but are processed in the order they are found -in the imagemap file. -<dl> -<dt><code>base</code> Directive -<dd>Has the effect of <code><BASE href="value"></code>. The - non-absolute URLs of the mapfile are taken relative to this value. - The <code>base</code> directive overrides ImapBase as set in a - .htaccess file or in the server configuration files. In the absence - of an ImapBase configuration directive, <code>base</code> defaults to - <code>http://server_name/</code>. <br> - <code>base_uri</code> is synonymous with <code>base</code>. Note that - a trailing slash on the URL is significant. -<p> -<dt><code>default</code> Directive -<dd>The action taken if the coordinates given do not fit any of the - <code>poly</code>, <code>circle</code> or <code>rect</code> - directives, and there are no <code>point</code> directives. Defaults - to <code>nocontent</code> in the absence of an ImapDefault - configuration setting, causing a status code of <code>204 No - Content</code> to be returned. The client should keep the same - page displayed. -<p> -<dt><code>poly</code> Directive -<dd>Takes three to one-hundred points, and is obeyed if the user selected - coordinates fall within the polygon defined by these points. -<p> -<dt><code>circle</code> -<dd>Takes the center coordinates of a circle and a point on the circle. Is - obeyed if the user selected point is with the circle. -<p> -<dt><code>rect</code> Directive -<dd>Takes the coordinates of two opposing corners of a rectangle. Obeyed - if the point selected is within this rectangle. -<p> -<dt><code>point</code> Directive -<dd>Takes a single point. The point directive closest to the user - selected point is obeyed if no other directives are satisfied. - Note that <code>default</code> will not be followed if a - <code>point</code> directive is present and valid coordinates are - given. -</dl> - - - -<h3>Values</h3> -The values for each of the directives can any of the following: -<dl> - <dt>a URL - <dd>The URL can be relative or absolute URL. Relative URLs can - contain '..' syntax and will be resolved relative to the - <code>base</code> value. <br> - <code>base</code> itself will not resolved according to the current - value. A statement <code>base mailto:</code> will work properly, though. -<p> - <dt><code>map</code> - <dd>Equivalent to the URL of the imagemap file itself. No - coordinates are sent with this, so a menu will be generated - unless ImapMenu is set to 'none'. -<p> - <dt><code>menu</code> - <dd>Synonymous with <code>map</code>. -<p> - <dt><code>referer</code> - <dd>Equivalent to the URL of the refering document. - Defaults to <code>http://servername/</code> if no Referer: - header was present. -<p> - <dt><code>nocontent</code> - <dd>Sends a status code of <code>204 No Content</code>, - telling the client to keep the same page displayed. Valid for - all but <code>base</code>. -<p> - <dt><code>error</code> - <dd>Fails with a <code>500 Server Error</code>. Valid for all but - <code>base</code>, but sort of silly for anything but - <code>default</code>. -</dl> - -<h3>Coordinates</h3> -<dl> - <dt><code>0,0 200,200</code> - <dd>A coordinate consists of an <tt>x</tt> and a <tt>y</tt> value - separated by a comma. The coordinates are separated from each other - by whitespace. To accomodate the way Lynx handles imagemaps, should a - user select the coordinate <code>0,0</code>, it is as if - no coordinate had been selected. -</dl> - -<h3>Quoted Text</h3> -<dl> - <dt><code>"Menu Text"</code> - <dd>After the value or after the coordinates, the line optionally may - contain text within double quotes. This string is used as the - text for the link if a menu is generated:<br> - <code><a href="http://foo.com/">Menu text</a></code><br> - If no quoted text is present, the name of the link will be used - as the text:<br> - <code><a href="http://foo.com/">http://foo.com</a></code><br> - It is impossible to escape double quotes within this text. -</dl> - -<hr> - -<h2>Example Mapfile</h2> -<blockquote><code> -#Comments are printed in a 'formatted' or 'semiformatted' menu. <br> -#And can contain html tags. <hr> <br> -base referer <br> -poly map "Could I have a menu, please?" 0,0 0,10 10,10 10,0 <br> -rect .. 0,0 77,27 "the directory of the referer"<br> -circle http://www.inetnebr.com/lincoln/feedback/ 195,0 305,27 <br> -rect another_file "in same directory as referer" 306,0 419,27 <br> -point http://www.zyzzyva.com/ 100,100 <br> -point http://www.tripod.com/ 200,200 <br> -rect mailto:nate@tripod.com 100,150 200,0 "Bugs?" <br> -</code></blockquote> -<P> - -<h2>Referencing your mapfile</h2> -<blockquote><code> -<A HREF="/maps/imagmap1.map"> <br> -<IMG ISMAP SRC="/images/imagemap1.gif"> <br> -</A> -</code></blockquote><p> -<!--%hypertext --> -<HR> -<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> -<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> -</BODY> -</HTML> -<!--/%hypertext --> - diff --git a/docs/manual/mod/mod_include.html b/docs/manual/mod/mod_include.html deleted file mode 100644 index 770a8e2521..0000000000 --- a/docs/manual/mod/mod_include.html +++ /dev/null @@ -1,211 +0,0 @@ -<!--%hypertext --> -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_include</TITLE> -</HEAD> - -<BODY> -<IMG SRC="../images/apache_sub.gif" ALT=""> -<!--/%hypertext --> -<H1>Module mod_include</h1> - -This module is contained in the <code>mod_include.c</code> file, and -is compiled in by default. It provides for server-parsed html documents, -known as SPML documents. -Any document with mime type <code>text/x-server-parsed-html</code> or -<code>text/x-server-parsed-html3</code> will be parsed by this module, -with the resulting output given the mime type <code>text/html</code>. -<!--%plaintext <?INDEX {\tt text/x-server-parsed-html} mime type> --> -<!--%plaintext <?INDEX {\tt text/x-server-parsed-html3} mime type> --> - -<h2>SPML -- Include file Format</h2> - -The document is parsed as an HTML document, with special commands embedded -as SGML comments. A command has the syntax: -<blockquote><code> -<!--#</code><em>element attribute=value attribute=value ...</em> <code>--> -</code></blockquote> -The value will often be enclosed in double quotes; many commands only allow -a single attribute-value pair. -<p> -The allowed elements are:<p> -<dl> -<dt><strong>config</strong> -<dd> -<!--%plaintext <?INDEX {\tt config} SPML element> --> -This command controls various aspects of the parsing. The valid attributes -are: -<dl> -<dt>errmsg -<dd>The value is a message that is sent back to the client if an error occurs -whilst parsing the document. -<dt>sizefmt -<dd>The value sets the format to be used which displaying the size of a file. -Valid values are <code>bytes</code> for a count in bytes, or -<code>abbrev</code> for a count in Kb or Mb as appropriate. -<dt>timefmt -<dd>The value is a string to be used by the <code>strftime(3)</code> library -routine when printing dates. -</dl> - -<dt><strong>echo</strong> -<dd> -<!--%plaintext <?INDEX {\tt echo} SPML element> --> -This command prints one of the include variables, defined below. -If the variable is unset, it is printed as <code>(none)</code>. -Any dates printed are subject to the currently configured <code>timefmt</code>. -Attributes: -<dl> -<dt>var -<dd>The value is the name of the variable to print. -</dl> - -<dt><strong>exec</strong> -<dd> -<!--%plaintext <?INDEX {\tt exec} SPML element> --> -The exec command executes a given shell command or CGI script. -The IncludesNOEXEC <A HREF="core.html#options">Option</A> disables this command -completely. The valid attributes are: -<dl> -<dt>cgi -<dd> -<!--%plaintext <?INDEX CGI scripts, {\tt exec} element and> --> -The value specifies a (%-encoded) URL relative path to the CGI script. -If the path does not begin with a (/), then it is taken to be relative to -the current document. The document referenced by this path is invoked -as a CGI script, even if the server would not normally recognise it as -such. However, the directory containing the script must be enabled for -CGI scripts (with <A HREF="mod_alias.html#scriptalias">ScriptAlias</A> -or the ExecCGI <A HREF="core.html#options">Option</A>).<p> -<!--%plaintext <?INDEX PATH\_INFO CGI variable> --> -<!--%plaintext <?INDEX QUERY\_STRING CGI variable> --> -The CGI script is given the PATH_INFO and query string (QUERY_STRING) of the -original request from the client; these cannot be specified in the URL path. -The include variables will be available to the script in addition to the -standard <A HREF="mod_cgi.html">CGI</A> environment.<p> -If the script returns a Location: header instead of output, then this -will be translated into an HTML anchor.<p> -The <code>include virtual</code> element should be used in preference to -<code>exec cgi</code>. -<dt>cmd -<dd>The server will execute the given string using <code>/bin/sh</code>. -The include variables are available to the command. -</dl> - -<dt><strong>fsize</strong> -<dd> -<!--%plaintext <?INDEX {\tt fsize} SPML element> --> -This command prints the size of the specified file, subject to the -<code>sizefmt</code> format specification. Attributes: -<dl> -<dt>file -<dd>The value is a path relative to the directory containing the current -document being parsed. -<dt>virtual -<dd>The value is a (%-encoded) URL-path relative to the current document being -parsed. If it does not begin with a slash (/) then it is taken to be relative -to the current document. -</dl> - -<dt><strong>flastmod</strong> -<dd><!--%plaintext <?INDEX {\tt exec} flastmod element> --> -This command prints the last modification date of the specified file, -subject to the <code>timefmt</code> format specification. The attributes are -the same as for the <code>fsize</code> command. - -<dt><strong>include</strong> -<dd><!--%plaintext <?INDEX {\tt include} SPML element> --> -This command inserts the text of another document or file into the parsed -file. Any included file is subject to the usual access control. If the -directory containing the parsed file has the -<A HREF="core.html#options">Option</A> -IncludesNOEXEC set, and the including the document would cause a program -to be executed, then it will not be included; this prevents the execution of -CGI scripts. Otherwise CGI scripts are invoked as normal using the complete -URL given in the command, including any query string. -<!--%plaintext <?INDEX CGI scripts, {\tt include} element and> --> -<p> - -An attribute defines the location of the document; the inclusion is done for -each attribute given to the include command. The valid attributes are: -<dl> -<dt>file -<dd>The value is a path relative to the directory containing the current -document being parsed. It cannot contain <code>../</code>, nor can it be an -absolute path. The <code>virtual</code> attribute should always be used -in preference to this one. -<dt>virtual -<dd>The value is a (%-encoded) URL relative to the current document being -parsed. The URL cannot contain a scheme or hostname, only a path and -an optional query string. If it does not begin with a slash (/) then it -is taken to be relative to the current document. -</dl> -A URL is constructed from the attribute, and the output the server -would return if the URL were accessed by the client is included in the parsed -output. Thus included files can be nested. -</dl> - -<h2>Include variables</h2> -These are available for the <code>echo</code> command, and to any program -invoked by the document. -<dl> -<dt>DATE_GMT -<dd>The current date in Greenwich Mean Time. -<dt>DATE_LOCAL -<dd>The current date in the local time zone. -<dt>DOCUMENT_NAME -<dd>The filename (excluding directories) of the document requested by the -user. -<dt>DOCUMENT_URI -<dd>The (%-decoded) URL path of the document requested by the user. Note that -in the case of nested include files, this is <em>not</em> then URL for the -current document. -<dt>LAST_MODIFIED -<dd>The last modification date of the document requested by the user. -</dl> -<p> - -<!--%hypertext --> -<hr> -<h2>Directives</h2> -<ul> -<li><A HREF="#xbithack">XBitHack</A> -</ul> -<hr> -<!--/%hypertext --> - -<A name="xbithack"><h2>XBitHack</h2></A> -<!--%plaintext <?INDEX {\tt XBitHack} directive> --> -<strong>Syntax:</strong> XBitHack <em>status</em><br> -<strong>Default:</strong> <code>XBitHack off</code><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> Options<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_include<p> - -The XBitHack directives controls the parsing of ordinary html documents. -<em>Status</em> can have the following values: -<dl> -<dt>off -<dd>No special treatment of executable files. -<dt>on -<dd>Any file that has the user-execute bit set will be treated as a -server-parsed html document. -<dt>full -<dd>As for <code>on</code> but also test the group-execute bit. If it -is set, then set the Last-modified date of the returned file to be the -last modified time of the file. If it is not set, then no last-modified date -is sent. Setting this bit allows clients and proxies to cache the result of -the request. -</dl> -<p> -<!--%hypertext --> -<hr> - -<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> -<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> - -</BODY> -</HTML> -<!--/%hypertext --> diff --git a/docs/manual/mod/mod_info.html b/docs/manual/mod/mod_info.html deleted file mode 100644 index 6261f5f32b..0000000000 --- a/docs/manual/mod/mod_info.html +++ /dev/null @@ -1,44 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<html> -<head> -<title>Apache module mod_info</title> -</head> - -<body> -<IMG SRC="../images/apache_sub.gif" ALT=""> -<h1>Module mod_info</h1> - -This module is contained in the <code>mod_info.c</code> file. It -provides a comprehensive overview of the current server configuration -including all installed modules. This module is not compiled into the -server by default. It is only available in Apache 1.1 and later. To -enable it, add the following line to the server build Configuration -file, and rebuild the server: - -<PRE> -Module info_module mod_info.o -</PRE> - -<HR> -<P> -To configure it, add the following to your <code>access.conf</code> file. - -<PRE> -<Location /server-info> -SetHandler server-info -</Location> -</PRE> - -You may wish to add a limit clause inside the location directive to limit -access to your server configuration information.<p> -Once configured, the server information is obtained by accessing -<tt>http://your.host.dom/server-info</tt><p> - -<!--%hypertext --> -<hr> -<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> -<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> - -</BODY> -</HTML> -<!--/%hypertext --> diff --git a/docs/manual/mod/mod_isapi.html b/docs/manual/mod/mod_isapi.html deleted file mode 100644 index 5fde08c1a7..0000000000 --- a/docs/manual/mod/mod_isapi.html +++ /dev/null @@ -1,73 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_isapi</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">Module mod_isapi</h1> - -<p>This module is contained in the <code>mod_isapi.c</code> file, and is - compiled in by default. It provides support for ISAPI Extensions when - running under Microsoft Windows. Any document with a handler of - <code>isapi-isa</code> will be processed by this module. - -<h2>Purpose</h2> - -<p>This module implements the <a - href="http://www.microsoft.com/win32dev/apiext/isapimrg.htm">ISAPI - Extension</a> API. It allows Internet Server Applications (i.e., ISAPI - Extensions) to be used with Apache for Windows. - -<h2>Usage</h2> - -<p>In the server configuration file, add a handler called - <code>isapi-isa</code>, and map it to files with a <code>.DLL</code> - extension. In other words:</p> -<pre> - AddHandler isapi-isa dll -</pre> -<p>Now simply place the ISA DLLs into your document root, and they will - be loaded when their URLs are accessed.</p> - -<p>ISAPI Extensions are governed by the same restrictions as CGI - scripts. That is, <code>Options ExecCGI</code> must be active in the - directory that contains the ISA.</p> - -<h2>Notes</h2> - -<p>Apache's ISAPI implementation conforms to all of the ISAPI 2.0 - specification, except for the "Microsoft-specific" extensions dealing - with ascynchronous I/O. Apache's I/O model does not allow asynchronous - reading and writing in a manner that the ISAPI could access. If an ISA - tries to access async I/O, a message will be place in the error log, - to help with debugging. - -<p>Some servers, like Microsoft IIS, load the ISA into the server, and - keep it loaded until memory usage is too high, and it is - unloaded. Apache currently loads and unloads the ISA for each - request. This is inefficient, but Apache's request model makes this - method the only method that currently works. A future release may use - a more effective loading method. - -<p>Apache 1.3a1 currently limits POST and PUT input to 48k per - request. This is to work around a problem with the ISAPI implementation - that could result in a denial of service attack. It is expected that - support for larger uploads will be added soon. - -<p>Also, remember that while Apache supports ISAPI Extensions, it does - not support ISAPI Filters. Support for filters may be added at a later - date, but no support is planned at this time.</p> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/mod/mod_log_config.html b/docs/manual/mod/mod_log_config.html deleted file mode 100644 index 6855ec5c61..0000000000 --- a/docs/manual/mod/mod_log_config.html +++ /dev/null @@ -1,144 +0,0 @@ -<!--%hypertext --> -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_log_config</TITLE> -</HEAD> - -<BODY> -<IMG SRC="../images/apache_sub.gif" ALT=""> -<!--/%hypertext --> -<H1>Module mod_log_config</h1> - -This module is contained in the <code>mod_log_config.c</code> file, and is not -compiled in by default. It provides for logging of the requests made to -the server, using a user-specified format. - -<h2>Summary</h2> -This is an EXPERIMENTAL module, which implements the TransferLog directive -(same as the common log module), and an additional directive, LogFormat. -Bugs would not surprise me.<P> - -The argument to the <A HREF="#logformat">LogFormat</A> is a string, which can -include literal characters copied into the log files, and `%' directives as -follows: - -<PRE> -%...h: Remote host -%...l: Remote logname (from identd, if supplied) -%...u: Remote user (from auth; may be bogus if return - status (%s) is 401) -%...t: Time, in common log format time format -%...r: First line of request -%...s: Status. For requests that got internally redirected, - this is status of the <b>original</b> request --- %...>s - for the last. -%...b: Bytes sent. -%...{Foobar}i: The contents of Foobar: header line(s) in the request - sent to the client. -%...{Foobar}o: The contents of Foobar: header line(s) in the reply. -</PRE> - -The `...' can be nothing at all (e.g. <code>"%h %u %r %s %b"</code>), or it can -indicate conditions for inclusion of the item (which will cause it -to be replaced with `-' if the condition is not met). Note that -there is no escaping performed on the strings from %r, %...i and -%...o; some with long memories may remember that I thought this was -a bad idea, once upon a time, and I'm still not comfortable with -it, but it is difficult to see how to `do the right thing' with all -of `%..i', unless we URL-escape everything and break with CLF. - -<P> - -The forms of condition are a list of HTTP status codes, which may -or may not be preceded by `!'. Thus, `%400,501{User-agent}i' logs -User-agent: on 400 errors and 501 errors (Bad Request, Not -Implemented) only; `%!200,304,302{Referer}i' logs Referer: on all -requests which did <b>not</b> return some sort of normal status. - -<P> - -The default LogFormat reproduces CLF; see below. - -<P> - -The way this is supposed to work with virtual hosts is as follows: -a virtual host can have its own LogFormat, or its own TransferLog. -If it doesn't have its own LogFormat, it inherits from the main -server. If it doesn't have its own TransferLog, it writes to the -same descriptor (meaning the same process for `| ...'). - -<P> - -That means that you can do things like: - -<blockquote><code> -<VirtualHost hosta.com><br> -LogFormat "hosta ..."<br> -...<br> -</VirtualHost><br> -<br> -<VirtualHost hosta.com><br> -LogFormat "hostb ..."<br> -...<br> -</VirtualHost></code></blockquote> - -... to have different virtual servers write into the same log file, -but have some indication which host they came from, though a %v -directive may well be a better way to handle this. Look for more -changes to come to this format.<p> - - -<!--%hypertext --> - -<h2>Directives</h2> - -<ul> -<li><A HREF="#logformat">LogFormat</A> -<li><A HREF="#transferlog">TransferLog</A> -</ul> -<hr> -<!--/%hypertext --> - -<A name="logformat"><h2>LogFormat</h2></A> -<!--%plaintext <?INDEX {\tt LogFormat} directive> --> -<strong>Syntax:</strong> LogFormat <em>string</em><br> -<strong>Default:</strong> <code>LogFormat "%h %l %u %t \"%r\" -%s %b"</code><br> -<Strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> Experimental<br> -<strong>Module:</strong> mod_log_config<p> - -This sets the format of the logfile.<p><hr> - - -<A name="transferlog"><h2>TransferLog</h2></A> -<!--%plaintext <?INDEX {\tt TransferLog} directive> --> -<strong>Syntax:</strong> TransferLog <em>file-pipe</em><br> -<strong>Default:</strong> <code>TransferLog logs/transfer_log</code><br> -<Strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> Experimental<br> -<strong>Module:</strong> mod_log_config<p> - -The TransferLog directive sets the name of the file to which the server will -log the incoming requests. <em>File-pipe</em> is one -of -<dl><dt>A filename -<dd>A filename relative to the <A HREF="core.html#serverroot">ServerRoot</A>. -<dt> `|' followed by a command -<dd>A program to receive the agent log information on its standard input. -Note the a new program will not be started for a VirtualHost if it inherits -the TransferLog from the main server. -</dl> -<strong>Security:</strong> if a program is used, then it will be -run under the user who started httpd. This will be root if the server -was started by root; be sure that the program is secure.<p> - -<!--%hypertext --> -<hr> -<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> -<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> - -</BODY> -</HTML> -<!--/%hypertext --> diff --git a/docs/manual/mod/mod_mime.html b/docs/manual/mod/mod_mime.html deleted file mode 100644 index c3dc14af92..0000000000 --- a/docs/manual/mod/mod_mime.html +++ /dev/null @@ -1,210 +0,0 @@ -<!--%hypertext --> -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_mime</TITLE> -</HEAD> - -<BODY> -<IMG SRC="../images/apache_sub.gif" ALT=""> -<!--/%hypertext --> -<H1>Module mod_mime</h1> - -This module is contained in the <code>mod_mime.c</code> file, and is -compiled in by default. It provides for determining the types of files -from the filename. - -<h2>Summary</h2> -This module is used to determine the mime types of documents. Some mime -types indicate special processing to be performed by the server, otherwise -the type is returned to the client so that the browser can deal with -the document appropriately.<p> - -The filename of a document is treated as being composed of a basename followed -by some extensions, in the following order: -<blockquote><em>base.type.language.enc</em></blockquote> -The <em>type</em> extension sets the type of the document; types are defined -in the <A HREF="#typesconfig">TypesConfig</A> file and by the -<A HREF="#addtype">AddType</A> directive. The <em>language</em> extension -sets the language of the document, as defined by the -<A HREF="#addlanguage">AddLanguage</A> directive. Finally, the -<em>enc</em> directive sets the encoding of the document, as defined by -the <A HREF="#addencoding">AddEncoding</A> directive. - -<!--%hypertext --> -<h2> Directives</h2> -<ul> -<li><A HREF="#addencoding">AddEncoding</A> -<li><A HREF="#addhandler">AddHandler</A> -<li><A HREF="#addlanguage">AddLanguage</A> -<li><A HREF="#addtype">AddType</A> -<li><A HREF="#forcetype">ForceType</A> -<li><A HREF="#sethandler">SetHandler</A> -<li><A HREF="#typesconfig">TypesConfig</A> -</ul> -<hr> -<!--/%hypertext --> - -<A name="addencoding"><h2>AddEncoding</h2></A> -<!--%plaintext <?INDEX {\tt AddEncoding} directive> --> -<strong>Syntax:</strong> AddEncoding <em>mime-enc extension extension...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> FileInfo<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_mime<p> - -The AddEncoding directive adds to the list of filename extensions which -filenames may end in for the specified encoding type. <em>Mime-enc</em> -is the mime encoding to use for documents ending in <em>extension</em>. -Example: -<blockquote><code> -AddEncoding x-gzip gz<br> -AddEncoding x-compress Z -</code></blockquote> - -This will cause files ending in .gz to be marked as encoded using the x-gzip -encoding, and .Z files to be marked as encoded with x-compress.<p><hr> - -<h2><a name="addhandler">AddHandler</a></h2> - -<strong>Syntax:</strong> <AddHandler <em>handler-name extention</em>><br> -<strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_mime<br> -<strong>Compatibility:</strong> AddHandler is only available in Apache -1.1 and later<p> - -<p>AddHandler maps the filename extension <em>extension</em> to the -<a href="handler.html">handler</a> -<em>handler-name</em>. For example, to activate CGI scripts -with the file extension "<code>.cgi</code>", you might use: -<pre> - AddHandler cgi-script cgi -</pre> - -<p>Once that has been put into your srm.conf or httpd.conf file, any -file ending with "<code>.cgi</code>" will be treated as a CGI -program.</p> - - -<A name="addlanguage"><h2>AddLanguage</h2></A> -<!--%plaintext <?INDEX {\tt AddLanguage} directive> --> -<strong>Syntax:</strong> AddLanguage <em>mime-lang extension extension...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> FileInfo<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_mime<p> - -The AddLanguage directive adds to the list of filename extensions which -filenames may end in for the specified content language. <em>Mime-lang</em> -is the mime language of files with names ending <em>extension</em>, -after any content encoding extensions have been removed. Example: -<blockquote><code> -AddEncoding x-compress Z<br> -AddLanguage en .en<br> -AddLanguage fr .fr<br> -</code></blockquote> - -Then the document <code>xxxx.en.Z</code> will be treated as being a compressed -English document. Although the content language is reported to the client, -the browser is unlikely to use this information. The AddLanguage directive -is more useful for content negotiation, where the server returns one -from several documents based on the client's language preference.<p><hr> - -<A name="addtype"><h2>AddType</h2></A> -<!--%plaintext <?INDEX {\tt AddType} directive> --> -<strong>Syntax:</strong> AddType <em>mime-type extension extension...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> FileInfo<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_mime<p> - -The AddType directive adds to the list of filename extensions which -filenames may end in for the specified content type. <em>Mime-enc</em> -is the mime type to use for documents ending in <em>extension</em>. -after content-encoding and language extensions have been removed. Example: -<blockquote><code> -AddType image/gif GIF -</code></blockquote> -It is recommended that new mime types be added using the AddType directive -rather than changing the <A HREF="#typesconfig">TypesConfig</A> file.<p> -Note that, unlike the NCSA httpd, this directive cannot be used to set the -type of particular files.<p><hr> - -<h2><a name="sethandler">ForceType</a></h2> - -<strong>Syntax:</strong> <ForceType <em>media type</em>><br> -<strong>Context:</strong> directory, .htaccess<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_mime<br> -<strong>Compatibility:</strong> ForceType is only available in Apache -1.1 and later.<p> - -<p>When placed into an <code>.htaccess</code> file or a -<code><Directory></code> or <code><Location</code> section, -this directive forces all matching files to be served -as the content type given by <em>media type</em>. For example, if you -had a directory full of GIF files, but did not want to label them all with -".gif", you might want to use: -<pre> - ForceType image/gif -</pre> -<p>Note that this will override any filename extensions that might -media type.</p> - -<h2><a name="sethandler">SetHandler</a></h2> - -<strong>Syntax:</strong> <SetHandler <em>handler-name</em>><br> -<strong>Context:</strong> directory, .htaccess<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_mime<br> -<strong>Compatibility:</strong> SetHandler is only available in Apache -1.1 and later.<p> - -<p>When placed into an <code>.htaccess</code> file or a -<code><Directory></code> or <code><Location</code> section, -this directive forces all matching files to be parsed through the -<a href="handler.html">handler</a> -given by <em>handler-name</em>. For example, if you had a -directory you wanted to be parsed entirely as imagemap rule files, -regardless of extension, you might put the following into an -<code>.htaccess</code> file in that directory: -<pre> - SetHandler imap-file -</pre> - -<p>Another example: if you wanted to have the server display a status -report whenever a URL of <code>http://servername/status</code> was -called, you might put the following into access.conf: -<pre> - <Location /status> - SetHandler server-status - </Location> -</pre> - - -<A name="typesconfig"><h2>TypesConfig</h2></A> -<!--%plaintext <?INDEX {\tt TypesConfig} directive> --> -<strong>Syntax:</strong> TypesConfig <em>filename</em><br> -<strong>Default:</strong> <code>TypesConfig conf/mime.types</code><br> -<Strong>Context:</strong> server config<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_mime<p> - -The TypesConfig directive sets the location of the mime types configuration -file. <em>Filename</em> is relative to the -<A HREF="#serverroot">ServerRoot</A>. This file sets the default list of -mappings from filename extensions to content types; changing this file is not -recommended. Use the <A HREF="#addtype">AddType</A> directive instead. The -file contains lines in the format of the arguments to an AddType command: -<blockquote><em>mime-type extension extension ...</em></blockquote> -The extensions are lower-cased. Blank lines, and lines beginning with a hash -character (`#') are ignored.<p> -<!--%hypertext --> -<hr> -<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> -<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> - -</BODY> -</HTML> -<!--/%hypertext --> diff --git a/docs/manual/mod/mod_mime_magic.html b/docs/manual/mod/mod_mime_magic.html deleted file mode 100644 index 56fade8486..0000000000 --- a/docs/manual/mod/mod_mime_magic.html +++ /dev/null @@ -1,251 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Apache module mod_mime_magic</TITLE> - </HEAD> - <!-- Background white, links blue (unvisited), navy (visited), red (active) --> - <BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" - > - <h1 align="CENTER">Module mod_mime_magic</h1> - - This module is an optional extension to the Apache HTTPD server. - The current version can be obtained from - <a href="http://www.employees.org/~ikluft/apache/mod_mime_magic/"> - http://www.employees.org/~ikluft/apache/mod_mime_magic/</a>. - - <h2>Summary</h2> - - This module is derived from a free version of the <code>file(1)</code> - command for Unix, - which uses "magic numbers" and other hints from a file's contents to - figure out what the contents are. - In the case of this module, - it tries to figure out the MIME type of the file. - <p> - This module is only active if the magic file exists and - was successfully opened at server-configuration time. - The magic file can be named by the - <A HREF="#mimemagicfile"><code>MimeMagicFile</code></a> - directive or defaults to conf/magic. - <p> - The contents of the file are plain ASCII text in 4-5 columns. - Blank lines are allowed but ignored. - Commented lines use a hash mark "#". - The remaining lines are parsed for the following columns: - <table border=1> - <tr valign=top> - <th>Column</th> - <th>Description</th> - </tr> - <tr valign=top> - <td>1</td> - <td>byte number to begin checking from - <br> - ">" indicates a dependency upon the previous non-">" line</td> - </tr><tr valign=top> - <td>2</td> - <td>type of data to match - <table border=1> - <tr><td>byte</td><td>single character</td></tr> - <tr><td>short</td><td>machine-order 16-bit integer</td></tr> - <tr><td>long</td><td>machine-order 32-bit integer</td></tr> - <tr><td>string</td><td>arbitrary-length string</td></tr> - <tr><td>date</td><td>long integer date - (seconds since Unix epoch/1970)</td></tr> - <tr><td>beshort</td><td>big-endian 16-bit integer</td></tr> - <tr><td>belong</td><td>big-endian 32-bit integer</td></tr> - <tr><td>bedate</td><td>big-endian 32-bit integer date</td></tr> - <tr><td>leshort</td><td>little-endian 16-bit integer</td></tr> - <tr><td>lelong</td><td>little-endian 32-bit integer</td></tr> - <tr><td>ledate</td><td>little-endian 32-bit integer date</td></tr> - </table> - </td> - </tr><tr valign=top> - <td>3</td> - <td>contents of data to match</td> - </tr><tr valign=top> - <td>4</td> - <td>MIME type if matched</td> - </tr><tr valign=top> - <td>5</td> - <td>MIME encoding if matched (optional)</td> - </tr> - </table> - - <p> - For example, the following magic file lines - would recognize some audio formats. - -<pre> -# Sun/NeXT audio data -0 string .snd ->12 belong 1 audio/basic ->12 belong 2 audio/basic ->12 belong 3 audio/basic ->12 belong 4 audio/basic ->12 belong 5 audio/basic ->12 belong 6 audio/basic ->12 belong 7 audio/basic ->12 belong 23 audio/x-adpcm -</pre> - - Or these would recognize the difference between "*.doc" files containing - Microsoft Word or FrameMaker documents. (These are incompatible file - formats which use the same file suffix.) - -<pre> -# Frame -0 string \<MakerFile application/x-frame -0 string \<MIFFile application/x-frame -0 string \<MakerDictionary application/x-frame -0 string \<MakerScreenFon application/x-frame -0 string \<MML application/x-frame -0 string \<Book application/x-frame -0 string \<Maker application/x-frame - -# MS-Word -0 string \376\067\0\043 application/msword -0 string \320\317\021\340\241\261 application/msword -0 string \333\245-\0\0\0 application/msword -</pre> - - An optional MIME encoding can be included as a fifth column. - For example, this can recognize gzipped files and set the encoding - for them. - -<pre> -# gzip (GNU zip, not to be confused with [Info-ZIP/PKWARE] zip archiver) -0 string \037\213 application/octet-stream x-gzip -</pre> - - <h3>Performance Issues</h3> - - This module is not for every system. If your system is barely keeping - up with its load or if you're performing a web server benchmark, - you may not want to enable this because the processing is not free. - <p> - However, an effort was made to improve the performance of the original - file(1) code to make it fit in a busy web server. - It was designed for a server where there are thousands of users who - publish their own documents. - This is probably very common on intranets. - Many times, it's helpful - if the server can make more intelligent decisions about a file's - contents than the file name allows - ...even if just to reduce the "why doesn't my page work" calls - when users improperly name their own files. - You have to decide if the extra work suits your environment. - <p> - When compiling an Apache server, this module should be at or near the - top of the list of modules in the Configuration file. The modules are - listed in increasing priority so that will mean this one is used only - as a last resort, just like it was designed to. - - <h2>Directives</h2> - <p> - <UL> - <LI><A HREF="#mimemagicfile">MimeMagicFile</A> - </LI> - </UL> - </P> - <HR> - <H2><A NAME="mimemagicfile"> - MimeMagicFile - </A></H2> - <P> - <STRONG>Syntax:</STRONG> MimeMagicFile <em>magic-file-name</em> - <BR> - <STRONG>Default:</STRONG> conf/magic - <BR> - <STRONG>Context:</STRONG> server config, virtual host - <BR> - <STRONG>Status:</STRONG> Extension - <BR> - <STRONG>Module:</STRONG> mod_mime_magic - <p> - - The MimeMagicFile directive can be used to change the location of the - magic file from its default location at <code>conf/magic</code>. - Non-rooted paths are relative to the ServerRoot. - <p> - <HR> - - <h2><a name="notes">Notes</a></h2> - - Patches and suggestions for mod_mime_magic should be sent to - Ian Kluft <ikluft<!--- comment inserted to discourage spam --->@cisco.com>. - Note that enhancements are done on a volunteer basis so no timetable can - be committed for any particular request. - Obviously, patches are given much higher priority over plain requests. - <p> - The following notes apply to the mod_mime_magic module and are - included here for compliance with contributors' copyright restrictions - that require their acknowledgement. - -<pre> -/* - * mod_mime_magic: MIME type lookup via file magic numbers - * Copyright (c) 1996-1997 Cisco Systems, Inc. - * - * This software was submitted by Cisco Systems to the Apache Group in July - * 1997. Future revisions and derivatives of this source code must - * acknowledge Cisco Systems as the original contributor of this module. - * All other licensing and usage conditions are those of the Apache Group. - * - * Some of this code is derived from the free version of the file command - * originally posted to comp.sources.unix. Copyright info for that program - * is included below as required. - * --------------------------------------------------------------------------- - * - Copyright (c) Ian F. Darwin, 1987. Written by Ian F. Darwin. - * - * This software is not subject to any license of the American Telephone and - * Telegraph Company or of the Regents of the University of California. - * - * Permission is granted to anyone to use this software for any purpose on any - * computer system, and to alter it and redistribute it freely, subject to - * the following restrictions: - * - * 1. The author is not responsible for the consequences of use of this - * software, no matter how awful, even if they arise from flaws in it. - * - * 2. The origin of this software must not be misrepresented, either by - * explicit claim or by omission. Since few users ever read sources, credits - * must appear in the documentation. - * - * 3. Altered versions must be plainly marked as such, and must not be - * misrepresented as being the original software. Since few users ever read - * sources, credits must appear in the documentation. - * - * 4. This notice may not be removed or altered. - * ------------------------------------------------------------------------- - * - * For complicance with Mr Darwin's terms: this has been very significantly - * modified from the free "file" command. - * - all-in-one file for compilation convenience when moving from one - * version of Apache to the next. - * - Memory allocation is done through the Apache API's pool structure. - * - All functions have had necessary Apache API request or server - * structures passed to them where necessary to call other Apache API - * routines. (i.e. usually for logging, files, or memory allocation in - * itself or a called function.) - * - struct magic has been converted from an array to a single-ended linked - * list because it only grows one record at a time, it's only accessed - * sequentially, and the Apache API has no equivalent of realloc(). - * - Functions have been changed to get their parameters from the server - * configuration instead of globals. (It should be reentrant now but has - * not been tested in a threaded environment.) - * - Places where it used to print results to stdout now saves them in a - * list where they're used to set the MIME type in the Apache request - * record. - * - Command-line flags have been removed since they will never be used here. - * - */ -</pre> - - </BODY> -</HTML> diff --git a/docs/manual/mod/mod_negotiation.html b/docs/manual/mod/mod_negotiation.html deleted file mode 100644 index 6b8ac6e7d5..0000000000 --- a/docs/manual/mod/mod_negotiation.html +++ /dev/null @@ -1,134 +0,0 @@ -<!--%hypertext --> -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_negotiation</TITLE> -</HEAD> - -<BODY> -<IMG SRC="../images/apache_sub.gif" ALT=""> -<!--/%hypertext --> -<H1>Module mod_negotiation</h1> - -This module is contained in the <code>mod_negotiation.c</code> file, and -is compiled in by default. It provides for -<A HREF="content-negotiation.html">content negotiation</A>. Any document with -mime type <code>application/x-type-map</code> will be processed by this module. -<!--%plaintext <?INDEX {\tt application/x-type-map} mime type> --> - -<h2>Summary</h2> -Content negotiation, or more accurately content selection, is the -selection of the document that best matches the clients -capabilities, from one of several available documents. -There are two implementations of this. -<ul> -<li> A type map (a file with the mime type <code>application/x-type-map</code>) -which explicitly lists the files containing the variants. -<li> A MultiViews search (enabled by the MultiViews -<A HREF="core.html#options">Option</A>, where the server does an implicit -filename pattern match, and choose from amongst the results. -</ul> - -<h3>Type maps</h3> -A type map has the same format as RFC822 mail headers. It contains document -descriptions separated by blank lines, with lines beginning with a hash -character ('#') treated as comments. A document description consists of -several header records; records may be continued on multiple lines if the -continuation lines start with spaces. The leading space will be deleted -and the lines concatenated. A header record consists of a keyword -name, which always ends in a colon, followed by a value. Whitespace is allowed -between the header name and value, and between the tokens of value. - -The headers -allowed are: - -<dl> -<dt>Content-Encoding: -<dd>The encoding of the file. Currently only two encodings are recognised -by http; <code>x-compress</code> for compressed files, and <code>x-gzip</code> -for gzipped files. -<dt>Content-Language: -<dd>The language of the variant, as an Internet standard language code, such -as <code>en</code>. -<dt>Content-Length: -<dd>The length of the file, in bytes. If this header is not present, then -the actual length of the file is used. -<dt>Content-Type: -<dd>The MIME media type of the document, with optional parameters. -parameters are separated from the media type and from one another by -semi-colons. Parameter syntax is name=value; allowed parameters are: -<dl> -<dt>level -<dd>the value is an integer, which specifies the version of the media type. -For <code>text/html</code> this defaults to 2, otherwise 0. -<dt>qs -<dd>the value is a floating-point number with value between 0. and 1. -It indications the 'quality' of this variant. -</dl> -Example: -<blockquote><code>Content-Type: image/jpeg; qs=0.8</code></blockquote> -<dt>URI: -<dd>The path to the file containing this variant, relative to the map file. -</dl> - -<h3>MultiViews</h3> -A MultiViews search is enabled by the MultiViews -<A HREF="core.html#options">Option</A>. -If the server receives a request for <code>/some/dir/foo</code> and -<code>/some/dir/foo</code> does <em>not</em> exist, then the server reads the -directory looking for all files named <code>foo.*</code>, 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, and returns that document.<p> - - -<!--%hypertext --> -<h2>Directives</h2> -<ul> -<li><A href="#cachenegotiateddocs">CacheNegotiatedDocs</a> -<li><A HREF="#languagepriority">LanguagePriority</A> -</ul> -<hr> -<!--/%hypertext --> - -<A name="cachenegotiateddocs"><h2>CacheNegotiatedDocs</h2></A> -<strong>Syntax:</strong> CacheNegotiatedDocs<br> -<Strong>Context:</strong> server config<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_negotiation<br> -<strong>Compatibility:</strong> CacheNegotiatedDocs is only available -in Apache 1.1 and later.<p> - -<p>If set, this directive allows content-negotiated documents to be cached -by -proxy servers. This could mean that clients behind those proxys could -retrieve versions of the documents that are not the best match for -their abilities, but it will make caching more efficient.</p> - -<!--%hypertext --> -<A name="languagepriority"><h2>LanguagePriority</h2></A> -<!--%plaintext <?INDEX {\tt LanguagePriority} directive> --> -<strong>Syntax:</strong> LanguagePriority <em>mime-lang mime-lang...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> FileInfo<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_negotiation<p> - -The LanguagePriority sets the precedence of language variants for the case -where the client does not express a preference, when handling a -MultiViews request. The list of <em>mime-lang</em> are in order of decreasing -preference. Example: -<blockquote><code>LanguagePriority en fr de</code></blockquote> -For a request for <code>foo.html</code>, where <code>foo.html.fr</code> -and <code>foo.html.de</code> both existed, but the browser did not express -a language preference, then <code>foo.html.fr</code> would be returned.<p> -<!--%hypertext --> -<hr> - -<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> -<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> - -</BODY> -</HTML> -<!--/%hypertext --> diff --git a/docs/manual/mod/mod_proxy.html b/docs/manual/mod/mod_proxy.html deleted file mode 100644 index b64dcd9c6d..0000000000 --- a/docs/manual/mod/mod_proxy.html +++ /dev/null @@ -1,212 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_proxy</TITLE> -</HEAD> - -<BODY> -<IMG SRC="../images/apache_sub.gif" ALT=""> -<H1>Apache module mod_proxy</h1> - -This module is contained in the <code>mod_proxy.c</code> file, and -is not compiled in by default. It provides for a caching proxy server. -It is only available in Apache 1.1 and later. - -<h3>Note:</h3> -<p>This module is experimental. Use at your own risk.</p> - -<h2>Summary</h2> - -This module implements a proxy/cache for Apache. It implements -proxying capability for -<code>FTP</code>, -<code>HTTP/0.9</code>, and -<code>HTTP/1.0</code>. -The module can be configured to connect to other proxy modules for these -and other protocols. - -<h2>Directives</h2> -<ul> -<li><a href="#proxyrequests">ProxyRequests</a> -<li><a href="#proxyremote">ProxyRemote</a> -<li><a href="#proxypass">ProxyPass</a> -<li><a href="#cacheroot">CacheRoot</a> -<li><a href="#cachesize">CacheSize</a> -<li><a href="#cachegcinterval">CacheGcInterval</a> -<li><a href="#cachemaxexpire">CacheMaxExpire</a> -<li><a href="#cachelastmodifiedfactor">CacheLastModifiedFactor</a> -<li><a href="#cachedefaultexpire">CacheDefaultExpire</a> -<li><a href="#nocache">NoCache</a> -</ul> - -<hr> - -<A name="proxyrequests"><h2>ProxyRequests</h2></A> -<strong>Syntax:</strong> ProxyRequests <em>on/off</em><br> -<strong>Default:</strong> <code>ProxyRequests Off</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_proxy<br> -<strong>Compatibility:</strong> ProxyRequest is only available in -Apache 1.1 and later.<p> - -This allows or prevents Apache from functioning as a proxy -server. Setting ProxyRequests to 'off' does not disable use of the <a -href="#proxypass">ProxyPass</a> directive. - -<A name="proxyremote"><h2>ProxyRemote</h2></A> -<strong>Syntax:</strong> ProxyRemote <em><match> <remote-server></em><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_proxy<br> -<strong>Compatibility:</strong> ProxyRemote is only available in -Apache 1.1 and later.<p> - -This defines remote proxies to this proxy. <match> is either the -name of a URL-scheme that the remote server supports, or a partial URL -for which the remote server should be used, or '$' to indicate the -server should be contacted for all requests. <remote-server> is a -partial URL for the remote server. Syntax: - -<pre> - <remote-server> = <protocol>://<hostname>[:port] -</pre> -<protocol> is the protocol that should be used to communicate with the -remote -server; only "http" is supported by this module. - -Example: -<pre> - ProxyRemote ftp http://ftpproxy.mydomain.com:8080 - ProxyRemote http://goodguys.com/ http://mirrorguys.com:8000 - ProxyRemote * http://cleversite.com -</pre> - -<A name="proxypass"><h2>ProxyPass</h2></A> -<strong>Syntax:</strong> ProxyPass <em><path> <url></em><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_proxy<br> -<strong>Compatibility:</strong> ProxyPass is only available in -Apache 1.1 and later.<p> - -This directive allows remote servers to be mapped into the space of the local -server; the local server does not act as a proxy in the conventional sense, -but appears to be a mirror of the remote server. <path> is the name of -a local virtual path; <url> is a partial URL for the remote server. - -Suppose the local server has address http://wibble.org; then -<pre> - ProxyPass /mirror/foo http://foo.com -</pre> -Will cause a local request for the http://wibble.org/mirror/foo/bar to be -internally converted into a proxy request to http://foo.com/bar - -<A name="cacheroot"><h2>CacheRoot</h2></A> -<strong>Syntax:</strong> CacheRoot <em><directory></em><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_proxy<br> -<strong>Compatibility:</strong> CacheRoot is only available in -Apache 1.1 and later.<p> - -Sets the name of the directory to contain cache files; this must be -writable -by the httpd server. - -<A name="cachesize"><h2>CacheSize</h2></A> -<strong>Syntax:</strong> CacheSize <em><size></em><br> -<strong>Default:</strong> <code>CacheSize 5</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_proxy<br> -<strong>Compatibility:</strong> CacheSize is only available in -Apache 1.1 and later.<p> - -Sets the desired space usage of the cache, in Kb (1024 byte units). Although -usage may grow above this setting, the garbage collection will delete files -until the usage is at or below this setting. - -<A name="cachegcinterval"><h2>CacheGcInterval</h2></A> -<strong>Syntax:</strong> CacheGcInterval <em><time></em><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_proxy<br> -<strong>Compatibility:</strong> CacheGcinterval is only available in -Apache 1.1 and later.<p> - -Check the cache every <time> hours, and delete files if the space -usage is greater than that set by CacheSize. - -<A name="cachemaxexpire"><h2>CacheMaxExpire</h2></A> -<strong>Syntax:</strong> CacheMaxExpire <em><time></em><br> -<strong>Default:</strong> </code>CacheMaxExpire 24</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_proxy<br> -<strong>Compatibility:</strong> CacheMaxExpire is only available in -Apache 1.1 and later.<p> - -Cachable HTTP documents will be retained for at most <time> hours without -checking the origin server. Thus documents can be at most <time> -hours out of date. This restriction is enforced even if an expiry date -was supplied with the document. - -<A name="cachelastmodifiedfactor"><h2>CacheLastModifiedFactor</h2></A> -<strong>Syntax:</strong> CacheLastModifiedFactor <em><factor></em><br> -<strong>Default:</strong> </code>CacheLastModifiedFactor 0.1</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_proxy<br> -<strong>Compatibility:</strong> CacheLastModified is only available in -Apache 1.1 and later.<p> - -If the origin HTTP server did not supply an expiry date for the -document, then estimate on using the formula -<pre> - expiry-period = time-since-last-modification * <factor> -</pre> -For example, if the document was last modified 10 hours ago, and -<factor> is 0.1, then the expiry period wil be set to 10*0.1 = 1 hour. - -<p>If the expiry-period would be longer than that set by CacheMaxExpire, -then the latter takes precedence. - -<A name="cachedefaultexpire"><h2>CacheDefaultExpire</h2></A> -<strong>Syntax:</strong> CacheDefaultExpire <em><time></em><br> -<strong>Default:</strong> </code>CacheDefaultExpire 1</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_proxy<br> -<strong>Compatibility:</strong> CacheDefaultExpire is only available in -Apache 1.1 and later.<p> - -If the document is fetched via a protocol that does not support expirytimes, -then use <time> as the expiry time. -<a href="#cachemaxexpire">CacheMaxExpire</a> does <strong>not</strong> -override. - -<A name="nocache"><h2>NoCache</h2></A> -<strong>Syntax:</strong> NoCache <em><host/domain list></em><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_proxy<br> -<strong>Compatibility:</strong> NoCache is only available in -Apache 1.1 and later.<p> - -The NoCache directive specifies a list of hosts and/or domains, separated -by spaces. HTTP documents from hosts or domains in the list are <em>not</em> -cached by the proxy server. Example: - -<pre> - NoCache joes.garage.com some.host.co.uk wotsamattau.edu -</pre> - -<p><hr> - -<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> -<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> - -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_rewrite.html b/docs/manual/mod/mod_rewrite.html deleted file mode 100644 index b7c4e633a0..0000000000 --- a/docs/manual/mod/mod_rewrite.html +++ /dev/null @@ -1,1083 +0,0 @@ -<!--%hypertext --> -<!-- mod_rewrite.html --> -<!-- Documentation for the mod_rewrite Apache module --> -<html> -<head> -<title>Apache module mod_rewrite</title> -</head> - -<body> -<!--#include virtual="header.html" --> -<h1>Module mod_rewrite (Version 2.3)</h1> - -This module is contained in the <code>mod_rewrite.c</code> file, with -Apache 1.2 and later. It provides -a rule-based rewriting engine to rewrite requested URLs on the fly. -<code>mod_rewrite</code> is not compiled into the server by -default. To use <code>mod_rewrite</code> you have to enable the following -line in the server build Configuration file: -<pre> - Module rewrite_module mod_rewrite.o -</pre> - -<h2>Summary</h2> - -This module uses a rule-based rewriting engine (based on a -regular-expression parser) to rewrite requested URLs on the fly. - -<p> -It supports an unlimited number of additional rule conditions (which can -operate on a lot of variables, including HTTP headers) for granular -matching and external database lookups (either via plain text -tables, DBM hash files or external processes) for advanced URL -substitution. - -<p> -It operates on the full URLs (including the PATH_INFO part) both in -per-server context (httpd.conf) and per-dir context (.htaccess) and even -can generate QUERY_STRING parts on result. The rewrittten result can lead to internal sub-processing, external request redirection or to internal proxy throughput. -</b> - -<p> -The latest version can be found on<br> -<a href="http://www.engelschall.com/sw/mod_rewrite/"> -<code><b>http://www.engelschall.com/sw/mod_rewrite/</b></code></a> - -<p> -Copyright © 1996 <b>The Apache Group</b>, All rights reserved.<br> -Copyright © 1996 <i>Ralf S. Engelschall</i>, All rights reserved. -<p> -Written for <b>The Apache Group</b> by -<blockquote> - <i>Ralf S. Engelschall</i><br> - <a href="mailto:rse@engelschall.com"><tt>rse@engelschall.com</tt></a><br> - <a href="http://www.engelschall.com/~rse"><tt>http://www.engelschall.com/~rse</i></a> -</blockquote> - -<!--%hypertext --> -<HR> -<!--/%hypertext --> - -<p> -<h2>Directives</h2> - -<ul> - <li><a href="#RewriteEngine">RewriteEngine</a> - <li><a href="#RewriteOptions">RewriteOptions</a> - <li><a href="#RewriteLog">RewriteLog</a> - <li><a href="#RewriteLogLevel">RewriteLogLevel</a> - <li><a href="#RewriteMap">RewriteMap</a> - <li><a href="#RewriteBase">RewriteBase</a> - <li><a href="#RewriteCond">RewriteCond</a> - <li><a href="#RewriteRule">RewriteRule</a> -</ul> - -<!--%hypertext --> -<hr> -<!--/%hypertext --> - - -<center> -<a name="Configuration"> -<h1>Configuration Directives</h1> -</a> -</center> - -<a name="RewriteEngine"><h3>RewriteEngine</h3></a> -<strong>Syntax:</strong> <code>RewriteEngine</code> {<code>on,off</code>}<br> -<strong>Default:</strong> <strong><code>RewriteEngine off</code></strong><br> -<strong>Context:</strong> server config, virtual host, per-directory config<br> -<p> - -The <tt>RewriteEngine</tt> directive enables or disables the -runtime rewriting engine. If it is set to <code>off</code> this module does -no runtime processing at all. It does not even update the <tt>SCRIPT_URx</tt> -environment variables. - -<p> -Use this directive to disable the module instead of commenting out -all <tt>RewriteRule</tt> directives! - -<p> -<hr noshade size=1> -<p> - -<a name="RewriteOptions"><h3>RewriteOptions</h3></a> -<strong>Syntax:</strong> <code>RewriteOptions</code> <em>Option</em> ...<br> -<strong>Default:</strong> -<em>None</em>-<br> -<strong>Context:</strong> server config, virtual host, per-directory config<br> -<p> - -The <tt>RewriteOption</tt> directive sets some special options for the -current per-server or per-directory configuration. The <em>Option</em> -strings can be one of the following: - -<ul> -<li>'<strong><code>inherit</code></strong>'<br> - This forces the current configuration to inherit the configuration of the - parent. In per-virtual-server context this means that the maps, - conditions and rules of the main server gets inherited. In per-directory - context this means that conditions and rules of the parent directory's - <tt>.htaccess</tt> configuration gets inherited. -<p> -</ul> - -<p> -<hr noshade size=1> -<p> - -<a name="RewriteLog"><h3>RewriteLog</h3></a> -<strong>Syntax:</strong> <code>RewriteLog</code> <em>Filename</em><br> -<strong>Default:</strong> -<em>None</em>-<br> -<strong>Context:</strong> server config, virtual host<br> -<p> - -The <tt>RewriteLog</tt> directive sets the name of the file to which the -server logs any rewriting actions it performs. If the name does not begin -with a slash ('<tt>/</tt>') then it is assumed to be relative to the -<em>Server Root</em>. The directive should occur only once per server -config. - -<p> -<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> -<tr><td> -To disable the logging of rewriting actions it is not recommended -to set <em>Filename</em> -to <code>/dev/null</code>, because although the rewriting engine does -not create output to a logfile it still creates the logfile -output internally. <b>This will slow down the server with no advantage to the -administrator!</b> -To disable logging either remove or comment out the -<tt>RewriteLog</tt> directive or use <tt>RewriteLogLevel 0</tt>! -</td></tr> -</table> - -<p> -<b>Example:</b> -<blockquote> -<pre> -RewriteLog "/usr/local/var/apache/logs/rewrite.log" -</pre> -</blockquote> - -<p> -<hr noshade size=1> -<p> - -<a name="RewriteLogLevel"><h3>RewriteLogLevel</h3></a> -<strong>Syntax:</strong> <code>RewriteLogLevel</code> <em>Level</em><br> -<strong>Default:</strong> <strong><code>RewriteLogLevel 0</code></strong><br> -<strong>Context:</strong> server config, virtual host<br> -<p> - -The <tt>RewriteLogLevel</tt> directive set the verbosity level of the rewriting -logfile. The default level 0 means no logging, while 9 or more means -that practically all actions are logged. - -<p> -To disable the logging of rewriting actions simply set <em>Level</em> to 0. -This disables all rewrite action logs. - -<p> -<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> -<tr><td> -<b>Notice:</b> Using a high value for <i>Level</i> will slow down your Apache -server dramatically! Use the rewriting logfile only for debugging or at least -at <em>Level</em> not greater than 2! -</td></tr> -</table> - - -<p> -<b>Example:</b> -<blockquote> -<pre> -RewriteLogLevel 3 -</pre> -</blockquote> - -<p> -<hr noshade size=1> -<p> - -<a name="RewriteMap"><h3>RewriteMap</h3></a> -<strong>Syntax:</strong> <code>RewriteMap</code> <em>Mapname</em> <code>{txt,dbm,prg}:</code><em>Filename</em><br> -<strong>Default:</strong> not used per default<br> -<strong>Context:</strong> server config, virtual host<br> -<p> - -The <tt>RewriteMap</tt> directive defines an external <em>Rewriting Map</em> -which can be used inside rule substitution strings by the mapping-functions -to insert/substitute fields through a key lookup. -<p> - -The <a name="mapfunc"><em>Mapname</em></a> is the name of the map and will -be used to specify a mapping-function for the substitution strings of a -rewriting rule via - -<blockquote><strong> -<code>${</code> <em>Mapname</em> <code>:</code> <em>LookupKey</em> -<code>|</code> <em>DefaultValue</em> <code>}</code> -</strong></blockquote> - -When such a directive occurs the map <em>Mapname</em> -is consulted and the key <em>LookupKey</em> is looked-up. If the key is -found, the map-function directive is substituted by <em>SubstValue</em>. If -the key is not found then it is substituted by <em>DefaultValue</em>. - -<p> -The <em>Filename</em> must be a valid Unix filepath, containing one -of the following formats: - -<ol> -<li><b>Plain Text Format</b> - <p> - This is a ASCII file which contains either blank lines, comment lines - (starting with a '#' character) or - - <blockquote><strong> - <em>MatchingKey</em> <em>SubstValue</em> - </strong></blockquote> - - pairs - one per line. You can create such files either manually, - using your favorite editor, or by using the programs - <tt>mapcollect</tt> and <tt>mapmerge</tt> from the <tt>support</tt> - directory of the <b>mod_rewrite</b> distribution. - <p> - To declare such a map prefix, <em>Filename</em> with a <code>txt:</code> - string as in the following example: - -<p> -<table border=2 cellspacing=1 cellpadding=5 bgcolor="#d0d0d0"> -<tr><td><pre> -# -# map.real-to-user -- maps realnames to usernames -# - -Ralf.S.Engelschall rse # Bastard Operator From Hell -Dr.Fred.Klabuster fred # Mr. DAU -</pre></td></tr> -</table> - -<p> -<table border=2 cellspacing=1 cellpadding=5 bgcolor="#d0d0d0"> -<tr><td><pre> -RewriteMap real-to-host txt:/path/to/file/map.real-to-user -</pre></td></tr> -</table> - -<p> -<li><b>DBM Hashfile Format</b> - <p> - This is a binary NDBM format file containing the - same contents as the <em>Plain Text Format</b> files. You can create - such a file with any NDBM tool or with the <tt>dbmmanage</tt> program - from the <tt>support</tt> directory of the Apache distribution. - <p> - To declare such a map prefix <em>Filename</em> with a <code>dbm:</code> - string. -<p> -<li><b>Program Format</b> - <p> - This is a Unix executable, not a lookup file. To create it you can use - the language of your choice, but the result has to be a runable Unix - binary (i.e. either object-code or a script with the - magic cookie trick '<tt>#!/path/to/interpreter</tt>' as the first line). - <p> - This program gets started once at startup of the Apache servers and then - communicates with the rewriting engine over its <tt>stdin</tt> and - <tt>stdout</tt> filehandles. For each map-function lookup it will - receive the key to lookup as a newline-terminated string on - <tt>stdin</tt>. It then has to give back the looked-up value as a - newline-terminated string on <tt>stdout</tt> or the four-character string - ``<tt>NULL</tt>'' if it fails (i.e. there is no corresponding value - for the given key). A trivial program which will implement a 1:1 map - (i.e. key == value) could be: - <p> -<table border=2 cellspacing=1 cellpadding=5 bgcolor="#d0d0d0"> -<tr><td><pre> -#!/usr/bin/perl -$| = 1; -while (<STDIN>) { - # ...here any transformations - # or lookups should occur... - print $_; -} -</pre></td></tr> -</table> - <p> - <b>But be very careful:</b><br> - <ol> - <li>``<i>Keep the program simple, stupid</i>'' (KISS), because - if this program hangs it will lead to a hang of the Apache server - when the rule occurs. - <li>Avoid one common mistake: never do buffered I/O on <tt>stdout</tt>! - This will cause a deadloop! Hence the ``<tt>$|=1</tt>'' in the above - example... - </ol> - <p> - To declare such a map prefix <em>Filename</em> with a <code>prg:</code> - string. -</ol> - -The <tt>RewriteMap</tt> directive can occur more than once. For each -mapping-function use one <tt>RewriteMap</tt> directive to declare its -rewriting mapfile. While you cannot <b>declare</b> a map in per-directory -context it is of course possible to <b>use</b> this map in per-directory -context. - -<p> -<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> -<tr><td> -For plain text and DBM format files the looked-up keys are cached in-core -until the <tt>mtime</tt> of the mapfile changes or the server does a -restart. This way you can have map-functions in rules which are used -for <b>every</b> request. This is no problem, because the external lookup -only happens once! -</td></tr> -</table> - - -<p> -<hr noshade size=1> -<p> - -<a name="RewriteBase"><h3>RewriteBase</h3></a> -<strong>Syntax:</strong> <code>RewriteBase</code> <em>BaseURL</em><br> -<strong>Default:</strong> <em>default is the physical directory path</em><br> -<strong>Context:</strong> per-directory config<br> -<p> - -The <tt>RewriteBase</tt> directive explicitly sets the base URL for -per-directory rewrites. As you will see below, <tt>RewriteRule</tt> can be -used in per-directory config files (<tt>.htaccess</tt>). There it will act -locally, i.e. the local directory prefix is stripped at this stage of -processing and your rewriting rules act only on the remainder. At the end -it is automatically added. - -<p> -When a substitution occurs for a new URL, this module has to -re-inject the URL into the server processing. To be able to do this it needs -to know what the corresponding URL-prefix or URL-base is. By default this -prefix is the corresponding filepath itself. <b>But at most websites URLs are -<b>NOT</b> directly related to physical filename paths, so this assumption -will be usually be wrong!</b> There you have to use the <tt>RewriteBase</tt> -directive to specify the correct URL-prefix. - -<p> -<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> -<tr><td> -So, if your webserver's URLs are <b>not</b> directly -related to physical file paths, you have to use <tt>RewriteBase</tt> in every -<tt>.htaccess</tt> files where you want to use <tt>RewriteRule</tt> -directives. -</td></tr> -</table> - -<p> -<b>Example:</b> - -<blockquote> - Assume the following per-directory config file: - -<p> -<table border=2 cellspacing=1 cellpadding=5 bgcolor="#d0d0d0"> -<tr><td><pre> -# -# /abc/def/.htaccess -- per-dir config file for directory /abc/def -# Remember: /abc/def is the physical path of /xyz, i.e. the server -# has a 'Alias /xyz /abc/def' directive e.g. -# - -RewriteEngine On - -# let the server know that we are reached via /xyz and not -# via the physical path prefix /abc/def -RewriteBase /xyz - -# now the rewriting rules -RewriteRule ^oldstuff\.html$ newstuff.html -</pre></td></tr> -</table> - -<p> -In the above example, a request to <tt>/xyz/oldstuff.html</tt> gets correctly -rewritten to the physical file <tt>/abc/def/newstuff.html</tt>. - -<p> -<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> -<tr><td> -<font size=-1> -<b>For the Apache hackers:</b><br> -The following list gives detailed information about the internal -processing steps: - -<p> -<pre> -Request: - /xyz/oldstuff.html - -Internal Processing: - /xyz/oldstuff.html -> /abc/def/oldstuff.html (per-server Alias) - /abc/def/oldstuff.html -> /abc/def/newstuff.html (per-dir RewriteRule) - /abc/def/newstuff.html -> /xyz/newstuff.html (per-dir RewriteBase) - /xyz/newstuff.html -> /abc/def/newstuff.html (per-server Alias) - -Result: - /abc/def/newstuff.html -</pre> - -This seems very complicated but is the correct Apache internal processing, -because the per-directory rewriting comes too late in the process. So, -when it occurs the (rewritten) request has to be re-injected into the Apache -kernel! BUT: While this seems like a serious overhead, it really isn't, because -this re-injection happens fully internal to the Apache server and the same -procedure is used by many other operations inside Apache. So, you can be -sure the design and implementation is correct. -</font> -</td></tr> -</table> - -</blockquote> - - -<p> -<hr noshade size=1> -<p> - -<a name="RewriteCond"><h3>RewriteCond</h3></a> -<strong>Syntax:</strong> <code>RewriteCond</code> <em>TestString</em> <em>CondPattern</em><br> -<strong>Default:</strong> -<em>None</em>-<br> -<strong>Context:</strong> server config, virtual host, per-directory config<br> -<p> - -The <tt>RewriteCond</tt> directive defines a rule condition. Precede a -<tt>RewriteRule</tt> directive with one ore more <t>RewriteCond</tt> -directives. - -The following rewriting rule is only used if its pattern matches the current -state of the URI <b>AND</b> if these additional conditions apply, too. - -<p> -<em>TestString</em> is a string which contains server-variables of the form - -<blockquote><strong> -<tt>%{</tt> <em>NAME_OF_VARIABLE</em> <tt>}</tt> -</strong></blockquote> - -where <em>NAME_OF_VARIABLE</em> can be a string -of the following list: - -<p> -<table bgcolor="#d0d0d0" cellspacing=0 cellpadding=5> -<tr> -<td valign=top> -<b>HTTP headers:</b><p> -<font size=-1> -HTTP_USER_AGENT<br> -HTTP_REFERER<br> -HTTP_COOKIE<br> -HTTP_FORWARDED<br> -HTTP_HOST<br> -HTTP_PROXY_CONNECTION<br> -HTTP_ACCEPT<br> -</font> -</td> - -<td valign=top> -<b>connection & request:</b><p> -<font size=-1> -REMOTE_ADDR<br> -REMOTE_HOST<br> -REMOTE_USER<br> -REMOTE_IDENT<br> -REQUEST_METHOD<br> -SCRIPT_FILENAME<br> -PATH_INFO<br> -QUERY_STRING<br> -AUTH_TYPE<br> -</font> -</td> - -</tr> -<tr> - -<td valign=top> -<b>server internals:</b><p> -<font size=-1> -DOCUMENT_ROOT<br> -SERVER_ADMIN<br> -SERVER_NAME<br> -SERVER_PORT<br> -SERVER_PROTOCOL<br> -SERVER_SOFTWARE<br> -SERVER_VERSION<br> -</font> -</td> - -<td valign=top> -<b>system stuff:</b><p> -<font size=-1> -TIME_YEAR<br> -TIME_MON<br> -TIME_DAY<br> -TIME_HOUR<br> -TIME_MIN<br> -TIME_SEC<br> -TIME_WDAY<br> -</font> -</td> - -<td valign=top> -<b>specials:</b><p> -<font size=-1> -API_VERSION<br> -THE_REQUEST<br> -REQUEST_URI<br> -REQUEST_FILENAME<br> -</font> -</td> -</tr> -</table> - -<p> -<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> -<tr><td> -These variables all correspond to the similar named HTTP MIME-headers, C -variables of the Apache server or <tt>struct tm</tt> fields of the Unix -system. -</td></tr> -</table> - -<p> -Special Notes: -<ol> -<li>The variables SCRIPT_FILENAME and REQUEST_FILENAME contain the same -value, i.e. the value of the <tt>filename</tt> field of the internal -<tt>request_rec</tt> structure of the Apache server. The first name is just the -commonly known CGI variable name while the second is the consistent -counterpart to REQUEST_URI (which contains the value of the <tt>uri</tt> -field of <tt>request_rec</tt>). - -<p> -<li>There is an additional format: <tt>%{ENV:variable}</tt> where -<i>variable</i> can be any Unix environment variable. This is looked-up -via <tt>getenv()</tt> from the Apache server process. - -<p> -<li>There is one more additional format: <tt>%{HTTP:header}</tt> where -<i>header</i> can be any HTTP MIME-header name. This is looked-up -from the HTTP request. Example: <tt>%{HTTP:Proxy-Connection}</tt> -is the value of the HTTP header ``<tt>Proxy-Connection:</tt>''. -</ol> - - -<p> -<em>CondPattern</em> is the condition pattern, i.e. a regular expression -which gets applied to the current instance of the <em>TestString</em>, i.e. -<em>TestString</em> gets evaluated and then matched against -<em>CondPattern</em>. - -<p> -<b>Remember:</b> <em>CondPattern</em> is a standard -<em>Extended Regular Expression</em> with some additions: - -<ol> -<li>You can precede the pattern string with a '<tt>!</tt>' character -(exclamation mark) to specify a <b>non</b>-matching pattern. - -<p> -<li> -There are some special variants of <em>CondPatterns</em>. Instead of real -regular expression strings you can also use one of the following: -<p> -<ul> -<li>'<b>-d</b>' (is <b>d</b>irectory)<br> -Treats the <i>TestString</i> as a pathname and -tests if it exists and is a directory. -<p> -<li>'<b>-f</b>' (is regular <b>f</b>ile)<br> -Treats the <i>TestString</i> as a pathname and -tests if it exists and is a regular file. -<p> -<li>'<b>-s</b>' (is regular file with <b>s</b>ize)<br> -Treats the <i>TestString</i> as a pathname and -tests if it exists and is a regular file with size greater then zero. -<p> -<li>'<b>-l</b>' (is symbolic <b>l</b>ink)<br> -Treats the <i>TestString</i> as a pathname and -tests if it exists and is a symbolic link. -</ul> -<p> -Notice: All of these tests can also be prefixed by a not ('!') character -to negate their meaning. -</ol> - -<p> -Additionally you can set special flags for <em>CondPattern</em> by appending - -<blockquote><strong> -<code>[</code><em>flags</em><code>]</code> -</strong></blockquote> - -as the third argument to the <tt>RewriteCond</tt> directive. <em>Flags</em> -is a comma-separated list of the following flags: - -<ul> -<li>'<strong><code>nocase|NC</code></strong>' (<b>n</b>o <b>c</b>ase)<br> - This makes the condition test case-insensitive, i.e. there is - no difference between 'A-Z' and 'a-z' both in the expanded - <em>TestString</em> and the <em>CondPattern</em>. -<p> -<li>'<strong><code>ornext|OR</code></strong>' (<b>or</b> next condition)<br> - Use this to combine rule conditions with a local OR instead of the - implicit AND. Typical example: - <p> -<blockquote><pre> -RewriteCond %{REMOTE_HOST} ^host1.* [OR] -RewriteCond %{REMOTE_HOST} ^host2.* [OR] -RewriteCond %{REMOTE_HOST} ^host3.* -RewriteRule ...some special stuff for any of these hosts... -</pre></blockquote> - Without this flag you had to write down the cond/rule three times. -<p> -</ul> - -<p> -<b>Example:</b> -<blockquote> - -To rewrite the Homepage of a site according to the ``<tt>User-Agent:</tt>'' -header of the request, you can use the following: - -<blockquote><pre> -RewriteCond %{HTTP_USER_AGENT} ^Mozilla.* -RewriteRule ^/$ /homepage.max.html [L] - -RewriteCond %{HTTP_USER_AGENT} ^Lynx.* -RewriteRule ^/$ /homepage.min.html [L] - -RewriteRule ^/$ /homepage.std.html [L] -</pre></blockquote> - -Interpretation: If you use Netscape Navigator as your browser (which identifies -itself as 'Mozilla'), then you get the max homepage, which includes -Frames, etc. If you use the Lynx browser (which is Terminal-based), then you -get the min homepage, which contains no images, no tables, etc. If you -use any other browser you get the standard homepage. -</blockquote> -<p> - -<p> -<hr noshade size=1> -<p> - -<a name="RewriteRule"><h3>RewriteRule</h3></a> -<strong>Syntax:</strong> <code>RewriteRule</code> <em>Pattern</em> <em>Substitution</em><br> -<strong>Default:</strong> -<em>None</em>-<br> -<strong>Context:</strong> server config, virtual host, per-directory config<br> - -<p> -The <tt>RewriteRule</tt> directive is the real rewriting workhorse. The -directive can occur more than once. Each directive then defines one single -rewriting rule. The <b>definition order</b> of these rules is -<b>important</b>, because this order is used when applying the rules at -run-time. - -<p> -<a name="patterns"><em>Pattern</em></a> can be (for Apache 1.1.x a System -V8 and for Apache 1.2.x a POSIX) <a name="regexp">regular expression</a> -which gets applied to the current URL. Here ``current'' means the value of the -URL when this rule gets applied. This may not be the original requested -URL, because there could be any number of rules before which already matched -and made alterations to it. - -<p> -Some hints about the syntax of regular expressions: - -<p> -<table bgcolor="#d0d0d0" cellspacing=0 cellpadding=5> -<tr> -<td valign=top> -<pre> -<strong><code>^</code></strong> Start of line -<strong><code>$</code></strong> End of line -<strong><code>.</code></strong> Any single character -<strong><code>[</code></strong>chars<strong><code>]</code></strong> One of chars -<strong><code>[^</code></strong>chars<strong><code>]</code></strong> None of chars - -<strong><code>?</code></strong> 0 or 1 of the preceding char -<strong><code>*</code></strong> 0 or N of the preceding char -<strong><code>+</code></strong> 1 or N of the preceding char - -<strong><code>\</code></strong>char escape that specific char - (e.g. for specifying the chars "<code>.[]()</code>" etc.) - -<strong><code>(</code></strong>string<strong><code>)</code></strong> Grouping of chars (the <b>N</b>th group can be used on the RHS with <code>$</code><b>N</b>) -</pre> -</td> -</tr> -</table> - -<p> -Additionally the NOT character ('<tt>!</tt>') is a possible pattern -prefix. This gives you the ability to negate a pattern; to say, for instance: ``<i>if -the current URL does <b>NOT</b> match to this pattern</i>''. This can be used -for special cases where it is better to match the negative pattern or as a -last default rule. - -<p> -<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> -<tr><td> -<b>Notice!</b> When using the NOT character to negate a pattern you cannot -have grouped wildcard parts in the pattern. This is impossible because when -the pattern does NOT match, there are no contents for the groups. In -consequence, if negated patterns are used, you cannot use <tt>$N</tt> in the -substitution string! -</td></tr> -</table> - -<p> -<a name="rhs"><em>Substitution</em></a> of a rewriting rule is the string -which is substituted for (or replaces) the original URL for which -<em>Pattern</em> matched. Beside plain text you can use - -<ol> -<li>pattern-group back-references (<code>$N</code>) -<li>server-variables as in rule condition test-strings (<code>%{VARNAME}</code>) -<li><a href="#mapfunc">mapping-function</a> calls (<code>${mapname:key|default}</code>) -</ol> - -Back-references are <code>$</code><b>N</b> (<b>N</b>=1..9) identifiers which -will be replaced by the contents of the <b>N</b>th group of the matched -<em>Pattern</em>. The server-variables are the same as for the -<em>TestString</em> of a <tt>RewriteCond</tt> directive. The -mapping-functions come from the <tt>RewriteMap</tt> directive and are -explained there. These three types of variables are expanded in the order of -the above list. - -<p> -As already mentioned above, all the rewriting rules are applied to the -<em>Substitution</em> (in the order of definition in the config file). The -URL is <b>completely replaced</b> by the <em>Substitution</em> and the -rewriting process goes on until there are no more rules (unless explicitly -terminated by a <code><b>L</b></code> flag - see below). - -<p> -There is a special substitution string named '<tt>-</tt>' which means: -<b>NO substitution</b>! Sounds silly? No, it is useful to provide rewriting -rules which <b>only</b> match some URLs but do no substitution, e.g. in -conjunction with the <b>C</b> (chain) flag to be able to have more than one -pattern to be applied before a substitution occurs. - -<p> -<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> -<tr><td> -<b>Notice</b>: There is a special feature. When you prefix a substitution -field with <tt>http://</tt><em>thishost</em>[<em>:thisport</em>] then -<b>mod_rewrite</b> automatically strips it out. This auto-reduction on -implicit external redirect URLs is a useful and important feature when -used in combination with a mapping-function which generates the hostname -part. Have a look at the first example in the example section below to -understand this. -<p> -<b>Remember:</b> An unconditional external redirect to your own server will -not work with the prefix <tt>http://thishost</tt> because of this feature. -To achieve such a self-redirect, you have to use the <b>R</b>-flag (see -below). -</td></tr> -</table> - -<p> -Additionally you can set special flags for <em>Substitution</em> by appending - -<blockquote><strong> -<code>[</code><em>flags</em><code>]</code> -</strong></blockquote> - -as the third argument to the <tt>RewriteRule</tt> directive. <em>Flags</em> is a -comma-separated list of the following flags: - -<ul> -<li>'<strong><code>redirect|R</code></strong>' (force <a name="redirect"><b>r</b>edirect</a>)<br> - Prefix <em>Substitution</em> - with <code>http://thishost/</code> (which makes the new URL a URI) to - force a external redirection. Use it for rules which should - canonicalize the URL and gives it back to the client, e.g. translate - ``<code>/~</code>'' into ``<code>/u/</code>'' or always append a slash to - <code>/u/</code><em>user</em>, etc.<br> - <b>Notice:</b> When you use this flag, make sure that the - substitution field is a valid URL! If not, you are redirecting to an invalid - location!</b> -<p> -<li>'<strong><code>proxy|P</code></strong>' (force <b>p</b>roxy)<br> - This flag forces the substitution part to be internally forced as a proxy - request and immediately (i.e. rewriting rule processing stops here) put - through the proxy module. You have to make sure that the substitution - string is a valid URI (e.g. typically <tt>http://</tt>) which can - be handled by the Apache proxy module. If not you get an error from - the proxy module. Use this flag to achieve a more powerful implementation - of the <tt>mod_proxy</tt> directive <tt>ProxyPass</tt>, to map - some remote stuff into the namespace of the local server. -<p> -<li>'<strong><code>last|L</code></strong>' (<b>l</b>ast rule)<br> - Stop the rewriting process here and - don't apply any more rewriting rules. This corresponds to the Perl - <code>last</code> command or the <code>break</code> command from the C - language. Use this flag to prevent the currently rewritten URL from being - rewritten further by following rules which may be wrong. For - example, use it to rewrite the root-path URL ('<code>/</code>') to a real - one, e.g. '<code>/e/www/</code>'. -<p> -<li>'<strong><code>next|N</code></strong>' (<b>n</b>ext round)<br> - Re-run the rewriting process (starting again with the first rewriting - rule). Here the URL to match is again not the original URL but the URL - from the last rewriting rule. This corresponds to the Perl - <code>next</code> command or the <code>continue</code> command from the C - language. Use this flag to restart the rewriting process, i.e. to - immediately go to the top of the loop. <br> - <b>But be careful not to create a deadloop!</b> -<p> -<li>'<strong><code>chain|C</code></strong>' (<b>c</b>hained with next rule)<br> - This flag chains the current rule with the next rule (which itself can - also be chained with its following rule, etc.). This has the following - effect: if a rule matches, then processing continues as usual, i.e. the - flag has no effect. If the rule does <b>not</b> match, then all following - chained rules are skipped. For instance, use it to remove the - ``<tt>.www</tt>'' part inside a per-directory rule set when you let an - external redirect happen (where the ``<tt>.www</tt>'' part should not to - occur!). -<p> -<li>'<strong><code>type|T</code></strong>=<em>mime-type</em>' (force MIME <b>t</b>ype)<br> - Force the MIME-type of the target file to be <em>mime-type</em>. For - instance, this can be used to simulate the old <tt>mod_alias</tt> - directive <tt>ScriptAlias</tt> which internally forces all files inside - the mapped directory to have a MIME type of - ``<tt>application/x-httpd-cgi</tt>''. -<p> -<li>'<strong><code>nosubreq|NS</code></strong>' (used only if <b>n</b>o internal <b>s</b>ub-request)<br> - This flag forces the rewriting engine to skip a rewriting rule if the - current request is an internal sub-request. For instance, sub-requests - occur internally in Apache when <tt>mod_include</tt> tries to find out - information about possible directory default files (<tt>index.xxx</tt>). - On sub-requests it is not always useful and even sometimes causes a failure to - if the complete set of rules are applied. Use this flag to exclude some rules.<br> - <p> - Use the following rule for your decision: whenever you prefix some URLs - with CGI-scripts to force them to be processed by the CGI-script, the - chance is high that you will run into problems (or even overhead) on sub-requests. - In these cases, use this flag. -<p> -<li>'<strong><code>passthrough|PT</code></strong>' (<b>p</b>ass <b>t</b>hrough to next handler)<br> - This flag forces the rewriting engine to set the <code>uri</code> field - of the internal <code>request_rec</code> structure to the value - of the <code>filename</code> field. This flag is just a hack to be able - to post-process the output of <tt>RewriteRule</tt> directives by - <tt>Alias</tt>, <tt>ScriptAlias</tt>, <tt>Redirect</tt>, etc. directives - from other URI-to-filename translators. A trivial example to show the - semantics: - If you want to rewrite <tt>/abc</tt> to <tt>/def</tt> via the rewriting - engine of <tt>mod_rewrite</tt> and then <tt>/def</tt> to <tt>/ghi</tt> - with <tt>mod_alias</tt>: - <pre> - RewriteRule ^/abc(.*) /def$1 [PT] - Alias /def /ghi - </pre> - If you omit the <tt>PT</tt> flag then <tt>mod_rewrite</tt> - will do its job fine, i.e. it rewrites <tt>uri=/abc/...</tt> to - <tt>filename=/def/...</tt> as a full API-compliant URI-to-filename - translator should do. Then <tt>mod_alias</tt> comes and tries to do a - URI-to-filename transition which will not work. - <p> - Notice: <b>You have to use this flag if you want to intermix directives - of different modules which contain URL-to-filename translators</b>. The - typical example is the use of <tt>mod_alias</tt> and - <tt>mod_rewrite</tt>.. - -<p> -<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> -<tr><td> -<font size=-1> - <b>For the Apache hackers:</b><br> - If the current Apache API had a - filename-to-filename hook additionally to the URI-to-filename hook then - we wouldn't need this flag! But without such a hook this flag is the - only solution. The Apache Group has discussed this problem and will - add such hooks into Apache version 2.0. -</font> -</td></tr> -</table> -<p> -<li>'<strong><code>skip|S</code></strong>=<em>num</em>' (<b>s</b>kip next rule(s))<br> - This flag forces the rewriting engine to skip the next <em>num</em> rules - in sequence when the current rule matches. Use this to make pseudo - if-then-else constructs: The last rule of the then-clause becomes - a <tt>skip=N</tt> where N is the number of rules in the else-clause. - (This is <b>not</b> the same as the 'chain|C' flag!) -<p> -</ul> - -<p> -<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> -<tr><td> -Remember: Never forget that <em>Pattern</em> gets applied to a complete URL -in per-server configuration files. <b>But in per-directory configuration -files, the per-directory prefix (which always is the same for a specific -directory!) gets automatically <em>removed</em> for the pattern matching and -automatically <em>added</em> after the substitution has been done.</b> This feature is -essential for many sorts of rewriting, because without this prefix stripping -you have to match the parent directory which is not always possible. -<p> -There is one exception: If a substitution string starts with -``<tt>http://</tt>'' then the directory prefix will be <b>not</b> added and a -external redirect or proxy throughput (if flag <b>P</b> is used!) is forced! -</td></tr> -</table> - -<p> -<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> -<tr><td> -Notice! To enable the rewriting engine for per-directory configuration files -you need to set ``<tt>RewriteEngine On</tt>'' in these files <b>and</b> -``<tt>Option FollowSymLinks</tt>'' enabled. If your administrator has -disabled override of <tt>FollowSymLinks</tt> for a user's directory, then -you cannot use the rewriting engine. This restriction is needed for -security reasons. -</td></tr> -</table> - -<p> -Here are all possible substitution combinations and their meanings: - -<p> -<b>Inside per-server configuration (<tt>httpd.conf</tt>)<br> -for request ``<tt>GET /somepath/pathinfo</tt>'':</b><br> - -<p> -<table bgcolor="#d0d0d0" cellspacing=0 cellpadding=5> -<tr> -<td> -<pre> -<b>Given Rule</b> <b>Resulting Substitution</b> ----------------------------------------------- ---------------------------------- -^/somepath(.*) otherpath$1 not supported, because invalid! - -^/somepath(.*) otherpath$1 [R] not supported, because invalid! - -^/somepath(.*) otherpath$1 [P] not supported, because invalid! ----------------------------------------------- ---------------------------------- -^/somepath(.*) /otherpath$1 /otherpath/pathinfo - -^/somepath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo - via external redirection - -^/somepath(.*) /otherpath$1 [P] not supported, because silly! ----------------------------------------------- ---------------------------------- -^/somepath(.*) http://thishost/otherpath$1 /otherpath/pathinfo - -^/somepath(.*) http://thishost/otherpath$1 [R] http://thishost/otherpath/pathinfo - via external redirection - -^/somepath(.*) http://thishost/otherpath$1 [P] not supported, because silly! ----------------------------------------------- ---------------------------------- -^/somepath(.*) http://otherhost/otherpath$1 http://otherhost/otherpath/pathinfo - via external redirection - -^/somepath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo - via external redirection - (the [R] flag is redundant) - -^/somepath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo - via internal proxy -</pre> -</td> -</tr> -</table> - -<p> -<b>Inside per-directory configuration for <tt>/somepath</tt><br> -(i.e. file <tt>.htaccess</tt> in dir <tt>/physical/path/to/somepath</tt> containing -<tt>RewriteBase /somepath</tt>)<br> for -request ``<tt>GET /somepath/localpath/pathinfo</tt>'':</b><br> - -<p> -<table bgcolor="#d0d0d0" cellspacing=0 cellpadding=5> -<tr> -<td> -<pre> -<b>Given Rule</b> <b>Resulting Substitution</b> ----------------------------------------------- ---------------------------------- -^localpath(.*) otherpath$1 /somepath/otherpath/pathinfo - -^localpath(.*) otherpath$1 [R] http://thishost/somepath/otherpath/pathinfo - via external redirection - -^localpath(.*) otherpath$1 [P] not supported, because silly! ----------------------------------------------- ---------------------------------- -^localpath(.*) /otherpath$1 /otherpath/pathinfo - -^localpath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo - via external redirection - -^localpath(.*) /otherpath$1 [P] not supported, because silly! ----------------------------------------------- ---------------------------------- -^localpath(.*) http://thishost/otherpath$1 /otherpath/pathinfo - -^localpath(.*) http://thishost/otherpath$1 [R] http://thishost/otherpath/pathinfo - via external redirection - -^localpath(.*) http://thishost/otherpath$1 [P] not supported, because silly! ----------------------------------------------- ---------------------------------- -^localpath(.*) http://otherhost/otherpath$1 http://otherhost/otherpath/pathinfo - via external redirection - -^localpath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo - via external redirection - (the [R] flag is redundant) - -^localpath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo - via internal proxy -</pre> -</td> -</tr> -</table> - - -</td> -</tr> -</table> - -<p> -<b>Example:</b> -<p> -<blockquote> -We want to rewrite URLs of the form -<blockquote> -<code>/</code> <em>Language</em> -<code>/~</code> <em>Realname</em> -<code>/.../</code> <em>File</em> -</blockquote> -into -<blockquote> -<code>/u/</code> <em>Username</em> -<code>/.../</code> <em>File</em> -<code>.</code> <em>Language</em> -</blockquote> -<p> -We take the rewrite mapfile from above and save it under -<code>/anywhere/map.real-to-user</code>. Then we only have to add the -following lines to the Apache server configuration file: - -<blockquote> -<pre> -RewriteLog /anywhere/rewrite.log -RewriteMap real-to-user txt:/anywhere/map.real-to-host -RewriteRule ^/([^/]+)/~([^/]+)/(.*)$ /u/${real-to-user:$2|nobody}/$3.$1 -</pre> -</blockquote> -</blockquote> - - -<!--#include virtual="footer.html" --> -</BODY> -</HTML>
\ No newline at end of file diff --git a/docs/manual/mod/mod_setenvif.html b/docs/manual/mod/mod_setenvif.html deleted file mode 100644 index d089fa37db..0000000000 --- a/docs/manual/mod/mod_setenvif.html +++ /dev/null @@ -1,275 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Apache module mod_setenvif</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">Module mod_setenvif</H1> - <P> - This module is contained in the <SAMP>mod_setenvif.c</SAMP> file, and - <STRONG>is</STRONG> compiled in by default. It provides for - the ability to set environment variables based upon attributes of the - request. - </P> - <H2>Summary</H2> - <P> - The <SAMP>mod_setenvif</SAMP> module allows you to set environment - variables according to whether different aspects of the request match - regular expressions you specify. These envariables can be used by - other parts of the server to make decisions about actions to be taken. - </P> - <H2>Directives</H2> - <UL> - <LI><A HREF="#BrowserMatch">BrowserMatch</A> - </LI> - <LI><A HREF="#BrowserMatchNoCase">BrowserMatchNoCase</A> - </LI> - <LI><A HREF="#SetEnvIf">SetEnvIf</A> - </LI> - <LI><A HREF="#SetEnvIfNoCase">SetEnvIfNoCase</A> - </LI> - </UL> - - <HR> <!-- the HR is part of the directive description --> - <H2><A NAME="BrowserMatch">The <SAMP>BrowserMatch</SAMP> Directive</A></H2> - <P> - <STRONG>Syntax:</STRONG> BrowserMatch <EM>regex envar[=value] [...]</EM> - <BR> - <STRONG>Default:</STRONG> <EM>none</EM> - <BR> - <STRONG>Context:</STRONG> server config - <BR> - <STRONG>Override:</STRONG> <EM>none</EM> - <BR> - <STRONG>Status:</STRONG> Base - <BR> - <STRONG>Module:</STRONG> mod_setenvif - <BR> - <STRONG>Compatibility:</STRONG> Apache 1.2 and above - </P> - <P> - The BrowserMatch directive defines environment variables based on the - <SAMP>User-Agent</SAMP> HTTP request header field. The first argument - should be a POSIX.2 extended regular expression (similar to an - <SAMP>egrep</SAMP>-style regex). The rest of the arguments give the - names of variables to set, and optionally values to which they should - be set. These take the form of - </P> - <OL> - <LI><SAMP><EM>varname</EM></SAMP>, or - </LI> - <LI><SAMP>!<EM>varname</EM></SAMP>, or - </LI> - <LI><SAMP><EM>varname</EM>=<EM>value</EM></SAMP> - </LI> - </OL> - <P> - In the first form, the value will be set to "1". The second - will remove the given variable if already defined, and the third will - set the variable to the value given by <SAMP><EM>value</EM></SAMP>. If a - <SAMP>User-Agent</SAMP> string matches more than one entry, they will - be merged. Entries are processed in the order in which they appear, - and later entries can override earlier ones. - </P> - <P> - For example: - </P> - <PRE> - BrowserMatch ^Mozilla forms jpeg=yes browser=netscape - BrowserMatch "^Mozilla/[2-3]" tables agif frames javascript - BrowserMatch MSIE !javascript - </PRE> - <P> - Note that the regular expression string is - <STRONG>case-sensitive</STRONG>. For cane-INsensitive matching, see - the - <A - HREF="#BrowserMatchNoCase" - ><SAMP>BrowserMatchNoCase</SAMP></A> - directive. - </P> - <P> - The <SAMP>BrowserMatch</SAMP> and <SAMP>BrowserMatchNoCase</SAMP> - directives are special cases of the - <A - HREF="#SetEnvIf" - ><SAMP>SetEnvIf</SAMP></A> - and - <A - HREF="#SetEnvIfNoCase" - ><SAMP>SetEnvIfNoCase</SAMP></A> - directives. The following two lines have the same effect: - </P> - <PRE> - BrowserMatchNoCase Robot is_a_robot - SetEnvIfNoCase User-Agent Robot is_a_robot - </PRE> - - <HR> <!-- the HR is part of the directive description --> - <H2> - <A NAME="BrowserMatchNoCase"> - The <SAMP>BrowserMatchNoCase</SAMP> Directive - </A> - </H2> - <P> - <STRONG>Syntax:</STRONG> BrowserMatchNoCase <EM>regex envar[=value] [...]</EM> - <BR> - <STRONG>Default:</STRONG> <EM>none</EM> - <BR> - <STRONG>Context:</STRONG> server config - <BR> - <STRONG>Override:</STRONG> <EM>none</EM> - <BR> - <STRONG>Status:</STRONG> Base - <BR> - <STRONG>Module:</STRONG> mod_setenvif - <BR> - <STRONG>Compatibility:</STRONG> Apache 1.2 and above - </P> - <P> - The <SAMP>BrowserMatchNoCase</SAMP> directive is semantically identical to - the - <A - HREF="#BrowserMatch" - ><SAMP>BrowserMatch</SAMP></A> - directive. However, it provides for case-insensitive matching. For - example: - </P> - <PRE> - BrowserMatchNoCase mac platform=macintosh - BrowserMatchNoCase win platform=windows - </PRE> - <P> - The <SAMP>BrowserMatch</SAMP> and <SAMP>BrowserMatchNoCase</SAMP> - directives are special cases of the - <A - HREF="#SetEnvIf" - ><SAMP>SetEnvIf</SAMP></A> - and - <A - HREF="#SetEnvIfNoCase" - ><SAMP>SetEnvIfNoCase</SAMP></A> - directives. The following two lines have the same effect: - </P> - <PRE> - BrowserMatchNoCase Robot is_a_robot - SetEnvIfNoCase User-Agent Robot is_a_robot - </PRE> - - <HR> <!-- the HR is part of the directive description --> - <H2> - <A NAME="SetEnvIf"> - The <SAMP>SetEnvIf</SAMP> Directive - </A> - </H2> - <P> - <STRONG>Syntax:</STRONG> SetEnvIf <EM> attribute regex envar[=value] [...]</EM> - <BR> - <STRONG>Default:</STRONG> <EM>none</EM> - <BR> - <STRONG>Context:</STRONG> server config - <BR> - <STRONG>Override:</STRONG> <EM>none</EM> - <BR> - <STRONG>Status:</STRONG> Base - <BR> - <STRONG>Module:</STRONG> mod_setenvif - <BR> - <STRONG>Compatibility:</STRONG> Apache 1.3 and above - </P> - <P> - The <SAMP>SetEnvIf</SAMP> directive defines environment variables - based on attributes of the request. These attributes can be the - values of various HTTP request header fields (see - <A - HREF="http://ds.internic.net/rfc/rfc2068.txt" - >RFC2068</A> - for more information about these), or of other aspects of the request, - including the following: - </P> - <UL> - <LI><SAMP>Remote_Host</SAMP> - the hostname (if available) of the - client making the request - </LI> - <LI><SAMP>Remote_Addr</SAMP> - the IP address of the client making - the request - </LI> - <LI><SAMP>Remote_User</SAMP> - the authenticated username (if - available) - </LI> - <LI><SAMP>Request_Method</SAMP> - the name of the method being used - (<SAMP>GET</SAMP>, <SAMP>POST</SAMP>, <EM>et cetera</EM>) - </LI> - <LI><SAMP>Request_URI</SAMP> - the portion of the URL following the - scheme and host portion - </LI> - </UL> - <P> - Some of the more commonly used request header field names include - <SAMP>Host</SAMP>, <SAMP>User-Agent</SAMP>, and <SAMP>Referer</SAMP>. - </P> - <P> - Example: - </P> - <PRE> - SetEnvIf Request_URI "\.(gif)|(jpg)|(xbm)$" object_is_image - SetEnvIf Referer www\.mydomain\.com intra_site_referral - </PRE> - <P> - The first will set the envariable <SAMP>object_is_image</SAMP> if the - request was for an image file, and the second sets - <SAMP>intra_site_referral</SAMP> if the referring page was somewhere - on the <SAMP>www.mydomain.com</SAMP> Web site. - </P> - - <HR> <!-- the HR is part of the directive description --> - <H2> - <A NAME="SetEnvIfNoCase"> - The <SAMP>SetEnvIfNoCase</SAMP> Directive - </A> - </H2> - <P> - <STRONG>Syntax:</STRONG> SetEnvIfNoCase - <EM> attribute regex envar[=value] [...]</EM> - <BR> - <STRONG>Default:</STRONG> <EM>none</EM> - <BR> - <STRONG>Context:</STRONG> server config - <BR> - <STRONG>Override:</STRONG> <EM>none</EM> - <BR> - <STRONG>Status:</STRONG> Base - <BR> - <STRONG>Module:</STRONG> mod_setenvif - <BR> - <STRONG>Compatibility:</STRONG> Apache 1.3 and above - </P> - <P> - The <SAMP>SetEnvIfNoCase</SAMP> is semantically identical to the - <A - HREF="#SetEnvIf" - ><SAMP>SetEnvIf</SAMP></A> - directive, and differs only in that the regular expression matching is - performed in a case-insensitive manner. For example: - </P> - <PRE> - SetEnvIfNoCase Host Apache\.Org site=apache - </PRE> - <P> - This will cause the <SAMP>site</SAMP> envariable to be set to - "<SAMP>apache</SAMP>" if the HTTP request header field - <SAMP>Host:</SAMP> was included and contained <SAMP>Apache.Org</SAMP>, - <SAMP>apache.org</SAMP>, or any other combination. - </P> - -<!--#include virtual="footer.html" --> - </BODY> -</HTML> diff --git a/docs/manual/mod/mod_so.html b/docs/manual/mod/mod_so.html deleted file mode 100644 index 9ceefee7d1..0000000000 --- a/docs/manual/mod/mod_so.html +++ /dev/null @@ -1,95 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_so</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">Module mod_so</H1> - -This module is contained in the <CODE>mod_so.c</CODE> file, and is not -compiled in by default. It provides for loading of executable code and -modules into the server at start-up time, on Unix systems. Win32 -systems use <A HREF="mod_dll.html">mod_dll</A> instead. This module is -only available in Apache 1.3 and up. - -<h2>Summary</h2> - -This is an experimental module. On selected operating systems it can -be used to load modules into Apache at runtime, rather than requiring -a recompilation. - - -<h2>Directives</h2> -<UL> -<LI><A HREF="#loadfile">LoadFile</A> -<LI><A HREF="#loadmodule">LoadModule</A> -</UL> -<HR> - - -<h2><A name="loadfile">LoadFile</A></h2> -<!--%plaintext <?INDEX {\tt LoadFile} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> LoadFile <EM>filename filename ...</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Experimental<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_so<P> - -The LoadFile directive links in the named object files or libraries when -the server is started; this is used to load additional code which -may be required for some module to work. <EM>Filename</EM> is relative -to <A HREF="core.html#serverroot">ServerRoot</A>.<P><HR> - -<h2><A name="loadmodule">LoadModule</A></h2> -<!--%plaintext <?INDEX {\tt LoadModule} directive> --> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> LoadModule <EM>module filename</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Experimental<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_so<P> - -The LoadModule directive links in the object file or library <EM>filename</EM> -and adds the module structure named <EM>module</EM> to the list of active -modules. <EM>Module</EM> is the name of the external variable of type -<CODE>module</CODE> in the file. Example: -<BLOCKQUOTE><CODE> -LoadModule status_module modules/mod_status.so -</CODE></BLOCKQUOTE> -loads the module in the modules subdirectory of the ServerRoot.<P> - - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_speling.html b/docs/manual/mod/mod_speling.html deleted file mode 100644 index 2db6c4773a..0000000000 --- a/docs/manual/mod/mod_speling.html +++ /dev/null @@ -1,88 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Apache module mod_speling</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">Module mod_speling</H1> - <P> - This module is contained in the <code>mod_speling.c</code> file, - and is <strong>not</strong> compiled in by default. - It attemps to correct mispellings of - URLs that users might have entered, by ignoring capitalization - and by allowing up to one misspelling.<br> - This catches the majority of misspelled requests. An automatic - "spelling corrected" redirection is returned if only one matching - document was found, and a list of matches is returned if more than - one document with a sufficiently similar name is found. - </P> - - <h2>Summary</h2> - <p> - Requests to documents sometimes cannot be served by the core apache - server because the request was misspelled or miscapitalized. This - module addresses this problem by trying to find a matching document, - even after all other modules gave up. It does its work by comparing - each document name in the requested directory against the requested - document name <STRONG>without regard to case</STRONG>, and allowing - <STRONG>up to one misspelling</STRONG> (character insertion / omission - / transposition or wrong character). A list is built with all document - names which were matched using this strategy. - </p> - <p> - If, after scanning the directory, - <ul> - <li>no matching document was found, Apache will proceed as usual - and return a "document not found" error. - <li>only one document is found that "almost" matches the request, - then it is returned in the form of a redirection response. - <li>more than one document with a close match was found, then - the list of the matches is returned to the client, and the client - can select the correct candidate. - </ul> - </p> - - <h2>Directives</h2> - - <menu> - <li><A HREF="#checkspelling">CheckSpelling</A> - </menu> - - <HR> <!-- the HR is part of the directive description --> - <A name="checkspelling"><h2>CheckSpelling</h2></A> - <!--%plaintext <?INDEX {\tt CheckSpelling} directive> --> - <strong>Syntax:</strong> CheckSpelling <em>on/off</em><br> - <strong>Default:</strong> <code>CheckSpelling Off</code><br> - <Strong>Context:</strong> server config, virtual host<br> - <strong>Status:</strong> Base<br> - <strong>Module:</strong> mod_speling<br> - <strong>Compatibility:</strong> CheckSpelling was available as a separately - available module for Apache 1.1, but was limited to miscapitalizations. - As of Apache 1.3, it is part of the apache distribution<!-- or: - available as a separate module-->.<p> - - This directive enables or disables the spelling module. When enabled, - keep in mind that - <UL> - <LI>the directory scan which is necessary for the spelling - correction will have an impact on the server's performance - when many spelling corrections have to be performed at the same time. - <LI>the document trees should not contain sensitive files which could - be matched inadvertedly, by a spelling "correction". - <LI>the module is unable to correct misspelled user names - (as in <code>http://my.host/~apahce/</code>), just file names or - directory names. - </UL> - -<!--#include virtual="footer.html" --> - </BODY> -</HTML> - diff --git a/docs/manual/mod/mod_status.html b/docs/manual/mod/mod_status.html deleted file mode 100644 index 34ce9b6cc9..0000000000 --- a/docs/manual/mod/mod_status.html +++ /dev/null @@ -1,94 +0,0 @@ -<html><head> -<title>Apache Status Module</title> -</head><body> - -<img src="../images/apache_sub.gif" alt=""> -<h1>Apache Status Module</h1> -<hr> - -The Status Module is only available in Apache 1.1 and later.<p> - -<h2>Function</h2> - -The Status module allows a server administrator to find out how well -their server is performing. A HTML page is presented that gives -the current server statistics in an easily readable form. If required -this page can be made to automatically refresh (given a compatible -browser). Another page gives a simple machine-readable list of the current -server state. -<p> -The details given are: -<ul> -<li>The number of children serving requests -<li>The number of idle children -<li>The status of each child, the number of requests that child has -performed and the total number of bytes served by the child (*) -<li>A total number of accesses and byte count served (*) -<li>The time the server was started/restarted and the -time it has been running for -<li>Averages giving the number of requests per second, -the number of bytes served per second and the average number -of bytes per request (*) -<li>The current percentage CPU used by each child and in total by -Apache (*) -<li>The current hosts and requests being processed (*) -</ul> - -A compile-time option must be used to display the details marked "(*)" as -the instrumentation required for obtaining these statistics does not -exist within standard Apache. - -<h2>Enabling Status Support</h2> - -To enable status reports only for browsers from the foo.com -domain add this code to your <code>access.conf</code> configuration file -<pre> - <Location /server-status> - SetHandler server-status - - <Limit GET POST> - order deny,allow - deny from all - allow from .foo.com - </Limit> - </Location> -</pre> -<p> -You can now access server statistics by using a Web browser to access the -page <code>http://your.server.name/server-status</code> -<h3>Automatic Updates</h3> -You can get the status page to update itself automatically if you have -a browser that supports "refresh". Access the page -<code>http://your.server.name/server-status?refresh=N</code> to refresh the page -every N seconds. -<h3>Machine Readable Status File</h3> -A machine-readable version of the status file is available by accessing the -page <code>http://your.server.name/server-status?auto</code>. This is useful -when automatically run, see the Perl program in the <code>/support</code> -directory of Apache, <code>log_server_status</code>. - -<h2>Full Instrumentation</h2> - -To obtain full statistics you must compile Apache with a special -directive. On some machines there may be a small performance loss -if you do this. Try full statistics and see if you notice any -difference. If you do please contact <a href="mailto:mark@ukweb.com"> -mark@ukweb.com</a> and tell me your configuration. - -<p> -Do this by adding the following to the AUX_CFLAGS line in the -"Configuration" file and then recompiling as usual. -<pre> - AUX_CFLAGS= (something) -DSTATUS -</pre> - - - - -<hr> -<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> -<A HREF="../"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> - -</BODY> -</HTML> - diff --git a/docs/manual/mod/mod_unique_id.html b/docs/manual/mod/mod_unique_id.html deleted file mode 100644 index ff71fce934..0000000000 --- a/docs/manual/mod/mod_unique_id.html +++ /dev/null @@ -1,180 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_unique_id</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">Module mod_unique_id</h1> - -This module provides a magic token for each request which is guaranteed -to be unique across "all" requests under very specific conditions. -The unique identifier is even unique across multiple machines in a -properly configured cluster of machines. The environment variable -<code>UNIQUE_ID</code> is set to the identifier for each request. -Unique identifiers are useful for various reasons which are beyond the -scope of this document. - -<h2>Theory</h2> - -<p> -First a brief recap of how the Apache server works on Unix machines. -This feature currently isn't supported on Windows NT. On Unix machines, -Apache creates several children, the children process requests one at -a time. Each child can serve multiple requests in its lifetime. For the -purpose of this discussion, the children don't share any data -with each other. We'll refer to the children as httpd processes. - -<p> -Your website has one or more machines under your administrative control, -together we'll call them a cluster of machines. Each machine can -possibly run multiple instances of Apache. All of these collectively -are considered "the universe", and with certain assumptions we'll -show that in this universe we can generate unique identifiers for each -request, without extensive communication between machines in the cluster. - -<p> -The machines in your cluster should satisfy these requirements. -(Even if you have only one machine you should synchronize its clock -with NTP.) - -<ul> -<li>The machines' times are synchronized via NTP or other network time - protocol. - -<li>The machines' hostnames all differ, such that the module can do a - hostname lookup on the hostname and receive a different IP address - for each machine in the cluster. -</ul> - -<p> -As far as operating system assumptions go, we assume that pids (process -ids) fit in 32-bits. If the operating system uses more than 32-bits -for a pid, the fix is trivial but must be performed in the code. - -<p> -Given those assumptions, at a single point in time we can identify -any httpd process on any machine in the cluster from all other httpd -processes. The machine's IP address and the pid of the httpd process -are sufficient to do this. So in order to generate unique identifiers -for requests we need only distinguish between different points in time. - -<p> -To distinguish time we will use a Unix timestamp (seconds since January -1, 1970 UTC), and a 16-bit counter. The timestamp has only one second -granularity, so the counter is used to represent up to 65536 values -during a single second. The quadruple <i>( ip_addr, pid, time_stamp, -counter )</i> is sufficient to enumerate 65536 requests per second per -httpd process. There are issues however with pid reuse over -time, and the counter is used to alleviate this issue. - -<p> -When an httpd child is created, the counter is initialized with ( -current microseconds divided by 10 ) modulo 65536 (this formula was -chosen to eliminate some variance problems with the low order bits of -the microsecond timers on some systems). When a unique identifier is -generated, the time stamp used is the time the request arrived at the -web server. The counter is incremented every time an identifier is -generated (and allowed to roll over). - -<p> -The kernel generates a pid for each process as it forks the process, and -pids are allowed to roll over (they're 16-bits on many Unixes, but newer -systems have expanded to 32-bits). So over time the same pid will be -reused. However unless it is reused within the same second, it does not -destroy the uniqueness of our quadruple. That is, we assume the system -does not spawn 65536 processes in a one second interval (it may even be -32768 processes on some Unixes, but even this isn't likely to happen). - -<p> -Suppose that time repeats itself for some reason. That is, suppose that -the system's clock is screwed up and it revisits a past time (or it is -too far forward, is reset correctly, and then revisits the future time). -In this case we can easily show that we can get pid and time stamp reuse. -The choice of initializer for the counter is intended to help defeat this. -Note that we really want a random number to initialize the counter, -but there aren't any readily available numbers on most systems (i.e. you -can't use rand() because you need to seed the generator, and can't seed -it with the time because time, at least at one second resolution, has -repeated itself). This is not a perfect defense. - -<p> -How good a defense is it? Well suppose that one of your machines serves -at most 500 requests per second (which is a very reasonable upper bound -at this writing, because systems generally do more than just shovel out -static files). To do that it will require a number of children which -depends on how many concurrent clients you have. But we'll be pessimistic -and suppose that a single child is able to serve 500 requests per second. -There are 1000 possible starting counter values such that two sequences -of 500 requests overlap. So there is a 1.5% chance that if time (at one -second resolution) repeats itself this child will repeat a counter value, -and uniqueness will be broken. This was a very pessimistic example, -and with real world values it's even less likely to occur. If your -system is such that it's still likely to occur, then perhaps you should -make the counter 32 bits (by editing the code). - -<p> -You may be concerned about the clock being "set back" during summer -daylight savings. However this isn't an issue because the times used here -are UTC, which "always" go forward. Note that x86 based Unixes may need -proper configuration for this to be true -- they should be configured to -assume that the motherboard clock is on UTC and compensate appropriately. -But even still, if you're running NTP then your UTC time will be correct -very shortly after reboot. - -<p> -The <code>UNIQUE_ID</code> environment variable is constructed by -encoding the 112-bit (32-bit IP address, 32 bit pid, 32 bit time stamp, -16 bit counter) quadruple using the alphabet <code>[A-Za-z0-9@-]</code> -in a manner similar to MIME base64 encoding, producing 19 characters. -The MIME base64 alphabet is actually <code>[A-Za-z0-9+/]</code> however -<code>+</code> and <code>/</code> need to be specially encoded in URLs, -which makes them less desirable. All values are encoded in network -byte ordering so that the encoding is comparable across architectures of -different byte ordering. The actual ordering of the encoding is: time -stamp, IP address, pid, counter. This ordering has a purpose, but it -should be emphasized that applications should not dissect the encoding. -Applications should treat the entire encoded <code>UNIQUE_ID</code> as an -opaque token, which can be compared against other <code>UNIQUE_ID</code>s -for equality only. - -<p> -The ordering was chosen such that it's possible to change the encoding -in the future without worrying about collision with an existing database -of <code>UNIQUE_ID</code>s. The new encodings should also keep the time -stamp as the first element, and can otherwise use the same alphabet and -bit length. Since the time stamps are essentially an increasing sequence, -it's sufficient to have a <i>flag second</i> in which all machines in the -cluster stop serving and request, and stop using the old encoding format. -Afterwards they can resume requests and begin issuing the new encodings. - -<p> -This we believe is a relatively portable solution to this problem. It can -be extended to multithreaded systems like Windows NT, and can grow with -future needs. The identifiers generated have essentially an infinite -life-time because future identifiers can be made longer as required. -Essentially no communication is required between machines in the cluster -(only NTP synchronization is required, which is low overhead), and no -communication between httpd processes is required (the communication is -implicit in the pid value assigned by the kernel). In very specific -situations the identifier can be shortened, but more information needs -to be assumed (for example the 32-bit IP address is overkill for any -site, but there is no portable shorter replacement for it). - -<hr> - -<h2>Directives</h2> - -<code>mod_unique_id</code> has no directives. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/mod/mod_userdir.html b/docs/manual/mod/mod_userdir.html deleted file mode 100644 index a1a517faff..0000000000 --- a/docs/manual/mod/mod_userdir.html +++ /dev/null @@ -1,54 +0,0 @@ -<!--%hypertext --> -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_userdir</TITLE> -</HEAD> - -<BODY> -<IMG SRC="../images/apache_sub.gif" ALT=""> -<!--/%hypertext --> -<H1>Module mod_userdir</h1> - -This module is contained in the <code>mod_userdir.c</code> file, and -is compiled in by default. It provides for user-specific directories. - -<!--%hypertext --> -<ul> -<li><A HREF="#userdir">UserDir</A> -</ul> -<hr> -<!--/%hypertext --> - -<A name="userdir"><h2>UserDir</h2></A> -<!--%plaintext <?INDEX {\tt UserDir} directive> --> -<strong>Syntax:</strong> UserDir <em>directory/filename</em><br> -<strong>Default:</strong> <code>UserDir public_html</code><br> -<Strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_userdir<p> - -The UserDir directive sets the real directory in a user's home directory -to use when a request for a document for a user is received. -<em>Directory</em> is either <code>disabled</code>, to disable this feature, - or the name of a directory, following one of the following -patterns. If not disabled, then a request for -<code>http://www.foo.com/~bar/one/two.html</code> will be translated to: -<pre> -UserDir public_html -> ~bar/public_html/one/two.html -UserDir /usr/web -> /usr/web/bar/one/two.html -UserDir /home/*/www -> /home/bar/www/one/two.html -</pre> -The following directives will send redirects to the client: -<pre> -UserDir http://www.x.com/users -> http//www.x.com/users/bar/one/two.html -UserDir http://www.x.com/*/y -> http://www.x.com/y/one/two.html -</pre> -<!--%hypertext --> -<hr> -<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> -<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> - -</BODY> -</HTML> -<!--/%hypertext --> diff --git a/docs/manual/mod/mod_usertrack.html b/docs/manual/mod/mod_usertrack.html deleted file mode 100644 index c327020c8f..0000000000 --- a/docs/manual/mod/mod_usertrack.html +++ /dev/null @@ -1,41 +0,0 @@ -<!--%hypertext --> -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Apache module mod_usertrack</TITLE> -</HEAD> - -<BODY> -<IMG SRC="../images/apache_sub.gif" ALT=""> -<!--/%hypertext --> -<H1>Module mod_usertrack</h1> - -This module is contained in the <code>mod_usertrack.c</code> file, and -is not compiled in by default. It provides for user tracking using cookies. -There is no documentation available for this module. Mark is writing this. - -<!--%hypertext --> -<menu> -<li><A HREF="#cookielog">CookieLog</A> -</menu> -<hr> -<!--/%hypertext --> - -<A name="cookielog"><h2>CookieLog</h2></A> -<!--%plaintext <?INDEX {\tt CookieLog} directive> --> -<strong>Syntax:</strong> CookieLog <em>filename</em><br> -<Strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> Experimental<br> -<strong>Module:</strong> mod_cookies<p> - -The CookieLog directive sets the filename for logging of cookies. -The filename is relative to the <A HREF="core.html#serverroot">ServerRoot</A>. -<p> -<!--%hypertext --> -<hr> -<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> -<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> - -</BODY> -</HTML> -<!--/%hypertext --> diff --git a/docs/manual/platform/perf-hp.html b/docs/manual/platform/perf-hp.html deleted file mode 100644 index 0bf286747d..0000000000 --- a/docs/manual/platform/perf-hp.html +++ /dev/null @@ -1,124 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<html> -<head> -<title>Running a High-Performance Web Server on HPUX</title> -</head> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<A NAME="initial"> -<DIV ALIGN="CENTER"> - <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> - <H3> - Apache HTTP Server Version 1.3 - </H3> -</DIV> - -</A> -<H1 ALIGN="CENTER">Running a High-Performance Web Server for HPUX</H1> - -<PRE> -Date: Wed, 05 Nov 1997 16:59:34 -0800 -From: Rick Jones <<A HREF="mailto:raj@cup.hp.com">raj@cup.hp.com</A>> -Reply-To: raj@cup.hp.com -Organization: Network Performance -Subject: HP-UX tuning tips -</PRE> - -Here are some tuning tips for HP-UX to add to the tuning page. - -<P> - -For HP-UX 9.X: Upgrade to 10.20<BR> -For HP-UX 10.[00|01|10]: Upgrade to 10.20 - -<P> - -For HP-UX 10.20: - -<P> - -Install the latest cumulative ARPA Transport Patch. This will allow you -to configure the size of the TCP connection lookup hash table. The -default is 256 buckets and must be set to a power of two. This is -accomplished with adb against the *disc* image of the kernel. The -variable name is tcp_hash_size. - -<P> - -How to pick the value? Examine the output of -<A HREF="ftp://ftp.cup.hp.com/dist/networking/tools/connhist"> -ftp://ftp.cup.hp.com/dist/networking/tools/connhist</A> and see how many -total TCP connections exist on the system. You probably want that number -divided by the hash table size to be reasonably small, say less than 10. -Folks can look at HP's SPECweb96 disclosures for some common settings. -These can be found at <A HREF="http://www.specbench.org/"> -http://www.specbench.org/</A>. If an HP-UX system was -performing at 1000 SPECweb96 connections per second, the TIME_WAIT time -of 60 seconds would mean 60,000 TCP "connections" being tracked. - -<P> - -Folks can check their listen queue depths with -<A HREF="ftp://ftp.cup.hp.com/dist/networking/misc/listenq"> -ftp://ftp.cup.hp.com/dist/networking/misc/listenq</A>. - -<P> - -If folks are running Apache on a PA-8000 based system, they should -consider "chatr'ing" the Apache executable to have a large page size. -This would be "chatr +pi L <binary>." The GID of the running executable -must have MLOCK priviledges. Setprivgrp(1m) should be consulted for -assigning MLOCK. The change can be validated by running Glance and -examining the memory regions of the server(s) to make sure that they -show a non-trivial fraction of the text segment being locked. - -<P> - -If folks are running Apache on MP systems, they might consider writing a -small program that uses mpctl() to bind processes to processors. A -simple pid % numcpu algorithm is probably sufficient. This might even go -into the source code. - -<P> - -If folks are concerned about the number of FIN_WAIT_2 connections, they -can use nettune to shrink the value of tcp_keepstart. However, they -should be careful there - certainly do not make it less than oh two to -four minutes. If tcp_hash_size has been set well, it is probably OK to -let the FIN_WAIT_2's take longer to timeout (perhaps even the default -two hours) - they will not on average have a big impact on performance. - -<P> - -There are other things that could go into the code base, but that might -be left for another email. Feel free to drop me a message if you or -others are interested. - -<P> - -sincerely, - -<P> - -rick jones<BR> -<A HREF="http://www.cup.hp.com/netperf/NetperfPage.html"> -http://www.cup.hp.com/netperf/NetperfPage.html</A> - -<HR> - -<H3 ALIGN="CENTER"> - Apache HTTP Server Version 1.3 -</H3> - -<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> -<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> - -</body></html> - diff --git a/docs/manual/platform/windows.html b/docs/manual/platform/windows.html deleted file mode 100644 index 43889ca908..0000000000 --- a/docs/manual/platform/windows.html +++ /dev/null @@ -1,229 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Using Apache with Microsoft Windows</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">Using Apache With Microsoft Windows</H1> - -<p>This document explains how to compile, install, configure and run - Apache 1.3a1 (or later) under Microsoft Windows. Please note that at - this time, Windows support is entirely experimental, and is - recommended only for experienced users. The Apache Group does not - guarantee that this software will work as documented, or even at - all. If you find any bugs, or wish to contribute in other ways, please - use our <a href="http://www.apache.org/bug_report.html">bug reporting - page.</a></p> - -<hr> - -<ul> - <li><a href="#req">Requirements</a> - <li><a href="#down">Downloading Apache for Windows</a> - <li><a href="#comp">Compiling Apache for Windows</a> - <li><a href="#inst">Installing Apache for Windows</a> - <li><a href="#use">Using Apache for Windows</a> -</ul> - -<hr> - -<h2><a name="req">Requirements</a></h2> - -<p>Apache 1.3a1 requires the following:</p> - -<ul> - <li>Microsoft Windows NT 4.0<a href="#351">*</a>, or Windows 95. - <li>An Intel-based PC-compatible capable of running above OS (exact - requirements unknown) with a connection to a TCP/IP network. - <li>Microsoft Visual C++ 5.0 or later. -</ul> - -<p><small><a name="351">*</a> Apache may run with Windows NT 3.5.1, but - has not been tested.</small></p> - -<p>Apache 1.3a1 is available only in source form. Future releases will - contain prebuilt binaries for use by those without compilers (which we - understand are the vast majority of Windows users), however the - current release requires Microsoft Visual C++ 5.0 or later. The Apache - Group is releasing 1.3a1 only as source to limit the alpha release to - those who have the tools and knowledge to assist with the development - processes.</p> - -<p>This documentation assumes good working knowledge of Microsoft - Windows, Microsoft Visual C++, and the Apache web server (for - Unix).</p> - -<H2><a name="down">Downloading Apache for Windows</a></H2> - -<p>Information on the latest version of Apache can be found on the Apache -web server at <A -HREF="http://www.apache.org/">http://www.apache.org/</A>. This will -list the current release, any more recent alpha or beta-test release, -together with details of mirror web and anonymous ftp sites.</p> - -<p>You will be able to download Apache 1.3a1 or a later release in - several forms, including a WinZip (<code>.zip</code>) - archive. Although this contains the same files as the others (likely - <code>.tar.gz</code> and <code>.tar.Z</code>), it is recommended for - Windows use, as all the files contained therein will contain Windows - line breaks. The other archives may contain files with Unix line - breaks, which will not function on Windows (although they may).</p> - -<h2><a name="comp">Compiling Apache for Windows</a></h2> - -<p>Compiling Apache requires Microsoft Visual C++ 5.0 to be properly - installed. It is easiest to compile with the command-line tools - (nmake, etc...). Consult the VC++ manual to determine how to install - them.</p> - -<p>First, unpack the Apache distribution into an appropriate - directory. Open a command-line prompt, and change to the - <code>src</code> subdirectory of the Apache distribution.</p> - -<p>The master Apache makefile instructions are contained in the - <code>Makefile.nt</code> file. To compile Apache, simply use one of - the following commands: -<ul> -<li><code>nmake /f Makefile.nt release</code> -<li><code>nmake /f Makefile.nt debug</code> -</ul> - -<p>These will both compile Apache. The latter will include debugging - information in the resulting files, making it easier to find bugs and - track down problems.</p> - -<p>Apache can also be compiled using VC++'s Visual Studio development - environment. Although compiling Apache in this manner is not as simple, - it makes it possible to easily modify the Apache source, or to compile - Apache if the command-line tools are not installed.</p> - -<p>Project files (<code>.DSP</code>) are included for each of the - portions of Apache. The two projects that are necessary for Apache to - run are <code>Apache.dsp</code> and <code>ApacheCore.dsp</code>. The - <code>src\nt</code> subdirectory also contains project files for the - optional modules (see below).</p> - -<h2><a name="inst">Installing Apache for Windows</a></h2> - -<p>Once Apache has been compiled, it needs to be installed in its server - root directory. The hard-coded default is the <code>\Apache</code> - directory, on the current hard drive. Another directory may be used, - but the files will need to be installed manually.</p> - -<p>To install the files into the </code>\Apache</code> directory - automatically, use one the following nmake commands (see above):</p> -<ul> -<li><code>nmake /f Makefile.nt installr</code> (for release build) -<li><code>nmake /f Makefile.nt installd</code> (for debug build) -</ul> - -<p>This will install the following:</p> - -<ul> - <li><code>\Apache\Apache.exe</code> - Apache executable - <li><code>\Apache\ApacheCore.dll</code> - Main Apache shared library - <li><code>\Apache\modules\ApacheModule*.dll</code> - Optional Apache - modules (7 files) - <li><code>\Apache\conf</code> - Empty configuration directory - <li><code>\Apache\logs</code> - Empty logging directory -</ul> - -<p>If you do not have nmake, or wish to install in a different directory, - be sure to use a similar naming scheme.</p> - -<h2><a name="use">Using Apache for Windows</a></h2> - -<p>The first step is to set up Apache's configuration files. Default - configuration files for Windows are located in the <code>conf</code> - subdirectory in the Apache distribution, and are named - <code>httpd.conf-dist-win</code>, <code>access.conf-dist-win</code> - and <code>srm.conf-dist-win</code>. Move these into - <code>\Apache\conf</code>, and rename them <code>httpd.conf</code>, - <code>access.conf</code> and <code>srm.conf</code>, respectively.</p> - -<p>Configuring Apache is nearly identical to the Unix version of Apache, - so most of the standard <a href="./">Apache documentation</a> is - applicable. A few things are, however, different:</p> - -<ul> - <li><p>Because Apache for Windows is multithreaded, it does not use a - separate process for each request, as Apache does with - Unix. Therefore, the "process"-management directives are different: - <p><a href="mod/core.html#startservers">StartServers</a> - This - tells the server how many processes to use. Unlike Unix, there - will never be more than this number, and only one will be used - at a time (the others will be held in reserve in case the main - processes crashes or otherwise dies). The recommended default is - <code>StartServers 3</code>. - <p><a - href="mod/core.html#maxrequestsperchild">MaxRequestsPerChild</a> - - Like the Unix directive, this controls how many requests a - process will serve before exiting. However, unlike Unix, a - process serves all the requests at once, not just one, so if - this is set, it is recommended that a very high number is - used. The recommended default, <code>MaxRequestsPerChild - 0</code>, does not cause the process to ever exit. - <p><a href="mode/core.html#threadsperchild">ThreadsPerChild</a> - - This directive is new, and tells the server how many threads it - should use. This is the maximum number of connections the server - can handle at once; be sure and set this number high enough for - your site if you get a lot of hits. The recommended default is - <code>ThreadsPerChild 20</code>.</p> - <li><p>The directives that accept filenames as arguments now must use - Windows filenames instead of Unix ones. However, because Apache - uses Unix-style names internally, you must use forward slashes, not - backslashes. Drive letters can be used; if omitted, the drive with - the Apache executable will be assumed.</p> - <li><p>Apache for Windows contains the ability to load modules at runtime, - without recompiling the server. If Apache is compiled normally, it - will install a number of optional modules in the - <code>\Apache\modules</code> directory. To activate these, or other - modules, the new <a href="mod/mod_dll.html#loadmodule">LoadModule</a> - directive must be used. For example, to active the status module, - use the following (in addition to the status-activating directives - in <code>access.conf</code>):</p> -<pre> - LoadModule status_module modules/ApacheModuleStatus.dll -</pre> - <p>Information on <a href="mod/mod_dll.html#creating">creating module - DLLs</a> is also available.</p> -</ul> - -<p>Once Apache is configured correctly, it is nearly ready to be -run. However, we recommend you copy the <code>icons</code> and -<code>htdocs</code> subdirectories from the Apache distribution to -<code>\Apache</code>. The latter is especially important, as it contains -the document root (what the server actually serves). - -<p>Apache can be executed in one of two ways, directly from the command - line, or as a Windows NT service. To run it from the command line, use - the following command: -<pre> - C:\Apache> <b>apache -s</b> -</pre> - -<p>Apache will then execute, and will remain running until it is - exited. To use Apache as a Windows NT service, use the following:</p> -<pre> - C:\Apache> <b>apache -i</b> -</pre> -<p>Then open the Services control panel, and start the Apache service.</p> - -<p>If you installed Apache in a server root other than - <code>\Apache</code>, you must use the <code>-f</code> command-line - option to specify the httpd.conf file, or the <code>-d</code> option - to specify the server root.</p> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/sections.html b/docs/manual/sections.html deleted file mode 100644 index a145a56531..0000000000 --- a/docs/manual/sections.html +++ /dev/null @@ -1,139 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<html><head> -<title>How Directory, Location and Files sections work</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">How Directory, Location and Files sections work</h1> - -The sections <a -href="mod/core.html#directory"><code><Directory></code></a>, <a -href="mod/core.html#location"><code><Location></code></a> and <a -href="mode/core.html#files"><code><Files></code></a> can contain -directives which only apply to specified directories, URLs or files -respectively. Also htaccess files can be used inside a directory to -apply directives to that directory. This document explains how these -different sections differ and how they relate to each other when -Apache decides which directives apply for a particular directory or -request URL. - -<h2>Directives allowed in the sections</h2> - -Everything that is syntactically allowed in -<code><Directory></code> is also allowed in -<code><Location></code> (except a sub-<code><Files></code> -section, but the code doesn't test for that, Lars has an open bug -report on that). Semantically however some things, and the most -notable is AllowOverrides, make no sense in -<code><Location></code>. The same for -<code><Files></code> -- syntactically everything is fine, but -semantically some things are different. - -<h2>How the sections are merged</h2> - -The order of merging is: - -<ol> - -<li> - - <code><Directory></code> (except regular expressions) and - .htaccess done simultaneously (with .htaccess overriding - <code><Directory></code>) - -</li> - -<li> - <code><DirectoryMatch></code>, and - <code><Directory></code> with regular expressions - -</li> - - <li><code><Files></code> and <code><FilesMatch></code> done simultaneously - </li> - - <li><code><Location></code> and <code><LocationMatch></code> done simultaneously - </li> - -</ol> - -Apart from <code><Directory></code>, each group is processed in -the order that they appear in the configuration -files. <code><Directory></code> (group 1 above) is processed in -the order shortest directory component to longest. If multiple -<code><Directory></code> sections apply to the same directory -they they are processed in the configuration file order. The -configuration files are read in the order httpd.conf, srm.conf and -access.conf. Configurations included via the <code>Include</code> -directive will be treated as if they where inside the including file -at the location of the <code>Include</code> directive. - -<p> - -Sections inside <code><VirtualHost></code> sections are applied -<i>after</i> the corresponding sections outside the virtual host -definition. This allows virtual hosts to override the main server -configuration. (Note: this only works correctly from 1.2.2 and 1.3a2 -onwards. Before those releases sections inside virtual hosts were -applied <i>before</i> the main server). - -<h2>Notes about using sections</h2> - -The general guidelines are: - -<p> - -<ul> -<li> - If you are attempting to match objects at the filesystem level - then you must use <code><Directory></code> and/or - <code><Files></code>. -</li> - -<li> - If you are attempting to match objects at the URL level then you - must use <code><Location></code> -</li> -</ul> - -But a notable exception is: - -<ul> -<li> - proxy control is done via <code><Directory></code>. This is - a legacy mistake because the proxy existed prior to - <code><Location></code>. A future version of the config - language should probably switch this to - <code><Location></code>. -</li> -</ul> - -Note also that modifying .htaccess parsing during Location doesn't do -anything because .htaccess parsing has already occured. - -<p> - -Another note: -<p> - -<ul> -<li> - There is actually a - <code><Location></code>/<code><LocationMatch></code> - sequence performed just before the name translation phase (where - <code>Aliases</code> and <code>DocumentRoots</code> are used to - map URLs to filenames). The results of this sequence are - completely thrown away after the translation has completed. -</li> -</ul> - -<!--#include virtual="footer.html" --> -</body></html> diff --git a/docs/manual/sections.html.en b/docs/manual/sections.html.en deleted file mode 100644 index a145a56531..0000000000 --- a/docs/manual/sections.html.en +++ /dev/null @@ -1,139 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<html><head> -<title>How Directory, Location and Files sections work</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">How Directory, Location and Files sections work</h1> - -The sections <a -href="mod/core.html#directory"><code><Directory></code></a>, <a -href="mod/core.html#location"><code><Location></code></a> and <a -href="mode/core.html#files"><code><Files></code></a> can contain -directives which only apply to specified directories, URLs or files -respectively. Also htaccess files can be used inside a directory to -apply directives to that directory. This document explains how these -different sections differ and how they relate to each other when -Apache decides which directives apply for a particular directory or -request URL. - -<h2>Directives allowed in the sections</h2> - -Everything that is syntactically allowed in -<code><Directory></code> is also allowed in -<code><Location></code> (except a sub-<code><Files></code> -section, but the code doesn't test for that, Lars has an open bug -report on that). Semantically however some things, and the most -notable is AllowOverrides, make no sense in -<code><Location></code>. The same for -<code><Files></code> -- syntactically everything is fine, but -semantically some things are different. - -<h2>How the sections are merged</h2> - -The order of merging is: - -<ol> - -<li> - - <code><Directory></code> (except regular expressions) and - .htaccess done simultaneously (with .htaccess overriding - <code><Directory></code>) - -</li> - -<li> - <code><DirectoryMatch></code>, and - <code><Directory></code> with regular expressions - -</li> - - <li><code><Files></code> and <code><FilesMatch></code> done simultaneously - </li> - - <li><code><Location></code> and <code><LocationMatch></code> done simultaneously - </li> - -</ol> - -Apart from <code><Directory></code>, each group is processed in -the order that they appear in the configuration -files. <code><Directory></code> (group 1 above) is processed in -the order shortest directory component to longest. If multiple -<code><Directory></code> sections apply to the same directory -they they are processed in the configuration file order. The -configuration files are read in the order httpd.conf, srm.conf and -access.conf. Configurations included via the <code>Include</code> -directive will be treated as if they where inside the including file -at the location of the <code>Include</code> directive. - -<p> - -Sections inside <code><VirtualHost></code> sections are applied -<i>after</i> the corresponding sections outside the virtual host -definition. This allows virtual hosts to override the main server -configuration. (Note: this only works correctly from 1.2.2 and 1.3a2 -onwards. Before those releases sections inside virtual hosts were -applied <i>before</i> the main server). - -<h2>Notes about using sections</h2> - -The general guidelines are: - -<p> - -<ul> -<li> - If you are attempting to match objects at the filesystem level - then you must use <code><Directory></code> and/or - <code><Files></code>. -</li> - -<li> - If you are attempting to match objects at the URL level then you - must use <code><Location></code> -</li> -</ul> - -But a notable exception is: - -<ul> -<li> - proxy control is done via <code><Directory></code>. This is - a legacy mistake because the proxy existed prior to - <code><Location></code>. A future version of the config - language should probably switch this to - <code><Location></code>. -</li> -</ul> - -Note also that modifying .htaccess parsing during Location doesn't do -anything because .htaccess parsing has already occured. - -<p> - -Another note: -<p> - -<ul> -<li> - There is actually a - <code><Location></code>/<code><LocationMatch></code> - sequence performed just before the name translation phase (where - <code>Aliases</code> and <code>DocumentRoots</code> are used to - map URLs to filenames). The results of this sequence are - completely thrown away after the translation has completed. -</li> -</ul> - -<!--#include virtual="footer.html" --> -</body></html> diff --git a/docs/manual/stopping.html b/docs/manual/stopping.html deleted file mode 100644 index 898acca3ca..0000000000 --- a/docs/manual/stopping.html +++ /dev/null @@ -1,137 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Stopping and Restarting Apache</TITLE> -</HEAD> - -<BODY> -<!--#include virtual="header.html" --> -<h1>Stopping and Restarting Apache</h1> - -<p>You will notice many <code>httpd</code> executables running on your system, -but you should not send signals to any of them except the parent, whose -pid is in the <a href="mod/core.html#pidfile">PidFile</a>. That is to -say you shouldn't ever need to send signals to any process except the -parent. There are three signals that you can send the parent: -<code>TERM</code>, <code>HUP</code>, and <code>USR1</code>, which will -be described in a moment. - -<p>To send a signal to the parent you should issue a command such as: -<blockquote><pre> - kill -TERM `cat /usr/local/etc/httpd/logs/httpd.pid` -</pre></blockquote> - -You can read about its progress by issuing: - -<blockquote><pre> - tail -f /usr/local/etc/httpd/logs/error_log -</pre></blockquote> - -Modify those examples to match your -<a href="mod/core.html#serverroot">ServerRoot</a> and -<a href="mod/core.html#pidfile">PidFile</a> settings. - -<h3>TERM Signal: stop now</h3> - -<p>Sending the <code>TERM</code> signal to the parent causes it to -immediately attempt to kill off all of its children. It may take it -several seconds to complete killing off its children. Then the -parent itself exits. Any requests in progress are terminated, and no -further requests are served. - -<h3>HUP Signal: restart now</h3> - -<p>Sending the <code>HUP</code> signal to the parent causes it to kill off -its children like in <code>TERM</code> but the parent doesn't exit. It -re-reads its configuration files, and re-opens any log files. -Then it spawns a new set of children and continues -serving hits. - -<p>Users of the -<a href="mod/mod_status.html">status module</a> -will notice that the server statistics are -set to zero when a <code>HUP</code> is sent. - -<h3>USR1 Signal: graceful restart</h3> - -<p><b>Note:</b> prior to release 1.2b9 this code is quite unstable and -shouldn't be used at all. - -<p>The <code>USR1</code> signal causes the parent process to <i>advise</i> -the children to exit after their current request (or to exit immediately -if they're not serving anything). The parent re-reads its configuration -files and re-opens its log files. As each child dies off the parent -replaces it with a child from the new <i>generation</i> of the -configuration, which begins serving new requests immediately. - -<p>This code is designed to always respect the -<a href="mod/core.html#maxclients">MaxClients</a>, -<a href="mod/core.html#minspareservers">MinSpareServers</a>, -and <a href="mod/core.html#maxspareservers">MaxSpareServers</a> settings. -Furthermore, it respects <a href="mod/core.html#startservers">StartServers</a> -in the following manner: if after one second at least StartServers new -children have not been created, then create enough to pick up the slack. -This is to say that the code tries to maintain both the number of children -appropriate for the current load on the server, and respect your wishes -with the StartServers parameter. - -<p>Users of the -<a href="mod/mod_status.html">status module</a> -will notice that the server statistics -are <b>not</b> set to zero when a <code>USR1</code> is sent. The code -was written to both minimize the time in which the server is unable to serve -new requests (they will be queued up by the operating system, so they're -not lost in any event) and to respect your tuning parameters. In order -to do this it has to keep the <i>scoreboard</i> used to keep track -of all children across generations. - -<p>The status module will also use a <code>G</code> to indicate those -children which are still serving requests started before the graceful -restart was given. - -<p>At present there is no way for a log rotation script using -<code>USR1</code> to know for certain that all children writing the -pre-restart log have finished. We suggest that you use a suitable delay -after sending the <code>USR1</code> signal before you do anything with the -old log. For example if most of your hits take less than 10 minutes to -complete for users on low bandwidth links then you could wait 15 minutes -before doing anything with the old log. - -<h3>Appendix: signals and race conditions</h3> - -<p>Prior to Apache 1.2b9 there were several <i>race conditions</i> -involving the restart and die signals (a simple description of race -condition is: a time-sensitive problem, as in if something happens at just -the wrong time it won't behave as expected). For those architectures that -have the "right" feature set we have eliminated as many as we can. -But it should be noted that there still do exist race conditions on -certain architectures. - -<p>Architectures that use an on disk <a -href="mod/core.html#scoreboardfile">ScoreBoardFile</a> have the potential -to lose track of a child during graceful restart (you'll see an <a -href="mod/core.html#errorlog">ErrorLog</a> message saying something about -a <i>long lost child</i>). The ScoreBoardFile directive explains how -to figure out if your server uses a file, and possibly how to avoid it. -There is also the potential that the scoreboard will be corrupted during -any signalling, but this only has bad effects on graceful restart. - -<p><code>NEXT</code> and <code>MACHTEN</code> have small race conditions -which can cause a restart/die signal to be lost, but should not cause the -server to do anything otherwise problematic. -<!-- they don't have sigaction, or we're not using it -djg --> - -<p>All architectures have a small race condition in each child involving -the second and subsequent requests on a persistent HTTP connection -(KeepAlive). It may exit after reading the request line but before -reading any of the request headers. There is a fix that was discovered -too late to make 1.2. In theory this isn't an issue because the KeepAlive -client has to expect these events because of network latencies and -server timeouts. In practice it doesn't seem to affect anything either --- in a test case the server was restarted twenty times per second and -clients successfully browsed the site without getting broken images or -empty documents. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/stopping.html.en b/docs/manual/stopping.html.en deleted file mode 100644 index 898acca3ca..0000000000 --- a/docs/manual/stopping.html.en +++ /dev/null @@ -1,137 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Stopping and Restarting Apache</TITLE> -</HEAD> - -<BODY> -<!--#include virtual="header.html" --> -<h1>Stopping and Restarting Apache</h1> - -<p>You will notice many <code>httpd</code> executables running on your system, -but you should not send signals to any of them except the parent, whose -pid is in the <a href="mod/core.html#pidfile">PidFile</a>. That is to -say you shouldn't ever need to send signals to any process except the -parent. There are three signals that you can send the parent: -<code>TERM</code>, <code>HUP</code>, and <code>USR1</code>, which will -be described in a moment. - -<p>To send a signal to the parent you should issue a command such as: -<blockquote><pre> - kill -TERM `cat /usr/local/etc/httpd/logs/httpd.pid` -</pre></blockquote> - -You can read about its progress by issuing: - -<blockquote><pre> - tail -f /usr/local/etc/httpd/logs/error_log -</pre></blockquote> - -Modify those examples to match your -<a href="mod/core.html#serverroot">ServerRoot</a> and -<a href="mod/core.html#pidfile">PidFile</a> settings. - -<h3>TERM Signal: stop now</h3> - -<p>Sending the <code>TERM</code> signal to the parent causes it to -immediately attempt to kill off all of its children. It may take it -several seconds to complete killing off its children. Then the -parent itself exits. Any requests in progress are terminated, and no -further requests are served. - -<h3>HUP Signal: restart now</h3> - -<p>Sending the <code>HUP</code> signal to the parent causes it to kill off -its children like in <code>TERM</code> but the parent doesn't exit. It -re-reads its configuration files, and re-opens any log files. -Then it spawns a new set of children and continues -serving hits. - -<p>Users of the -<a href="mod/mod_status.html">status module</a> -will notice that the server statistics are -set to zero when a <code>HUP</code> is sent. - -<h3>USR1 Signal: graceful restart</h3> - -<p><b>Note:</b> prior to release 1.2b9 this code is quite unstable and -shouldn't be used at all. - -<p>The <code>USR1</code> signal causes the parent process to <i>advise</i> -the children to exit after their current request (or to exit immediately -if they're not serving anything). The parent re-reads its configuration -files and re-opens its log files. As each child dies off the parent -replaces it with a child from the new <i>generation</i> of the -configuration, which begins serving new requests immediately. - -<p>This code is designed to always respect the -<a href="mod/core.html#maxclients">MaxClients</a>, -<a href="mod/core.html#minspareservers">MinSpareServers</a>, -and <a href="mod/core.html#maxspareservers">MaxSpareServers</a> settings. -Furthermore, it respects <a href="mod/core.html#startservers">StartServers</a> -in the following manner: if after one second at least StartServers new -children have not been created, then create enough to pick up the slack. -This is to say that the code tries to maintain both the number of children -appropriate for the current load on the server, and respect your wishes -with the StartServers parameter. - -<p>Users of the -<a href="mod/mod_status.html">status module</a> -will notice that the server statistics -are <b>not</b> set to zero when a <code>USR1</code> is sent. The code -was written to both minimize the time in which the server is unable to serve -new requests (they will be queued up by the operating system, so they're -not lost in any event) and to respect your tuning parameters. In order -to do this it has to keep the <i>scoreboard</i> used to keep track -of all children across generations. - -<p>The status module will also use a <code>G</code> to indicate those -children which are still serving requests started before the graceful -restart was given. - -<p>At present there is no way for a log rotation script using -<code>USR1</code> to know for certain that all children writing the -pre-restart log have finished. We suggest that you use a suitable delay -after sending the <code>USR1</code> signal before you do anything with the -old log. For example if most of your hits take less than 10 minutes to -complete for users on low bandwidth links then you could wait 15 minutes -before doing anything with the old log. - -<h3>Appendix: signals and race conditions</h3> - -<p>Prior to Apache 1.2b9 there were several <i>race conditions</i> -involving the restart and die signals (a simple description of race -condition is: a time-sensitive problem, as in if something happens at just -the wrong time it won't behave as expected). For those architectures that -have the "right" feature set we have eliminated as many as we can. -But it should be noted that there still do exist race conditions on -certain architectures. - -<p>Architectures that use an on disk <a -href="mod/core.html#scoreboardfile">ScoreBoardFile</a> have the potential -to lose track of a child during graceful restart (you'll see an <a -href="mod/core.html#errorlog">ErrorLog</a> message saying something about -a <i>long lost child</i>). The ScoreBoardFile directive explains how -to figure out if your server uses a file, and possibly how to avoid it. -There is also the potential that the scoreboard will be corrupted during -any signalling, but this only has bad effects on graceful restart. - -<p><code>NEXT</code> and <code>MACHTEN</code> have small race conditions -which can cause a restart/die signal to be lost, but should not cause the -server to do anything otherwise problematic. -<!-- they don't have sigaction, or we're not using it -djg --> - -<p>All architectures have a small race condition in each child involving -the second and subsequent requests on a persistent HTTP connection -(KeepAlive). It may exit after reading the request line but before -reading any of the request headers. There is a fix that was discovered -too late to make 1.2. In theory this isn't an issue because the KeepAlive -client has to expect these events because of network latencies and -server timeouts. In practice it doesn't seem to affect anything either --- in a test case the server was restarted twenty times per second and -clients successfully browsed the site without getting broken images or -empty documents. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/suexec.html b/docs/manual/suexec.html deleted file mode 100644 index c1207ac01a..0000000000 --- a/docs/manual/suexec.html +++ /dev/null @@ -1,20 +0,0 @@ -<html><head> -<title>Apache SetUserID Support</title> -</head><body> - -<!--#include virtual="header.html" --> -<h1>Apache SetUserID Support</h1> - -<hr> - -<h2>What is SUExec?</h2> - -<h2>Enabling SUExec Support</h2> - -<h2>When SUExec Is Used</h2> - - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/suexec.html.en b/docs/manual/suexec.html.en deleted file mode 100644 index c1207ac01a..0000000000 --- a/docs/manual/suexec.html.en +++ /dev/null @@ -1,20 +0,0 @@ -<html><head> -<title>Apache SetUserID Support</title> -</head><body> - -<!--#include virtual="header.html" --> -<h1>Apache SetUserID Support</h1> - -<hr> - -<h2>What is SUExec?</h2> - -<h2>Enabling SUExec Support</h2> - -<h2>When SUExec Is Used</h2> - - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/vhosts/details.html b/docs/manual/vhosts/details.html deleted file mode 100644 index 0e992170c3..0000000000 --- a/docs/manual/vhosts/details.html +++ /dev/null @@ -1,367 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<html><head> -<title>An In-Depth Discussion of Virtual Host Matching</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">An In-Depth Discussion of Virtual Host Matching</h1> - -<p>The virtual host code was completely rewritten in <B>Apache 1.3</B>. -This document attempts to explain exactly what Apache does when -deciding what virtual host to serve a hit from. With the help of the -new <A HREF="../mod/core.html#namevirtualhost"><SAMP>NameVirtualHost</SAMP></A> -directive virtual host configuration should be a lot easier and safer -than with versions prior to 1.3. - -<p>If you just want to <cite>make it work</cite> without understanding -how, here are <a href="examples.html">some examples</a>. - -<h3>Config File Parsing</h3> - -<p>There is a <EM>main_server</EM> which consists of all -the definitions appearing outside of <CODE><VirtualHost></CODE> sections. -There are virtual servers, called <EM>vhosts</EM>, which are defined by -<A HREF="../mod/core.html#virtualhost"><SAMP><VirtualHost></SAMP></A> -sections. - -<p>The directives -<A HREF="../mod/core.html#port"><SAMP>Port</SAMP></A>, -<A HREF="../mod/core.html#servername"><SAMP>ServerName</SAMP></A>, -<A HREF="../mod/core.html#serverpath"><SAMP>ServerPath</SAMP></A>, -and -<A HREF="../mod/core.html#serveralias"><SAMP>ServerAlias</SAMP></A> -can appear anywhere within the definition of -a server. However, each appearance overrides the previous appearance -(within that server). - -<p>The default value of the <code>Port</code> field for main_server -is 80. The main_server has no default <code>ServerPath</code>, or -<code>ServerAlias</code>. The default <code>ServerName</code> is -deduced from the servers IP address. - -<p>The main_server Port directive has two functions due to legacy -compatibility with NCSA configuration files. One function is -to determine the default network port Apache will bind to. This -default is overridden by the existence of any -<A HREF="../mod/core.html#listen"><code>Listen</code></A> directives. -The second function is to specify the port number which is used -in absolute URIs during redirects. - -<p>Unlike the main_server, vhost ports <em>do not</em> affect what -ports Apache listens for connections on. - -<p>Each address appearing in the <code>VirtualHost</code> directive -can have an optional port. If the port is unspecified it defaults to -the value of the main_server's most recent <code>Port</code> statement. -The special port <SAMP>*</SAMP> indicates a wildcard that matches any port. -Collectively the entire set of addresses (including multiple -<SAMP>A</SAMP> record -results from DNS lookups) are called the vhost's <EM>address set</EM>. - -<P>Unless a <A HREF="../mod/core.html#namevirtualhost">NameVirtualHost</A> -directive is used for a specific IP address the first vhost with -that address is treated as an IP-based vhost. - -<P>If name-based vhosts should be used a <code>NameVirtualHost</code> -directive <em>must</em> appear with the IP address set to be used for the -name-based vhosts. In other words, you must specify the IP address that -holds the hostname aliases (CNAMEs) for your name-based vhosts via a -<code>NameVirtualHost</code> directive in your configuration file. - -<P>Multiple <code>NameVirtualHost</code> directives can be used each -with a set of <code>VirtualHost</code> directives. - -<P>The ordering of <code>NameVirtualHost</code> and -<code>VirtualHost</code> directives is not important which makes the -following two examples identical (only the order of the -<code>VirtualHost</code> directives for <em>one</em> address set -is important, see below): - -<pre> - | - NameVirtualHost 111.22.33.44 | <VirtualHost 111.22.33.44> - <VirtualHost 111.22.33.44> | # server A - # server A | </VirtualHost> - ... | <VirtualHost 111.22.33.55> - </VirtualHost> | # server C - <VirtualHost 111.22.33.44> | ... - # server B | </VirtualHost> - ... | <VirtualHost 111.22.33.44> - </VirtualHost> | # server B - | ... - NameVirtualHost 111.22.33.55 | </VirtualHost> - <VirtualHost 111.22.33.55> | <VirtualHost 111.22.33.55> - # server C | # server D - ... | ... - </VirtualHost> | </VirtualHost> - <VirtualHost 111.22.33.55> | - # server D | NameVirtualHost 111.22.33.44 - ... | NameVirtualHost 111.22.33.55 - </VirtualHost> | - | -</pre> - -<p>(To aid the readability of your configuration you should prefer the -left variant.) - -<p> After parsing the <code>VirtualHost</code> directive, the vhost server -is given a default <code>Port</code> equal to the port assigned to the -first name in its <code>VirtualHost</code> directive. - -<p>The complete list of names in the <code>VirtualHost</code> directive -are treated just like a <code>ServerAlias</code> (but are not overridden by any -<code>ServerAlias</code> statement) if all names resolve to the same address set. -Note that subsequent <code>Port</code> statements for this vhost will not affect -the ports assigned in the address set. - -<p>During initialization a list for each IP address -is generated an inserted into an hash table. If the IP address is -used in a <code>NameVirtualHost</code> directive the list contains -all name-based vhosts for the given IP address. If there are no -vhosts defined for that address the <code>NameVirtualHost</code> directive -is ignored and an error is logged. For an IP-based vhost the list in the -hash table is empty. - -<p>Due to a fast hashing function the overhead of hashing an IP address -during a request is minimal and almost not existent. Additionally -the table is optimized for IP addresses which vary in the last octet. - -<p>For every vhost various default values are set. In particular: - -<ol> -<li>If a vhost has no - <A HREF="../mod/core.html#serveradmin"><code>ServerAdmin</code></A>, - <A HREF="../mod/core.html#resourceconfig"><code>ResourceConfig</code></A>, - <A HREF="../mod/core.html#accessconfig"><code>AccessConfig</code></A>, - <A HREF="../mod/core.html#timeout"><code>Timeout</code></A>, - <A HREF="../mod/core.html#keepalivetimeout"><code>KeepAliveTimeout</code></A>, - <A HREF="../mod/core.html#keepalive"><code>KeepAlive</code></A>, - <A HREF="../mod/core.html#maxkeepaliverequests"><code>MaxKeepAliveRequests</code></A>, - or - <A HREF="../mod/core.html#sendbuffersize"><code>SendBufferSize</code></A> - directive then the respective value is - inherited from the main_server. (That is, inherited from whatever - the final setting of that value is in the main_server.) - -<li>The "lookup defaults" that define the default directory - permissions - for a vhost are merged with those of the main_server. This includes - any per-directory configuration information for any module. - -<li>The per-server configs for each module from the main_server are - merged into the vhost server. -</ol> - -Essentially, the main_server is treated as "defaults" or a -"base" on which to build each vhost. -But the positioning of these main_server -definitions in the config file is largely irrelevant -- the entire -config of the main_server has been parsed when this final merging occurs. -So even if a main_server definition appears after a vhost definition -it might affect the vhost definition. - -<p> If the main_server has no <code>ServerName</code> at this point, -then the hostname of the machine that httpd is running on is used -instead. We will call the <EM>main_server address set</EM> those IP -addresses returned by a DNS lookup on the <code>ServerName</code> of -the main_server. - -<p> For any undefined <code>ServerName</code> fields, a name-based vhost -defaults to the address given first in the <code>VirtualHost</code> -statement defining the vhost. - -<P>Any vhost that includes the magic <SAMP>_default_</SAMP> wildcard -is given the same <code>ServerName</code> as the main_server. - - -<h3>Virtual Host Matching</h3> - -<p>The server determines which vhost to use for a request as follows: - -<h4>Hash table lookup</h4> - -<p>When the connection is first made by a client, the IP address to -which the client connected is looked up in the internal IP hash table. - -<P>If the lookup fails (the IP address wasn't found) the request is -served from the <samp>_default_</samp> vhost if there is such a vhost -for the port to which the client sent the request. If there is no -matching <samp>_default_</samp> vhost the request is served from the -main_server. - -<P>If the lookup succeeded (a corresponding list for the IP address was -found) the next step is to decide if we have to deal with an IP-based -or a name-base vhost. - -<h4>IP-based vhost</h4> - -<P>If the entry we found has an empty name list then we have found an -IP-based vhost, no further actions are performed and the request is -served from that vhost. - -<h4>Name-based vhost</h4> - -<p>If the entry corresponds to a name-based vhost the name list contains -one or more vhost structures. This list contains the vhosts in the same -order as the <code>VirtualHost</code> directives appear in the config -file. - -<p>The first vhost on this list (the first vhost that appears after the -corresponding <code>NameVirtualHost</code> directive in the config file) -has the highest priority and catches any request to an unknown -server name or a request without a <code>Host:</code> header. - -<p>If the client provided a <code>Host:</code> header the list is -searched for a matching vhost and the first hit on a <code>ServerName</code> -or <code>ServerAlias</code> is taken and the request is served from -that vhost. A <code>Host:</code> header can contain a port number, but -Apache always matches against the real port to which the client sent -the request. - -<p>If the client submitted a HTTP/1.0 request without <code>Host:</code> -header we don't know to what server the client tried to connect and -any existing <code>ServerPath</code> is matched against the URI -from the request. The first matching path on the list is used and the -request is served from that vhost. - -<p>If no matching vhost could be found the request is served from the -first vhost with a matching port number that is on the list for the IP -to which the client connected (as already mentioned before). - -<h4>Persistent connections</h4> -The IP lookup described above is only done <em>once</em> for a particular -TCP/IP session while the name lookup is done on <em>every</em> request -during a KeepAlive/persistent connection. In other words a client may -request pages from different name-based vhosts during a single -persistent connection. - - -<h4>Absolute URI</h4> - -<p>If the URI from the request is an absolute URI, and its hostname and -port match the main server or one of the configured virtual hosts -<em>and</em> match the address and port to which the client sent the request, -then the scheme/hostname/port prefix is stripped off and the remaining -relative URI is served by the corresponding main server or virtual host. -If it does not match, then the URI remains untouched and the request is -taken to be a proxy request. - - -<h3>Observations</h3> - -<ul> - -<li>A name-based vhost can never interfere with an IP-base vhost and - vice versa. IP-based vhosts can only be reached through an IP address - of its own address set and never through any other address. - The same applies to name-based vhosts, they can only be reached - through an IP address of the corresponding address set which must - be defined with a <code>NameVirtualHost</code> directive. - <p> - -<li><code>ServerAlias</code> and <code>ServerPath</code> checks are never - performed for an IP-based vhost. - <p> - -<li>The order of name-/IP-based, the <samp>_default_</samp> - vhost and the <code>NameVirtualHost</code> directive within the config - file is not important. Only the ordering - of name-based vhosts for a specific address set is significant. The one - name-based vhosts that comes first in the configuration file has - the highest priority for its corresponding address set. - <p> - -<li>For security reasons the port number given in a <code>Host:</code> - header is never used during the matching process. Apache always - uses the real port to which the client sent the request. - <p> - -<li>If a <code>ServerPath</code> directive exists which is a prefix of - another <code>ServerPath</code> directive that appears later in - the configuration file, then the former will always be matched - and the latter will never be matched. (That is assuming that no - Host header was available to disambiguate the two.) - <p> - -<li>If two IP-based vhosts have an address in common, the vhost appearing - first in the config file is always matched. Such a thing might happen - inadvertently. The server will give a warning in the error - logfile when it detects this. - <p> - -<li>A <code>_default_</code> vhost catches a request only if there is no - other vhost with a matching IP address <em>and</em> a matching port - number for the request. The request is only catched if the port number - to which the client sent the request matches the port number of your - <code>_default_</code> vhost which is your standard <code>Port</code> - by default. A wildcard port can be specified (i.e. - <code>_default_:*</code>) to catch requests to any available port. - <p> - -<li>The main_server is only used to serve a request if the IP address - and port number to which the client connected is unspecified - and does not match any other vhost (including a <code>_default_</code> - vhost). In other words the main_server only catches a request for an - unspecified address/port combination (unless there is a <code>_default_</code> - vhost which matches that port). - <p> - -<li>A <code>_default_</code> vhost or the main_server is <em>never</em> - matched for a request with an unknown or missing <code>Host:</code> header - if the client connected to an address (and port) which is used - for name-based vhosts, e.g. in a <code>NameVirtualHost</code> directive. - <p> - -<li>You should never specify DNS names in <code>VirtualHost</code> - directives because it will force your server to rely on DNS to boot. - Furthermore it poses a security threat if you do not control the - DNS for all the domains listed. - There's <a href="../dns-caveats.html">more information</a> - available on this and the next two topics. - <p> - -<li><code>ServerName</code> should always be set for each vhost. Otherwise - A DNS lookup is required for each vhost. - <p> - -</ul> - -<h3>Tips</h3> - -<p>In addition to the tips on the <a href="../dns-caveats.html#tips">DNS -Issues</a> page, here are some further tips: - -<ul> - -<li>Place all main_server definitions before any <code>VirtualHost</code> - definitions. (This is to aid the readability of the configuration -- - the post-config merging process makes it non-obvious that definitions - mixed in around virtual hosts might affect all virtual hosts.) - <p> - -<li>Group corresponding <code>NameVirtualHost</code> and - <code>VirtualHost</code> definitions in your configuration to ensure - better readability. - <p> - -<li>Avoid <code>ServerPaths</code> which are prefixes of other - <code>ServerPaths</code>. If you cannot avoid this then you have to - ensure that the longer (more specific) prefix vhost appears earlier in - the configuration file than the shorter (less specific) prefix - (<EM>i.e.</EM>, "ServerPath /abc" should appear after - "ServerPath /abc/def"). - <p> - -</ul> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/vhosts/examples.html b/docs/manual/vhosts/examples.html deleted file mode 100644 index c537f06dbb..0000000000 --- a/docs/manual/vhosts/examples.html +++ /dev/null @@ -1,512 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<html><head> -<title>VirtualHost Examples</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">Virtual Host examples for common setups</h1> - - -<h2>Base configuration</h2> - -<ul> -<li><A HREF="#ip">IP-based vhosts only</A> -<li><A HREF="#name">Name-based vhosts only</A> -<li><A HREF="#mixed">Mixed name-/IP-based vhosts</A> -<li><A HREF="#port">Port-based vhosts</A> -</ul> - -<h2>Additional features</h2> - -<ul> -<li><A HREF="#default">Using <code>_default_</code> vhosts</A> -<li><A HREF="#migrate">Migrating a named-based vhost to an IP-based vhost</A> -<li><A HREF="#serverpath">Using the <code>ServerPath</code> directive</A> -</ul> - -<HR> - -<h3><A NAME="ip">IP-based vhosts only</A></h3> - -<ul> - -<li><b>Setup 1:</b> - The server machine has two IP addresses (<samp>111.22.33.44</samp> - and <samp>111.22.33.55</samp>) - which resolve to the names <samp>server.domain.tld</samp> and - <samp>www.otherdomain.tld</samp> respectively. - The hostname <samp>www.domain.tld</samp> is an alias (CNAME) - for <samp>server.domain.tld</samp> and will represent the - main server. - <p> - <b>Server configuration:</b> - - - <blockquote><pre> - ... - Port 80 - DocumentRoot /www/domain - ServerName www.domain.tld - - <VirtualHost 111.22.33.55> - DocumentRoot /www/otherdomain - ServerName www.otherdomain.tld - ... - </VirtualHost> - </pre> - <samp>www.otherdomain.tld</samp> can only be reached through the - address <samp>111.22.33.55</samp>, while <samp>www.domain.tld</samp> - can only be reached through <samp>111.22.33.44</samp> - (which represents our main server). - </blockquote> - <p> - -<li><b>Setup 2:</b> - Same as setup 1, but we don't want to have a dedicated main server. - <p> - <b>Server configuration:</b> - - <blockquote><pre> - ... - Port 80 - ServerName server.domain.tld - - <VirtualHost 111.22.33.44> - DocumentRoot /www/domain - ServerName www.domain.tld - ... - </VirtualHost> - - <VirtualHost 111.22.33.55> - DocumentRoot /www/otherdomain - ServerName www.otherdomain.tld - ... - </VirtualHost> - </pre> - The main server can never catch a request, because all IP address - of our machine are in use for IP-based virtual hosts - (only <samp>localhost</samp> requests can hit the main server). - </blockquote> - <p> - -<li><b>Setup 3:</b> - The server machine has two IP addresses (<samp>111.22.33.44</samp> - and <samp>111.22.33.55</samp>) - which resolve to the names <samp>server.domain.tld</samp> and - <samp>www-cache.domain.tld</samp> respectively. - The hostname <samp>www.domain.tld</samp> is an alias (CNAME) - for <samp>server.domain.tld</samp> and will represent the - main server. - <samp>www-cache.domain.tld</samp> will become our proxy-cache - listening on port 8080, while the web server itself uses the default - port 80. - <p> - <b>Server configuration:</b> - - <blockquote><pre> - ... - Port 80 - Listen 111.22.33.44:80 - Listen 111.22.33.55:8080 - ServerName server.domain.tld - - <VirtualHost 111.22.33.44:80> - DocumentRoot /www/domain - ServerName www.domain.tld - ... - </VirtualHost> - - <VirtualHost 111.22.33.55:8080> - ServerName www-cache.domain.tld - ... - <Directory proxy:> - order deny,allow - deny from all - allow from 111.22.33 - </Directory> - </VirtualHost> - </pre> - The main server can never catch a request, because all IP addresss - (apart from <samp>localhost</samp>) of our machine are in use for IP-based - virtual hosts. The web server can only be reached on the first address - through port 80 and the proxy only on the second address through port 8080. - </blockquote> -</ul> -<HR> - -<h3><A NAME="name">Name-based vhosts only</A></h3> - -<ul> - -<li><b>Setup 1:</b> - The server machine has one IP address (<samp>111.22.33.44</samp>) - which resolves to the name <samp>server.domain.tld</samp>. - There are two aliases (CNAMEs) <samp>www.domain.tld</samp> and - <samp>www.sub.domain.tld</samp> for the address <samp>111.22.33.44</samp>. - <p> - <b>Server configuration:</b> - - <blockquote><pre> - ... - Port 80 - ServerName server.domain.tld - - NameVirtualHost 111.22.33.44 - - <VirtualHost 111.22.33.44> - DocumentRoot /www/domain - ServerName www.domain.tld - ... - </VirtualHost> - - <VirtualHost 111.22.33.44> - DocumentRoot /www/subdomain - ServerName www.sub.domain.tld - ... - </VirtualHost> - </pre> - Apart from <samp>localhost</samp> there are no unspecified - addresses/ports, therefore the main server only serves - <samp>localhost</samp> requests. Due to the fact - that <samp>www.domain.tld</samp> has the highest priority - it can be seen as the <cite>default</cite> or - <cite>primary</cite> server. - </blockquote> - <p> - -<li><b>Setup 2:</b> - The server machine has two IP addresses (<samp>111.22.33.44</samp> - and <samp>111.22.33.55</samp>) - which resolve to the names <samp>server1.domain.tld</samp> and - <samp>server2.domain.tld</samp> respectively. - The alias <samp>www.domain.tld</samp> should be used for the - main server which should also catch any unspecified addresses. - We want to use a virtual host for the alias - <samp>www.otherdomain.tld</samp> and one virtual host should - catch any request to hostnames of the form - <samp>*.sub.domain.tld</samp> with <samp>www.sub.domain.tld</samp> - as its server name. The address <samp>111.22.33.55</samp> should be - used for the virtual hosts. - <p> - <b>Server configuration:</b> - - <blockquote><pre> - ... - Port 80 - ServerName www.domain.tld - DocumentRoot /www/domain - - NameVirtualHost 111.22.33.55 - - <VirtualHost 111.22.33.55> - DocumentRoot /www/otherdomain - ServerName www.otherdomain.tld - ... - </VirtualHost> - - <VirtualHost 111.22.33.55> - DocumentRoot /www/subdomain - ServerName www.sub.domain.tld - ServerAlias *.sub.domain.tld - ... - </VirtualHost> - </pre> - Any request to an address other than <samp>111.22.33.55</samp> - will be served from the main server. A request to - <samp>111.22.33.55</samp> with an unknown or no <code>Host:</code> - header will be served from <samp>www.otherdomain.tld</samp>. - </blockquote> -</ul> - -<HR> - -<h3><A NAME="mixed">Mixed name-/IP-based vhosts</A></h3> - -<Ul> - -<li><b>Setup:</b> - The server machine has three IP addresses (<samp>111.22.33.44</samp>, - <samp>111.22.33.55</samp> and <samp>111.22.33.66</samp>) - which resolve to the names <samp>server.domain.tld</samp>, - <samp>www.otherdomain1.tld</samp> and <samp>www.otherdomain2.tld</samp> - respectively. - The address <samp>111.22.33.44</samp> should we used for a couple - of name-based vhosts and the other addresses for IP-based vhosts. - <p> - <b>Server configuration:</b> - - <blockquote><pre> - ... - Port 80 - ServerName server.domain.tld - - NameVirtualHost 111.22.33.44 - - <VirtualHost 111.22.33.44> - DocumentRoot /www/domain - ServerName www.domain.tld - ... - </VirtualHost> - - <VirtualHost 111.22.33.44> - DocumentRoot /www/subdomain1 - ServerName www.sub1.domain.tld - ... - </VirtualHost> - - <VirtualHost 111.22.33.44> - DocumentRoot /www/subdomain2 - ServerName www.sub2.domain.tld - ... - </VirtualHost> - - <VirtualHost 111.22.33.55> - DocumentRoot /www/otherdomain1 - ServerName www.otherdomain1.tld - ... - </VirtualHost> - - <VirtualHost 111.22.33.66> - DocumentRoot /www/otherdomain2 - ServerName www.otherdomain2.tld - ... - </VirtualHost> - </pre></blockquote> - -</ul> - -<HR> - -<h3><A NAME="port">Port-based vhosts</A></h3> - -<ul> - -<li><b>Setup:</b> - The server machine has one IP address (<samp>111.22.33.44</samp>) - which resolves to the name <samp>www.domain.tld</samp>. - If we don't have the option to get another address or alias - for our server we can use port-based vhosts if we need - a virtual host with a different configuration. - <p> - <b>Server configuration:</b> - - <blockquote><pre> - ... - Listen 80 - Listen 8080 - ServerName www.domain.tld - DocumentRoot /www/domain - - <VirtualHost 111.22.33.44:8080> - DocumentRoot /www/domain2 - ... - </VirtualHost> - </pre> - A request to <samp>www.domain.tld</samp> on port 80 is served - from the main server and a request to port 8080 is served from - the virtual host. - </blockquote> -</ul> - -<HR> - -<h3><A NAME="default">Using <code>_default_</code> vhosts</A></h3> - -<ul> - -<li><b>Setup 1:</b> - Catching <em>every</em> request to any unspecified IP address and port, - i.e. an address/port combination that is not used for any other - virtual host. - <p> - <b>Server configuration:</b> - - <blockquote><pre> - ... - <VirtualHost _default_:*> - DocumentRoot /www/default - ... - </VirtualHost> - </pre> - Using such a default vhost with a wildcard port effectively - prevents any request going to the main server.<br> - A default vhost never serves a request that was sent to an - address/port that is used for name-based vhosts. If the request - contained an unknown or no <code>Host:</code> header it is - always served from the primary name-based vhost (the - vhost for that address/port appearing first in the configuration - file).<br> - You can use - <A HREF="../mod/mod_alias.html#aliasmatch"><code>AliasMatch</code></A> - or - <A HREF="../mod/mod_rewrite.html#RewriteRule"><code>RewriteRule</code></A> - to rewrite any request to a single information page (or script). - </blockquote> - <p> - -<li><b>Setup 2:</b> - Same as setup 1, but the server listens on several ports and - we want to use a second <code>_default_</code> vhost for port 80. - <p> - <b>Server configuration:</b> - - <blockquote><pre> - ... - <VirtualHost _default_:80> - DocumentRoot /www/default80 - ... - </VirtualHost> - - <VirtualHost _default_:*> - DocumentRoot /www/default - ... - </VirtualHost> - </pre> - The default vhost for port 80 (which <em>must</em> appear before - any default vhost with a wildcard port) catches all requests that - were sent to an unspecified IP address. The main server is - never used to serve a request. - </blockquote> - <p> - -<li><b>Setup 3:</b> - We want to have a default vhost for port 80, but no other default vhosts. - <p> - <b>Server configuration:</b> - - <blockquote><pre> - ... - <VirtualHost _default_:80> - DocumentRoot /www/default - ... - </VirtualHost> - </pre> - A request to an unspecified address on port 80 is served from the - default vhost any other request to an unspecified address and port - is served from the main server. - </blockquote> - -</ul> - -<HR> - -<h3><A NAME="migrate">Migrating a name-based vhost to an IP-based vhost</A></h3> - -<ul> - -<li><b>Setup:</b> - The name-based vhost with the hostname - <samp>www.otherdomain.tld</samp> (from our <a href="#name">name-based</A> - example, setup 2) should get its own IP address. - To avoid problems with name servers or proxies who cached the old - IP address for the name-based vhost we want to provide both variants - during a migration phase.<br> - The solution is easy, because we can simply add the new IP address - (<samp>111.22.33.66</samp>) to the <code>VirtualHost</code> directive. - <p> - <b>Server configuration:</b> - - <blockquote><pre> - ... - Port 80 - ServerName www.domain.tld - DocumentRoot /www/domain - - NameVirtualHost 111.22.33.55 - - <VirtualHost 111.22.33.55 111.22.33.66> - DocumentRoot /www/otherdomain - ServerName www.otherdomain.tld - ... - </VirtualHost> - - <VirtualHost 111.22.33.55> - DocumentRoot /www/subdomain - ServerName www.sub.domain.tld - ServerAlias *.sub.domain.tld - ... - </VirtualHost> - </pre> - The vhost can now be accessed through the new address (as an IP-based - vhost) and through the old address (as a name-based vhost). - </blockquote> - -</ul> - -<HR> - -<h3><A NAME="serverpath">Using the <code>ServerPath</code> directive</A></h3> - -<ul> - -<li><b>Setup:</b> - We have a server with two name-based vhosts. In order to match the correct - virtual host a client must send the correct <code>Host:</code> header. - Old HTTP/1.0 clients do not send such a header and Apache has no clue - what vhost the client tried to reach (and serves the request from - the primary vhost). To provide as much backward compatibility - as possible we create a primary vhost which returns a single page - containing links with an URL prefix to the name-based virtual hosts. - <p> - <b>Server configuration:</b> - - <blockquote><pre> - ... - NameVirtualHost 111.22.33.44 - - <VirtualHost 111.22.33.44> - # primary vhost - DocumentRoot /www/subdomain - RewriteEngine On - RewriteRule ^/.* /www/subdomain/index.html - ... - </VirtualHost> - - <VirtualHost 111.22.33.44> - DocumentRoot /www/subdomain/sub1 - ServerName www.sub1.domain.tld - ServerPath /sub1/ - RewriteEngine On - RewriteRule ^(/sub1/.*) /www/subdomain$1 - ... - </VirtualHost> - - <VirtualHost 111.22.33.44> - DocumentRoot /www/subdomain/sub2 - ServerName www.sub2.domain.tld - ServerPath /sub2/ - RewriteEngine On - RewriteRule ^(/sub2/.*) /www/subdomain$1 - ... - </VirtualHost> - </pre> - Due to the <A HREF="../mod/core.html#serverpath"><code>ServerPath</code></A> - directive a request to the - URL <samp>http://www.sub1.domain.tld/sub1/</samp> is <em>always</em> - served from the sub1-vhost. <br> - A request to the URL <samp>http://www.sub1.domain.tld/</samp> - is only served from the sub1-vhost if the client sent a correct - <code>Host:</code> header. - If no <code>Host:</code> header is sent the client gets the - information page from the primary host.<br> - Please note that there is one oddity: A request to - <samp>http://www.sub2.domain.tld/sub1/</samp> is also served from - the sub1-vhost if the client sent no <code>Host:</code> header. <br> - The <code>RewriteRule</code> directives are used to make sure that - a client which sent a correct <code>Host:</code> header can use - both URL variants, i.e. with or without URL prefix. - </blockquote> - -</ul> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/vhosts/fd-limits.html b/docs/manual/vhosts/fd-limits.html deleted file mode 100644 index 77f4d8254d..0000000000 --- a/docs/manual/vhosts/fd-limits.html +++ /dev/null @@ -1,59 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<html> -<head> -<title>Apache Server Virtual Host Support</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">File Descriptor Limits</h1> - -<P> -When using a large number of Virtual Hosts, Apache may run out of available -file descriptors (sometimes called <cite>file handles</cite> if each Virtual -Host specifies different log files. -The total number of file descriptors used by Apache is one for each distinct -error log file, one for every other log file directive, plus 10-20 for -internal use. Unix operating systems limit the number of file descriptors that -may be used by a process; the limit is typically 64, and may usually be -increased up to a large hard-limit. -<p> -Although Apache attempts to increase the limit as required, this -may not work if: -<ol> -<li>Your system does not provide the setrlimit() system call. -<li>The setrlimit(RLIMIT_NOFILE) call does not function on your system - (such as Solaris 2.3) -<li>The number of file descriptors required exceeds the hard limit. -<li>Your system imposes other limits on file descriptors, such as a limit -on stdio streams only using file descriptors below 256. (Solaris 2) -</ol> - -In the event of problems you can: -<ul> -<li>Reduce the number of log files; don't specify log files in the VirtualHost -sections, but only log to the main log files. -<li>If you system falls into 1 or 2 (above), then increase the file descriptor -limit before starting Apache, using a script like -<blockquote><code> -#!/bin/sh <br> -ulimit -S -n 100 <br> -exec httpd</code></blockquote> -</ul> -<P> -Please see the -<A HREF="../misc/descriptors.html">Descriptors and Apache</A> -document containing further details about file descriptor problems and how -they can be solved on your operating system. -</P> - -<!--#include virtual="footer.html" --> -</body></html> - diff --git a/docs/manual/vhosts/fd-limits.html.en b/docs/manual/vhosts/fd-limits.html.en deleted file mode 100644 index 77f4d8254d..0000000000 --- a/docs/manual/vhosts/fd-limits.html.en +++ /dev/null @@ -1,59 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<html> -<head> -<title>Apache Server Virtual Host Support</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">File Descriptor Limits</h1> - -<P> -When using a large number of Virtual Hosts, Apache may run out of available -file descriptors (sometimes called <cite>file handles</cite> if each Virtual -Host specifies different log files. -The total number of file descriptors used by Apache is one for each distinct -error log file, one for every other log file directive, plus 10-20 for -internal use. Unix operating systems limit the number of file descriptors that -may be used by a process; the limit is typically 64, and may usually be -increased up to a large hard-limit. -<p> -Although Apache attempts to increase the limit as required, this -may not work if: -<ol> -<li>Your system does not provide the setrlimit() system call. -<li>The setrlimit(RLIMIT_NOFILE) call does not function on your system - (such as Solaris 2.3) -<li>The number of file descriptors required exceeds the hard limit. -<li>Your system imposes other limits on file descriptors, such as a limit -on stdio streams only using file descriptors below 256. (Solaris 2) -</ol> - -In the event of problems you can: -<ul> -<li>Reduce the number of log files; don't specify log files in the VirtualHost -sections, but only log to the main log files. -<li>If you system falls into 1 or 2 (above), then increase the file descriptor -limit before starting Apache, using a script like -<blockquote><code> -#!/bin/sh <br> -ulimit -S -n 100 <br> -exec httpd</code></blockquote> -</ul> -<P> -Please see the -<A HREF="../misc/descriptors.html">Descriptors and Apache</A> -document containing further details about file descriptor problems and how -they can be solved on your operating system. -</P> - -<!--#include virtual="footer.html" --> -</body></html> - diff --git a/docs/manual/vhosts/index.html b/docs/manual/vhosts/index.html deleted file mode 100644 index 0b1a22678e..0000000000 --- a/docs/manual/vhosts/index.html +++ /dev/null @@ -1,58 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache Virtual Host documentation</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 Virtual Host documentation</h1> - -<p>The term <cite>Virtual Host</cite> refers to the practice of maintaining -more than one server on one machine, as differentiated by their apparent -hostname. For example, it is often desirable for companies sharing a -web server to have their own domains, with web servers accessible as -<samp>www.company1.com</samp> and <samp>www.company2.com</samp>, -without requiring the user to know any extra path information.</p> - -<p>Apache was one of the first servers to support IP-based -virtual hosts right out of the box. Versions 1.1 and later of -Apache support both, IP-based and name-based virtual hosts (vhosts). -The latter variant of virtual hosts is sometimes also called host-based or -non-IP virtual hosts.</P> - -<P>Below is a list of documentation pages which explain all details -of virtual host support in Apache version 1.3 and later.</P> - -<HR> - -<H2>Virtual Host Support</H2> - -<UL> -<LI><A HREF="ip-based.html">IP-based Virtual Hosts</A> -<LI><A HREF="name-based.html">Name-based Virtual Hosts</A> -<LI><A HREF="examples.html">Virtual Host examples for common setups</A> -<LI><A HREF="details.html">In-Depth Discussion of Virtual Host Matching</A> -<LI><A HREF="fd-limits.html">File Descriptor Limits</A> -</UL> - -<H2>Configuration directives</H2> - -<UL> -<LI><A HREF="../mod/core.html#virtualhost"><VirtualHost></A> -<LI><A HREF="../mod/core.html#namevirtualhost">NameVirtualHost</A> -<LI><A HREF="../mod/core.html#servername">ServerName</A> -<LI><A HREF="../mod/core.html#serveralias">ServerAlias</A> -<LI><A HREF="../mod/core.html#serverpath">ServerPath</A> -</UL> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/vhosts/index.html.en b/docs/manual/vhosts/index.html.en deleted file mode 100644 index 0b1a22678e..0000000000 --- a/docs/manual/vhosts/index.html.en +++ /dev/null @@ -1,58 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache Virtual Host documentation</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 Virtual Host documentation</h1> - -<p>The term <cite>Virtual Host</cite> refers to the practice of maintaining -more than one server on one machine, as differentiated by their apparent -hostname. For example, it is often desirable for companies sharing a -web server to have their own domains, with web servers accessible as -<samp>www.company1.com</samp> and <samp>www.company2.com</samp>, -without requiring the user to know any extra path information.</p> - -<p>Apache was one of the first servers to support IP-based -virtual hosts right out of the box. Versions 1.1 and later of -Apache support both, IP-based and name-based virtual hosts (vhosts). -The latter variant of virtual hosts is sometimes also called host-based or -non-IP virtual hosts.</P> - -<P>Below is a list of documentation pages which explain all details -of virtual host support in Apache version 1.3 and later.</P> - -<HR> - -<H2>Virtual Host Support</H2> - -<UL> -<LI><A HREF="ip-based.html">IP-based Virtual Hosts</A> -<LI><A HREF="name-based.html">Name-based Virtual Hosts</A> -<LI><A HREF="examples.html">Virtual Host examples for common setups</A> -<LI><A HREF="details.html">In-Depth Discussion of Virtual Host Matching</A> -<LI><A HREF="fd-limits.html">File Descriptor Limits</A> -</UL> - -<H2>Configuration directives</H2> - -<UL> -<LI><A HREF="../mod/core.html#virtualhost"><VirtualHost></A> -<LI><A HREF="../mod/core.html#namevirtualhost">NameVirtualHost</A> -<LI><A HREF="../mod/core.html#servername">ServerName</A> -<LI><A HREF="../mod/core.html#serveralias">ServerAlias</A> -<LI><A HREF="../mod/core.html#serverpath">ServerPath</A> -</UL> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/vhosts/ip-based.html b/docs/manual/vhosts/ip-based.html deleted file mode 100644 index e1cc14ff05..0000000000 --- a/docs/manual/vhosts/ip-based.html +++ /dev/null @@ -1,129 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<html> -<head> -<title>Apache IP-based Virtual Host Support</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 IP-based Virtual Host Support</h1> - -<strong>See also:</strong> -<a href="name-based.html">Name-based Virtual Hosts Support</a> - -<HR> - -<h2>System requirements</h2> -As the term <cite>IP-based</cite> indicates, the server <strong>must have a -different IP address for each IP-based virtual host</strong>. -This can be achieved by the machine having several physical network connections, -or by use of virtual interfaces which are supported by most modern -operating systems (see system documentation for details). - -<h2>How to set up Apache</h2> -There are two ways of configuring apache to support multiple hosts. -Either by running a separate httpd daemon for each hostname, or by running a -single daemon which supports all the virtual hosts. -<p> -Use multiple daemons when: -<ul> -<li>The different virtual hosts need very different httpd configurations, such - as different values for: <A HREF="../mod/core.html#servertype">ServerType</A>, - <A HREF="../mod/core.html#user">User</A>, - <A HREF="../mod/core.html#group">Group</A>, - <A HREF="../mod/mod_mime.html#typesconfig">TypesConfig</A> or - <A HREF="../mod/core.html#serverroot">ServerRoot</A>. -<li>The machine does not process a very high request rate. -</ul> -Use a single daemon when: -<ul> -<li>Sharing of the httpd configuration between virtual hosts is acceptable. -<li>The machine services a large number of requests, and so the performance - loss in running separate daemons may be significant. -</ul> - -<h2>Setting up multiple daemons</h2> -Create a separate httpd installation for each virtual host. -For each installation, use the -<A HREF="../mod/core.html#listen">Listen</A> directive in the configuration -file to select which IP address (or virtual host) that daemon services. -e.g. -<pre> - Listen www.smallco.com:80 -</pre> -It is recommended that you use an IP address instead of a hostname -(see <A HREF="../dns-caveats.html">DNS page</A>). - -<h2>Setting up a single daemon with virtual hosts</h2> -For this case, a single httpd will service requests for the main server -and all the virtual hosts. -The <A HREF="../mod/core.html#virtualhost">VirtualHost</A> directive in the - configuration file is used to set the values of -<A HREF="../mod/core.html#serveradmin">ServerAdmin</A>, -<A HREF="../mod/core.html#servername">ServerName</A>, -<A HREF="../mod/core.html#documentroot">DocumentRoot</A>, -<A HREF="../mod/core.html#errorlog">ErrorLog</A> and -<A HREF="../mod/mod_log_config.html#transferlog">TransferLog</A> or -<A HREF="../mod/mod_log_config.html#customlog">CustomLog</A> -configuration directives to different values for each virtual host. -e.g. -<pre> - <VirtualHost www.smallco.com> - ServerAdmin webmaster@mail.smallco.com - DocumentRoot /groups/smallco/www - ServerName www.smallco.com - ErrorLog /groups/smallco/logs/error_log - TransferLog /groups/smallco/logs/access_log - </VirtualHost> - - <VirtualHost www.baygroup.org> - ServerAdmin webmaster@mail.baygroup.org - DocumentRoot /groups/baygroup/www - ServerName www.baygroup.org - ErrorLog /groups/baygroup/logs/error_log - TransferLog /groups/baygroup/logs/access_log - </VirtualHost> -</pre> - -It is recommended that you use an IP address instead of a hostname -(see <A HREF="../dns-caveats.html">DNS page</A>). - -<P> - -Almost <strong>any</strong> configuration directive can be put -in the VirtualHost directive, with the exception of -<A HREF="../mod/core.html#servertype">ServerType</A>, -<A HREF="../mod/core.html#startservers">StartServers</A>, -<A HREF="../mod/core.html#maxspareservers">MaxSpareServers</A>, -<A HREF="../mod/core.html#minspareservers">MinSpareServers</A>, -<A HREF="../mod/core.html#maxrequestsperchild">MaxRequestsPerChild</A>, -<A HREF="../mod/core.html#bindaddress">BindAddress</A>, -<A HREF="../mod/core.html#listen">Listen</A>, -<A HREF="../mod/core.html#pidfile">PidFile</A>, -<A HREF="../mod/mod_mime.html#typesconfig">TypesConfig</A>, -<A HREF="../mod/core.html#serverroot">ServerRoot</A> and -<A HREF="../mod/core.html#namevirtualhost">NameVirtualHost</A>. -<P> -<A HREF="../mod/core.html#user">User</A> and -<A HREF="../mod/core.html#group">Group</A> maybe used inside a VirtualHost -directive if the <A HREF="../suexec.html">suEXEC wrapper</A> is used. -<P> - -<EM>SECURITY:</EM> When specifying where to write log files, be aware -of some security risks which are present if anyone other than the -user that starts Apache has write access to the directory where they -are written. See the <A HREF="../misc/security_tips.html">security -tips</A> document for details. -</P> - -<!--#include virtual="footer.html" --> -</body> -</html> - diff --git a/docs/manual/vhosts/mass.html b/docs/manual/vhosts/mass.html deleted file mode 100644 index 4ecd952e2d..0000000000 --- a/docs/manual/vhosts/mass.html +++ /dev/null @@ -1,330 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML><HEAD> -<TITLE>Dynamically configured mass virtual hosting</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">Dynamically configured mass virtual hosting</H1> - -<P>This document describes how to efficiently serve an arbitrary number -of virtual hosts with Apache 1.3. Some familiarity with -<A HREF="../mod/mod_rewrite.html"><CODE>mod_rewrite</CODE></A> is -useful.</P> - -<!-- - -Written by Tony Finch (fanf@demon.net) (dot@dotat.at). - -Some examples were derived from Ralf S. Engleschall's document - http://www.engelschall.com/pw/apache/rewriteguide/ - -Some suggestions were made by Brian Behlendorf. - ---> - -<H2><A NAME="contents">Contents:</A></H2> - -<UL> -<LI><A HREF="#motivation">Motivation</A> -<LI><A HREF="#overview">Overview of the technique</A> -<LI><A HREF="#simple">Simple name-based dynamic virtual hosts</A> -<LI><A HREF="#homepages">A virtually hosted homepages system</A> -<LI><A HREF="#xtra-conf">Using a separate virtual host configuration file</A> -<LI><A HREF="#combinations">Using more than one virtual hosting system on the same server</A> -</UL> - -<HR><H2><A NAME="motivation">Motivation</A></H2> - -<P>The techniques described here are of interest if your -<CODE>httpd.conf</CODE> contains hundreds of -<CODE><VirtualHost></CODE> sections that are substantially the -same, for example: -<PRE> -NameVirtualHost 111.22.33.44 -<VirtualHost 111.22.33.44> - ServerName www.customer-1.com - DocumentRoot /www/hosts/www.customer-1.com/docs - ScriptAlias /cgi-bin/ /www/hosts/www.customer-1.com/cgi-bin -</VirtualHost> -<VirtualHost 111.22.33.44> - ServerName www.customer-2.com - DocumentRoot /www/hosts/www.customer-2.com/docs - ScriptAlias /cgi-bin/ /www/hosts/www.customer-2.com/cgi-bin -</VirtualHost> -# blah blah blah -<VirtualHost 111.22.33.44> - ServerName www.customer-N.com - DocumentRoot /www/hosts/www.customer-N.com/docs - ScriptAlias /cgi-bin/ /www/hosts/www.customer-N.com/cgi-bin -</VirtualHost> -</PRE> -</P> - -<P>The basic idea is to replace all of the static -<CODE><VirtualHost></CODE> configuration with a mechanism that -works it out dynamically. This has a number of advantages: -<OL> - <LI>Your configuration file is smaller so Apache starts faster and - uses less memory. - <LI>Adding virtual hosts is simply a matter of creating the - appropriate directories in the filesystem and entries in the DNS - - you don't need to reconfigure or restart Apache. -</OL> -</P> - -<P>The main disadvantage is that you cannot have a different log file -for each server; however if you have very many virtual hosts then -doing this is dubious anyway because it eats file descriptors. It's -better to log to a pipe or a fifo and arrange for the process at the -other end to distribute the logs (and perhaps accumulate statistics, -etc.). A <CODE>LogFormat</CODE> directive that includes -<CODE>%v</CODE> for the virtual host makes it easy to do this.</P> - - -<HR><H2><A NAME="overview">Overview of the technique</A></H2> - -<P>All of the dynamic virtual hosts will either be configured as part -of the main server configuration, or within a -<CODE><VirtualHost></CODE> section. For a simple (very uniform) -setup, <CODE><VirtualHost></CODE> sections aren't needed at all.</P> - -<P>A couple of things need to be `faked' to make the dynamic virtual -host look like a normal one. The most important is the server name -(configured with <CODE>ServerName</CODE> and available to CGIs via the -<CODE>SERVER_NAME</CODE> environment variable). The way it is -determined is controlled by the <CODE>UseCanonicalName</CODE> -directive: with <CODE>UseCanonicalName off</CODE> the server name -comes from the contents of the <CODE>Host:</CODE> header in the -request. If there is no <CODE>Host:</CODE> header then the value -configured with <CODE>ServerName</CODE> is used instead.</P> - -<P>The other one is the document root (configured with -<CODE>DocumentRoot</CODE> and available to CGIs via the -<CODE>DOCUMENT_ROOT</CODE> environment variable). This is used by the -core module when mapping URIs to filenames, but in the context of -dynamic virtual hosting its value only matters if any CGIs or SSI -documents make use of the <CODE>DOCUMENT_ROOT</CODE> environment -variable. This is an Apache extension to the CGI specification and as -such shouldn't really be relied upon, especially because this -technique breaks it: there isn't currently a way of setting -<CODE>DOCUMENT_ROOT</CODE> dynamically.</P> - -<P>The meat of the mechanism works via Apache's URI-to-filename -translation API phase. This is used by a number of modules: -<A HREF="../mod/mod_rewrite.html"><CODE>mod_rewrite</CODE></A>, -<A HREF="../mod/mod_alias.html"><CODE>mod_alias</CODE></A>, -<A HREF="../mod/mod_userdir.html"><CODE>mod_userdir</CODE></A>, -and <A HREF="../mod/core.html">the core module</A>. -In the default configuration these modules are called in that order -and given a chance to say that they know what the filename is. Most of -these modules do it in a fairly simple fashion (e.g. the core module -concatenates the document root and the URI) except for -<CODE>mod_rewrite</CODE>, which provides enough functionality to do -all sorts of sick and twisted things (like dynamic virtual hosting). -Note that because of the order in which the modules are called, using -a <CODE>mod_rewrite</CODE> configuration that matches any URI means -that the other modules (particularly <CODE>mod_alias</CODE>) will -cease to function. The examples below show how to deal with this.</P> - -<P><STRONG>The dynamic virtual hosting idea is very simple: use the -server name as well as the URI to determine the corresponding -filename.</STRONG></P> - - -<HR><H2><A NAME="simple">Simple name-based dynamic virtual hosts</A></H2> - -<P>This extract from <CODE>httpd.conf</CODE> implements the virtual -host arrangement outlined in the <A HREF="#motivation">Motivation</A> -section above, but in a generic fashion.</P> - -<P>The first half shows some other configuration options that are -needed to make the <CODE>mod_rewrite</CODE> part work as expected; the -second half uses <CODE>mod_rewrite</CODE> to do the actual work. Some -care is taken to do a per-dynamic-virtual-host equivalent of -<CODE>ScriptAlias</CODE>.</P> - -<PRE> -# dynamic ServerName -UseCanonicalName Off - -# splittable logs -LogFormat "%v %h %l %u %t \"%r\" %s %b" vcommon -CustomLog logs/access_log vcommon - -<Directory /www/hosts> - # ExecCGI is needed here because we can't force - # CGI execution in the way that ScriptAlias does - Options FollowSymLinks ExecCGI -</Directory> - -# now for the hard bit - -RewriteEngine On - -# a ServerName derived from a Host: header may be any case at all -RewriteMap lowercase int:tolower - -## deal with normal documents first: -# allow Alias /icons/ to work - repeat for other aliases -RewriteCond %{REQUEST_URI} !^/icons/ -# allow CGIs to work -RewriteCond %{REQUEST_URI} !^/cgi-bin/ -# do the magic -RewriteRule ^/(.*)$ /www/hosts/${lowercase:%{SERVER_NAME}}/docs/$1 - -## and now deal with CGIs - we have to force a MIME type -RewriteCond %{REQUEST_URI} ^/cgi-bin/ -RewriteRule ^/(.*)$ /www/hosts/${lowercase:%{SERVER_NAME}}/cgi-bin/$1 [T=application/x-httpd-cgi] - -# that's it! -</PRE> - - -<HR><H2><A NAME="homepages">A virtually hosted homepages system</A></H2> - -<P>This is an adjustment of the above system tailored for an ISP's -homepages server. Using slightly more complicated rewriting rules we -can select substrings of the server name to use in the filename so -that e.g. the documents for <SAMP>www.user.isp.com</SAMP> are found in -<CODE>/home/user/</CODE>. It uses a single <CODE>cgi-bin</CODE> -directory instead of one per virtual host.</P> - -<PRE> -RewriteEngine on - -RewriteMap lowercase int:tolower - -# allow CGIs to work -RewriteCond %{REQUEST_URI} !^/cgi-bin/ - -# check the hostname is right so that the RewriteRule works -RewriteCond ${lowercase:%{HTTP_HOST}} ^www\.[a-z-]+\.isp\.com$ - -# concatenate the virtual host name onto the start of the URI -# the [C] means do the next rewrite on the result of this one -RewriteRule ^(.+) ${lowercase:%{HTTP_HOST}}$1 [C] - -# now create the real file name -RewriteRule ^www\.([a-z-]+)\.isp\.com/(.*) /home/$1/$2 - -# define the global CGI directory -ScriptAlias /cgi-bin/ /www/std-cgi/ -</PRE> - - -<HR><H2><A NAME="xtra-conf">Using a separate virtual host configuration file</A></H2> - -<P>This arrangement uses a separate configuration file to specify the -translation from virtual host to document root. This provides more -flexibility but requires more configuration.</P> - -<P>The <CODE>vhost.map</CODE> file contains something like this: -<PRE> -www.customer-1.com /www/customers/1 -www.customer-2.com /www/customers/2 -# ... -www.customer-N.com /www/customers/N -</PRE> -</P> - -<P>The <CODE>http.conf</CODE> contains this: -<PRE> -RewriteEngine on - -RewriteMap lowercase int:tolower - -# define the map file -RewriteMap vhost txt:/www/conf/vhost.map - -# deal with aliases as above -RewriteCond %{REQUEST_URI} !^/icons/ -RewriteCond %{REQUEST_URI} !^/cgi-bin/ -RewriteCond ${lowercase:%{SERVER_NAME}} ^(.+)$ -# this does the file-based remap -RewriteCond ${vhost:%1} ^(/.*)$ -RewriteRule ^/(.*)$ %1/docs/$1 - -RewriteCond %{REQUEST_URI} ^/cgi-bin/ -RewriteCond ${lowercase:%{SERVER_NAME}} ^(.+)$ -RewriteCond ${vhost:%1} ^(/.*)$ -RewriteRule ^/(.*)$ %1/cgi-bin/$1 -</PRE> -</P> - - -<HR><H2><A NAME="combinations">Using more than one virtual hosting system on the same server</A></H2> - -<P>With more complicated setups, you can use Apache's normal -<CODE><VirtualHost></CODE> directives to control the scope of -the various rewrite configurations. For example, you could have one IP -address for homepages customers and another for commercial customers -with the following setup. This can of course be combined with -convential <CODE><VirtualHost></CODE> configuration -sections.</P> - -<PRE> -UseCanonicalName Off - -LogFormat "%v %h %l %u %t \"%r\" %s %b" vcommon -CustomLog logs/access_log vcommon - -<Directory /www/commercial> - Options FollowSymLinks ExecCGI - AllowOverride All -</Directory> - -<Directory /www/homepages> - Options FollowSymLinks - AllowOverride None -</Directory> - -<VirtualHost 111.22.33.44> - ServerName www.commercial.isp.com - - RewriteEngine On - RewriteMap lowercase int:tolower - - RewriteCond %{REQUEST_URI} !^/icons/ - RewriteCond %{REQUEST_URI} !^/cgi-bin/ - RewriteRule ^/(.*)$ /www/commercial/${lowercase:%{SERVER_NAME}}/docs/$1 - - RewriteCond %{REQUEST_URI} ^/cgi-bin/ - RewriteRule ^/(.*)$ /www/commercial/${lowercase:%{SERVER_NAME}}/cgi-bin/$1 [T=application/x-httpd-cgi] -</VirtualHost> - -<VirtualHost 111.22.33.45> - ServerName www.homepages.isp.com - - RewriteEngine on - RewriteMap lowercase int:tolower - - RewriteCond %{REQUEST_URI} !^/cgi-bin/ - - RewriteCond ${lowercase:%{HTTP_HOST}} ^www\.[a-z-]+\.isp\.com$ - RewriteRule ^(.+) ${lowercase:%{HTTP_HOST}}$1 [C] - RewriteRule ^www\.([a-z-]+)\.isp\.com/(.*) /www/homepages/$1/$2 - - ScriptAlias /cgi-bin/ /www/std-cgi/ -</VirtualHost> -</PRE> - - -<HR> - -<H3 ALIGN="CENTER"> - Apache HTTP Server Version 1.3 -</H3> - -<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> -<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> - -</BODY> -</HTML> diff --git a/docs/manual/vhosts/name-based.html b/docs/manual/vhosts/name-based.html deleted file mode 100644 index f26dd5f8ed..0000000000 --- a/docs/manual/vhosts/name-based.html +++ /dev/null @@ -1,141 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<html><head> -<title>Apache name-based Virtual Hosts</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 name-based Virtual Host Support</h1> - -<strong>See Also:</strong> -<a href="ip-based.html">IP-based Virtual Host Support</a> - -<hr> - -<h2>Name-based vs. IP-based virtual hosts</h2> - -<p>While the approach with IP-based virtual hosts works still very well, -it is not the most elegant solution, because a dedicated IP address -is needed for every virtual host and it is hard to implement on some -machines. The <code>HTTP/1.1</code> protocol contains a method for the -server to identify what name it is being addressed as. Apache 1.1 and -later support this approach as well as the traditional -IP-address-per-hostname method.</p> - -<p>The benefits of using the new name-based virtual host support is a -practically unlimited number of servers, ease of configuration and use, and -requires no additional hardware or software. -The main disadvantage is that the client must support this part of the -protocol. The latest versions of most browsers do, but there are still -old browsers in use who do not. This can cause problems, although a possible -solution is addressed below.</p> - -<h2>Using non-IP Virtual Hosts</h2> - -<p>Using the new virtual hosts is quite easy, and superficially looks -like the old method. You simply add to one of the Apache configuration -files (most likely <code>httpd.conf</code> or <code>srm.conf</code>) -code similar to the following:</p> -<pre> - NameVirtualHost 111.22.33.44 - - <VirtualHost 111.22.33.44> - ServerName www.domain.tld - DocumentRoot /web/domain - </VirtualHost> -</pre> - -<p>The notable difference between IP-based and name-based virtual host -configuration is the -<A HREF="../mod/core.html#namevirtualhost"><code>NameVirtualHost</code></A> -directive which specifies any IP address that should be used as a target for -name-based virtual hosts. - -<p>Of course, any additional directives can (and should) be placed -into the <code><VirtualHost></code> section. To make this work, -all that is needed is to make sure that the name -<samp>www.domain.tld</samp> is an alias (CNAME) pointing to the IP address -<samp>111.22.33.44</samp></p> - -<p>Additionally, many servers may wish to be accessible by more than -one name. For example, the example server might want to be accessible -as <code>domain.tld</code>, or <code>www2.domain.tld</code>, assuming -the IP addresses pointed to the same server. In fact, one might want it -so that all addresses at <code>domain.tld</code> were picked up by the -server. This is possible with the -<A HREF="../mod/core.html#serveralias"><code>ServerAlias</code></A> -directive, placed inside the <VirtualHost> section. For -example:</p> - -<pre> - ServerAlias domain.tld *.domain.tld -</pre> - -<p>Note that you can use <code>*</code> and <code>?</code> as wild-card -characters.</p> - -<p>You also might need <code>ServerAlias</code> if you are -serving local users who do not always include the domain name. -For example, if local users are -familiar with typing "www" or "www.foobar" then you will need to add -<code>ServerAlias www www.foobar</code>. It isn't possible for the -server to know what domain the client uses for their name resolution -because the client doesn't provide that information in the request.</p> - -<h2>Compatibility with Older Browsers</h2> - -<p>As mentioned earlier, there are still some clients in use who -do not send the required data for the name-based virtual hosts to work -properly. These clients will always be sent the pages from the -<cite>primary</cite> name-based virtual host (the first virtual host -appearing in the configuration file for a specific IP address).</p> - -<p>There is a possible workaround with the -<A HREF="../mod/core.html#serverpath"><code>ServerPath</code></A> -directive, albeit a slightly cumbersome one:</p> - -<p>Example configuration: - -<pre> - NameVirtualHost 111.22.33.44 - - <VirtualHost 111.22.33.44> - ServerName www.domain.tld - ServerPath /domain - DocumentRoot /web/domain - </VirtualHost> -</pre> - -<p>What does this mean? It means that a request for any URI beginning -with "<samp>/domain</samp>" will be served from the virtual host -<samp>www.domain.tld</samp> This means that the pages can be accessed as -<code>http://www.domain.tld/domain/</code> for all clients, although -clients sending a <samp>Host:</samp> header can also access it as -<code>http://www.domain.tld/</code>.</p> - -<p>In order to make this work, put a link on your primary virtual host's page -to <samp>http://www.domain.tld/domain/</samp> -Then, in the virtual host's pages, be sure to use either purely -relative links (e.g. "<samp>file.html</samp>" or -"<samp>../icons/image.gif</samp>" or links containing the prefacing -<samp>/domain/</samp> -(e.g. "<samp>http://www.domain.tld/domain/misc/file.html</samp>" or -"<samp>/domain/misc/file.html</samp>").</p> - -<p>This requires a bit of -discipline, but adherence to these guidelines will, for the most part, -ensure that your pages will work with all browsers, new and old.</p> - -<p>See also: <A HREF="examples.html#serverpath">ServerPath configuration -example</A></p> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/vhosts/name-based.html.en b/docs/manual/vhosts/name-based.html.en deleted file mode 100644 index f26dd5f8ed..0000000000 --- a/docs/manual/vhosts/name-based.html.en +++ /dev/null @@ -1,141 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<html><head> -<title>Apache name-based Virtual Hosts</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 name-based Virtual Host Support</h1> - -<strong>See Also:</strong> -<a href="ip-based.html">IP-based Virtual Host Support</a> - -<hr> - -<h2>Name-based vs. IP-based virtual hosts</h2> - -<p>While the approach with IP-based virtual hosts works still very well, -it is not the most elegant solution, because a dedicated IP address -is needed for every virtual host and it is hard to implement on some -machines. The <code>HTTP/1.1</code> protocol contains a method for the -server to identify what name it is being addressed as. Apache 1.1 and -later support this approach as well as the traditional -IP-address-per-hostname method.</p> - -<p>The benefits of using the new name-based virtual host support is a -practically unlimited number of servers, ease of configuration and use, and -requires no additional hardware or software. -The main disadvantage is that the client must support this part of the -protocol. The latest versions of most browsers do, but there are still -old browsers in use who do not. This can cause problems, although a possible -solution is addressed below.</p> - -<h2>Using non-IP Virtual Hosts</h2> - -<p>Using the new virtual hosts is quite easy, and superficially looks -like the old method. You simply add to one of the Apache configuration -files (most likely <code>httpd.conf</code> or <code>srm.conf</code>) -code similar to the following:</p> -<pre> - NameVirtualHost 111.22.33.44 - - <VirtualHost 111.22.33.44> - ServerName www.domain.tld - DocumentRoot /web/domain - </VirtualHost> -</pre> - -<p>The notable difference between IP-based and name-based virtual host -configuration is the -<A HREF="../mod/core.html#namevirtualhost"><code>NameVirtualHost</code></A> -directive which specifies any IP address that should be used as a target for -name-based virtual hosts. - -<p>Of course, any additional directives can (and should) be placed -into the <code><VirtualHost></code> section. To make this work, -all that is needed is to make sure that the name -<samp>www.domain.tld</samp> is an alias (CNAME) pointing to the IP address -<samp>111.22.33.44</samp></p> - -<p>Additionally, many servers may wish to be accessible by more than -one name. For example, the example server might want to be accessible -as <code>domain.tld</code>, or <code>www2.domain.tld</code>, assuming -the IP addresses pointed to the same server. In fact, one might want it -so that all addresses at <code>domain.tld</code> were picked up by the -server. This is possible with the -<A HREF="../mod/core.html#serveralias"><code>ServerAlias</code></A> -directive, placed inside the <VirtualHost> section. For -example:</p> - -<pre> - ServerAlias domain.tld *.domain.tld -</pre> - -<p>Note that you can use <code>*</code> and <code>?</code> as wild-card -characters.</p> - -<p>You also might need <code>ServerAlias</code> if you are -serving local users who do not always include the domain name. -For example, if local users are -familiar with typing "www" or "www.foobar" then you will need to add -<code>ServerAlias www www.foobar</code>. It isn't possible for the -server to know what domain the client uses for their name resolution -because the client doesn't provide that information in the request.</p> - -<h2>Compatibility with Older Browsers</h2> - -<p>As mentioned earlier, there are still some clients in use who -do not send the required data for the name-based virtual hosts to work -properly. These clients will always be sent the pages from the -<cite>primary</cite> name-based virtual host (the first virtual host -appearing in the configuration file for a specific IP address).</p> - -<p>There is a possible workaround with the -<A HREF="../mod/core.html#serverpath"><code>ServerPath</code></A> -directive, albeit a slightly cumbersome one:</p> - -<p>Example configuration: - -<pre> - NameVirtualHost 111.22.33.44 - - <VirtualHost 111.22.33.44> - ServerName www.domain.tld - ServerPath /domain - DocumentRoot /web/domain - </VirtualHost> -</pre> - -<p>What does this mean? It means that a request for any URI beginning -with "<samp>/domain</samp>" will be served from the virtual host -<samp>www.domain.tld</samp> This means that the pages can be accessed as -<code>http://www.domain.tld/domain/</code> for all clients, although -clients sending a <samp>Host:</samp> header can also access it as -<code>http://www.domain.tld/</code>.</p> - -<p>In order to make this work, put a link on your primary virtual host's page -to <samp>http://www.domain.tld/domain/</samp> -Then, in the virtual host's pages, be sure to use either purely -relative links (e.g. "<samp>file.html</samp>" or -"<samp>../icons/image.gif</samp>" or links containing the prefacing -<samp>/domain/</samp> -(e.g. "<samp>http://www.domain.tld/domain/misc/file.html</samp>" or -"<samp>/domain/misc/file.html</samp>").</p> - -<p>This requires a bit of -discipline, but adherence to these guidelines will, for the most part, -ensure that your pages will work with all browsers, new and old.</p> - -<p>See also: <A HREF="examples.html#serverpath">ServerPath configuration -example</A></p> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/modules/aaa/mod_access.exp b/modules/aaa/mod_access.exp new file mode 100644 index 0000000000..f8aff339da --- /dev/null +++ b/modules/aaa/mod_access.exp @@ -0,0 +1 @@ +access_module diff --git a/modules/aaa/mod_auth.exp b/modules/aaa/mod_auth.exp new file mode 100644 index 0000000000..76adad0a66 --- /dev/null +++ b/modules/aaa/mod_auth.exp @@ -0,0 +1 @@ +auth_module diff --git a/modules/aaa/mod_auth_anon.exp b/modules/aaa/mod_auth_anon.exp new file mode 100644 index 0000000000..4139896061 --- /dev/null +++ b/modules/aaa/mod_auth_anon.exp @@ -0,0 +1 @@ +anon_auth_module diff --git a/modules/aaa/mod_auth_dbm.exp b/modules/aaa/mod_auth_dbm.exp new file mode 100644 index 0000000000..dc8a438deb --- /dev/null +++ b/modules/aaa/mod_auth_dbm.exp @@ -0,0 +1 @@ +dbm_auth_module diff --git a/srclib/expat-lite/.cvsignore b/srclib/expat-lite/.cvsignore new file mode 100644 index 0000000000..f3c7a7c5da --- /dev/null +++ b/srclib/expat-lite/.cvsignore @@ -0,0 +1 @@ +Makefile diff --git a/srclib/expat-lite/CHANGES b/srclib/expat-lite/CHANGES new file mode 100644 index 0000000000..e424068ed9 --- /dev/null +++ b/srclib/expat-lite/CHANGES @@ -0,0 +1,41 @@ +=== PURPOSE === + +This file documents the changes made by the Apache Group to James +Clark's Expat parser. The original Expat distribution can be found at +http://www.jclark.com/xml/expat.html. + + +=== SUBSET INFORMATION === + +Apache does not choose (or need) to use the entire Expat parser +distribution. The subset that Apache will use will be referred to as +"expat-lite". In particular, this directory contains the files from +the following Expat distribution subdirectories: + + expat/xmltok/* + expat/xmlparse/* + +We also retain expat/expat.html for attribution to James Clark and +licensing information. + +In addition, we remove expat/xmltok/dllmain.c from our version since +we statically link expat-lite into the executable (rather than +building a DLL on the Win32 platform). The *.dsp files are also +removed, since we place those elsewhere in the Apache source +distribution and they will have a very different structure. + +Makefile.tmpl has been created from scratch to provide build +instructions to the Apache build system. + +This file (CHANGES) has been added to document changes from the +original Expat distribution. + + +=== CHANGES TO ORIGINAL === + +There have been no changes made to any Expat file at this point in +time (May 31, 1999). + +The files, in their original state from the Expat distribution, have +been tagged within CVS with the "EXPAT_1_1" tag. That tag may be used +as a reference for changes made by the Apache Group. diff --git a/srclib/expat-lite/asciitab.h b/srclib/expat-lite/asciitab.h new file mode 100644 index 0000000000..8a8a2dd388 --- /dev/null +++ b/srclib/expat-lite/asciitab.h @@ -0,0 +1,62 @@ +/* +The contents of this file are subject to the Mozilla Public License +Version 1.1 (the "License"); you may not use this file except in +compliance with the License. You may obtain a copy of the License at +http://www.mozilla.org/MPL/ + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the +License for the specific language governing rights and limitations +under the License. + +The Original Code is expat. + +The Initial Developer of the Original Code is James Clark. +Portions created by James Clark are Copyright (C) 1998, 1999 +James Clark. All Rights Reserved. + +Contributor(s): + +Alternatively, the contents of this file may be used under the terms +of the GNU General Public License (the "GPL"), in which case the +provisions of the GPL are applicable instead of those above. If you +wish to allow use of your version of this file only under the terms of +the GPL and not to allow others to use your version of this file under +the MPL, indicate your decision by deleting the provisions above and +replace them with the notice and other provisions required by the +GPL. If you do not delete the provisions above, a recipient may use +your version of this file under either the MPL or the GPL. +*/ + +/* 0x00 */ BT_NONXML, BT_NONXML, BT_NONXML, BT_NONXML, +/* 0x04 */ BT_NONXML, BT_NONXML, BT_NONXML, BT_NONXML, +/* 0x08 */ BT_NONXML, BT_S, BT_LF, BT_NONXML, +/* 0x0C */ BT_NONXML, BT_CR, BT_NONXML, BT_NONXML, +/* 0x10 */ BT_NONXML, BT_NONXML, BT_NONXML, BT_NONXML, +/* 0x14 */ BT_NONXML, BT_NONXML, BT_NONXML, BT_NONXML, +/* 0x18 */ BT_NONXML, BT_NONXML, BT_NONXML, BT_NONXML, +/* 0x1C */ BT_NONXML, BT_NONXML, BT_NONXML, BT_NONXML, +/* 0x20 */ BT_S, BT_EXCL, BT_QUOT, BT_NUM, +/* 0x24 */ BT_OTHER, BT_PERCNT, BT_AMP, BT_APOS, +/* 0x28 */ BT_LPAR, BT_RPAR, BT_AST, BT_PLUS, +/* 0x2C */ BT_COMMA, BT_MINUS, BT_NAME, BT_SOL, +/* 0x30 */ BT_DIGIT, BT_DIGIT, BT_DIGIT, BT_DIGIT, +/* 0x34 */ BT_DIGIT, BT_DIGIT, BT_DIGIT, BT_DIGIT, +/* 0x38 */ BT_DIGIT, BT_DIGIT, BT_COLON, BT_SEMI, +/* 0x3C */ BT_LT, BT_EQUALS, BT_GT, BT_QUEST, +/* 0x40 */ BT_OTHER, BT_HEX, BT_HEX, BT_HEX, +/* 0x44 */ BT_HEX, BT_HEX, BT_HEX, BT_NMSTRT, +/* 0x48 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, +/* 0x4C */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, +/* 0x50 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, +/* 0x54 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, +/* 0x58 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_LSQB, +/* 0x5C */ BT_OTHER, BT_RSQB, BT_OTHER, BT_NMSTRT, +/* 0x60 */ BT_OTHER, BT_HEX, BT_HEX, BT_HEX, +/* 0x64 */ BT_HEX, BT_HEX, BT_HEX, BT_NMSTRT, +/* 0x68 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, +/* 0x6C */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, +/* 0x70 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, +/* 0x74 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, +/* 0x78 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_OTHER, +/* 0x7C */ BT_VERBAR, BT_OTHER, BT_OTHER, BT_OTHER, diff --git a/srclib/expat-lite/expat.html b/srclib/expat-lite/expat.html new file mode 100644 index 0000000000..3806ca8d0e --- /dev/null +++ b/srclib/expat-lite/expat.html @@ -0,0 +1,73 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" +"http://www.w3.org/TR/REC-html40/loose.dtd"> + +<HTML> + +<TITLE>expat</TITLE> + +<BODY> + +<H1>expat - XML Parser Toolkit</H1> + +<H3>Version 1.1</H3> + +<P>Copyright (c) 1998, 1999 James Clark. Expat is subject to the <A +HREF="http://www.mozilla.org/NPL/NPL-1_1Final.html">Mozilla Public +License Version 1.1</A>. Alternatively you may use expat under the <A +href="http://www.gnu.org/copyleft/gpl.html">GNU General Public +License</A> instead. Please contact me if you wish to negotiate an +alternative license.</P> + +<P>Expat is an <A +HREF="http://www.w3.org/TR/1998/REC-xml-19980210">XML 1.0</A> parser +written in C. It aims to be fully conforming. It is currently not a +validating XML processor. The current production version of expat can +be downloaded from <A href = "ftp://ftp.jclark.com/pub/xml/expat.zip" +>ftp://ftp.jclark.com/pub/xml/expat.zip</A>.</P> + +<P>The directory <SAMP>xmltok</SAMP> contains a low-level library for +tokenizing XML. The interface is documented in +<SAMP>xmltok/xmltok.h</SAMP>.</P> + +<P>The directory <SAMP>xmlparse</SAMP> contains an XML parser library +which is built on top of the <SAMP>xmltok</SAMP> library. The +interface is documented in <SAMP>xmlparse/xmlparse.h</SAMP>. The +directory <SAMP>sample</SAMP> contains a simple example program using +this interface; <SAMP>sample/build.bat</SAMP> is a batch file to build +the example using Visual C++.</P> + +<P>The directory <SAMP>xmlwf</SAMP> contains the <SAMP>xmlwf</SAMP> +application, which uses the <SAMP>xmlparse</SAMP> library. The +arguments to <SAMP>xmlwf</SAMP> are one or more files which are each +to be checked for well-formedness. An option <SAMP>-d +<VAR>dir</VAR></SAMP> can be specified; for each well-formed input +file the corresponding <A +href="http://www.jclark.com/xml/canonxml.html">canonical XML</A> will +be written to <SAMP>dir/<VAR>f</VAR></SAMP>, where +<SAMP><VAR>f</VAR></SAMP> is the filename (without any path) of the +input file. A <CODE>-x</CODE> option will cause references to +external general entities to be processed. A <CODE>-s</CODE> option +will make documents that are not standalone cause an error (a document +is considered standalone if either it is intrinsically standalone +because it has no external subset and no references to parameter +entities in the internal subset or it is declared as standalone in the +XML declaration).</P> + +<P>The <SAMP>bin</SAMP> directory contains Win32 executables. The +<SAMP>lib</SAMP> directory contains Win32 import libraries.</P> + +<P>Answers to some frequently asked questions about expat can be found +in the <A HREF="http://www.jclark.com/xml/expatfaq.html">expat +FAQ</A>.</P> + +<P></P> + +<ADDRESS> + +<A HREF="mailto:jjc@jclark.com">James Clark</A> + +</ADDRESS> + +</BODY> + +</HTML> diff --git a/srclib/expat-lite/hashtable.c b/srclib/expat-lite/hashtable.c new file mode 100644 index 0000000000..780a061041 --- /dev/null +++ b/srclib/expat-lite/hashtable.c @@ -0,0 +1,151 @@ +/* +The contents of this file are subject to the Mozilla Public License +Version 1.1 (the "License"); you may not use this file except in +csompliance with the License. You may obtain a copy of the License at +http://www.mozilla.org/MPL/ + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the +License for the specific language governing rights and limitations +under the License. + +The Original Code is expat. + +The Initial Developer of the Original Code is James Clark. +Portions created by James Clark are Copyright (C) 1998, 1999 +James Clark. All Rights Reserved. + +Contributor(s): + +Alternatively, the contents of this file may be used under the terms +of the GNU General Public License (the "GPL"), in which case the +provisions of the GPL are applicable instead of those above. If you +wish to allow use of your version of this file only under the terms of +the GPL and not to allow others to use your version of this file under +the MPL, indicate your decision by deleting the provisions above and +replace them with the notice and other provisions required by the +GPL. If you do not delete the provisions above, a recipient may use +your version of this file under either the MPL or the GPL. +*/ + +#include "xmldef.h" + +#ifdef XML_UNICODE_WCHAR_T +#ifndef XML_UNICODE +#define XML_UNICODE +#endif +#endif + +#include "hashtable.h" + +#define INIT_SIZE 64 + +static +int keyeq(KEY s1, KEY s2) +{ + for (; *s1 == *s2; s1++, s2++) + if (*s1 == 0) + return 1; + return 0; +} + +static +unsigned long hash(KEY s) +{ + unsigned long h = 0; + while (*s) + h = (h << 5) + h + (unsigned char)*s++; + return h; +} + +NAMED *lookup(HASH_TABLE *table, KEY name, size_t createSize) +{ + size_t i; + if (table->size == 0) { + if (!createSize) + return 0; + table->v = calloc(INIT_SIZE, sizeof(NAMED *)); + if (!table->v) + return 0; + table->size = INIT_SIZE; + table->usedLim = INIT_SIZE / 2; + i = hash(name) & (table->size - 1); + } + else { + unsigned long h = hash(name); + for (i = h & (table->size - 1); + table->v[i]; + i == 0 ? i = table->size - 1 : --i) { + if (keyeq(name, table->v[i]->name)) + return table->v[i]; + } + if (!createSize) + return 0; + if (table->used == table->usedLim) { + /* check for overflow */ + size_t newSize = table->size * 2; + NAMED **newV = calloc(newSize, sizeof(NAMED *)); + if (!newV) + return 0; + for (i = 0; i < table->size; i++) + if (table->v[i]) { + size_t j; + for (j = hash(table->v[i]->name) & (newSize - 1); + newV[j]; + j == 0 ? j = newSize - 1 : --j) + ; + newV[j] = table->v[i]; + } + free(table->v); + table->v = newV; + table->size = newSize; + table->usedLim = newSize/2; + for (i = h & (table->size - 1); + table->v[i]; + i == 0 ? i = table->size - 1 : --i) + ; + } + } + table->v[i] = calloc(1, createSize); + if (!table->v[i]) + return 0; + table->v[i]->name = name; + (table->used)++; + return table->v[i]; +} + +void hashTableDestroy(HASH_TABLE *table) +{ + size_t i; + for (i = 0; i < table->size; i++) { + NAMED *p = table->v[i]; + if (p) + free(p); + } + free(table->v); +} + +void hashTableInit(HASH_TABLE *p) +{ + p->size = 0; + p->usedLim = 0; + p->used = 0; + p->v = 0; +} + +void hashTableIterInit(HASH_TABLE_ITER *iter, const HASH_TABLE *table) +{ + iter->p = table->v; + iter->end = iter->p + table->size; +} + +NAMED *hashTableIterNext(HASH_TABLE_ITER *iter) +{ + while (iter->p != iter->end) { + NAMED *tem = *(iter->p)++; + if (tem) + return tem; + } + return 0; +} + diff --git a/srclib/expat-lite/hashtable.h b/srclib/expat-lite/hashtable.h new file mode 100644 index 0000000000..df8ab8a4c8 --- /dev/null +++ b/srclib/expat-lite/hashtable.h @@ -0,0 +1,69 @@ +/* +The contents of this file are subject to the Mozilla Public License +Version 1.1 (the "License"); you may not use this file except in +compliance with the License. You may obtain a copy of the License at +http://www.mozilla.org/MPL/ + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the +License for the specific language governing rights and limitations +under the License. + +The Original Code is expat. + +The Initial Developer of the Original Code is James Clark. +Portions created by James Clark are Copyright (C) 1998, 1999 +James Clark. All Rights Reserved. + +Contributor(s): + +Alternatively, the contents of this file may be used under the terms +of the GNU General Public License (the "GPL"), in which case the +provisions of the GPL are applicable instead of those above. If you +wish to allow use of your version of this file only under the terms of +the GPL and not to allow others to use your version of this file under +the MPL, indicate your decision by deleting the provisions above and +replace them with the notice and other provisions required by the +GPL. If you do not delete the provisions above, a recipient may use +your version of this file under either the MPL or the GPL. +*/ + + +#include <stddef.h> + +#ifdef XML_UNICODE + +#ifdef XML_UNICODE_WCHAR_T +typedef const wchar_t *KEY; +#else /* not XML_UNICODE_WCHAR_T */ +typedef const unsigned short *KEY; +#endif /* not XML_UNICODE_WCHAR_T */ + +#else /* not XML_UNICODE */ + +typedef const char *KEY; + +#endif /* not XML_UNICODE */ + +typedef struct { + KEY name; +} NAMED; + +typedef struct { + NAMED **v; + size_t size; + size_t used; + size_t usedLim; +} HASH_TABLE; + +NAMED *lookup(HASH_TABLE *table, KEY name, size_t createSize); +void hashTableInit(HASH_TABLE *); +void hashTableDestroy(HASH_TABLE *); + +typedef struct { + NAMED **p; + NAMED **end; +} HASH_TABLE_ITER; + +void hashTableIterInit(HASH_TABLE_ITER *, const HASH_TABLE *); +NAMED *hashTableIterNext(HASH_TABLE_ITER *); diff --git a/srclib/expat-lite/iasciitab.h b/srclib/expat-lite/iasciitab.h new file mode 100644 index 0000000000..333d6bb779 --- /dev/null +++ b/srclib/expat-lite/iasciitab.h @@ -0,0 +1,63 @@ +/* +The contents of this file are subject to the Mozilla Public License +Version 1.1 (the "License"); you may not use this file except in +compliance with the License. You may obtain a copy of the License at +http://www.mozilla.org/MPL/ + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the +License for the specific language governing rights and limitations +under the License. + +The Original Code is expat. + +The Initial Developer of the Original Code is James Clark. +Portions created by James Clark are Copyright (C) 1998, 1999 +James Clark. All Rights Reserved. + +Contributor(s): + +Alternatively, the contents of this file may be used under the terms +of the GNU General Public License (the "GPL"), in which case the +provisions of the GPL are applicable instead of those above. If you +wish to allow use of your version of this file only under the terms of +the GPL and not to allow others to use your version of this file under +the MPL, indicate your decision by deleting the provisions above and +replace them with the notice and other provisions required by the +GPL. If you do not delete the provisions above, a recipient may use +your version of this file under either the MPL or the GPL. +*/ + +/* Like asciitab.h, except that 0xD has code BT_S rather than BT_CR */ +/* 0x00 */ BT_NONXML, BT_NONXML, BT_NONXML, BT_NONXML, +/* 0x04 */ BT_NONXML, BT_NONXML, BT_NONXML, BT_NONXML, +/* 0x08 */ BT_NONXML, BT_S, BT_LF, BT_NONXML, +/* 0x0C */ BT_NONXML, BT_S, BT_NONXML, BT_NONXML, +/* 0x10 */ BT_NONXML, BT_NONXML, BT_NONXML, BT_NONXML, +/* 0x14 */ BT_NONXML, BT_NONXML, BT_NONXML, BT_NONXML, +/* 0x18 */ BT_NONXML, BT_NONXML, BT_NONXML, BT_NONXML, +/* 0x1C */ BT_NONXML, BT_NONXML, BT_NONXML, BT_NONXML, +/* 0x20 */ BT_S, BT_EXCL, BT_QUOT, BT_NUM, +/* 0x24 */ BT_OTHER, BT_PERCNT, BT_AMP, BT_APOS, +/* 0x28 */ BT_LPAR, BT_RPAR, BT_AST, BT_PLUS, +/* 0x2C */ BT_COMMA, BT_MINUS, BT_NAME, BT_SOL, +/* 0x30 */ BT_DIGIT, BT_DIGIT, BT_DIGIT, BT_DIGIT, +/* 0x34 */ BT_DIGIT, BT_DIGIT, BT_DIGIT, BT_DIGIT, +/* 0x38 */ BT_DIGIT, BT_DIGIT, BT_COLON, BT_SEMI, +/* 0x3C */ BT_LT, BT_EQUALS, BT_GT, BT_QUEST, +/* 0x40 */ BT_OTHER, BT_HEX, BT_HEX, BT_HEX, +/* 0x44 */ BT_HEX, BT_HEX, BT_HEX, BT_NMSTRT, +/* 0x48 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, +/* 0x4C */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, +/* 0x50 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, +/* 0x54 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, +/* 0x58 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_LSQB, +/* 0x5C */ BT_OTHER, BT_RSQB, BT_OTHER, BT_NMSTRT, +/* 0x60 */ BT_OTHER, BT_HEX, BT_HEX, BT_HEX, +/* 0x64 */ BT_HEX, BT_HEX, BT_HEX, BT_NMSTRT, +/* 0x68 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, +/* 0x6C */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, +/* 0x70 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, +/* 0x74 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, +/* 0x78 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_OTHER, +/* 0x7C */ BT_VERBAR, BT_OTHER, BT_OTHER, BT_OTHER, diff --git a/srclib/expat-lite/latin1tab.h b/srclib/expat-lite/latin1tab.h new file mode 100644 index 0000000000..48609aa8f9 --- /dev/null +++ b/srclib/expat-lite/latin1tab.h @@ -0,0 +1,62 @@ +/* +The contents of this file are subject to the Mozilla Public License +Version 1.1 (the "License"); you may not use this file except in +compliance with the License. You may obtain a copy of the License at +http://www.mozilla.org/MPL/ + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the +License for the specific language governing rights and limitations +under the License. + +The Original Code is expat. + +The Initial Developer of the Original Code is James Clark. +Portions created by James Clark are Copyright (C) 1998, 1999 +James Clark. All Rights Reserved. + +Contributor(s): + +Alternatively, the contents of this file may be used under the terms +of the GNU General Public License (the "GPL"), in which case the +provisions of the GPL are applicable instead of those above. If you +wish to allow use of your version of this file only under the terms of +the GPL and not to allow others to use your version of this file under +the MPL, indicate your decision by deleting the provisions above and +replace them with the notice and other provisions required by the +GPL. If you do not delete the provisions above, a recipient may use +your version of this file under either the MPL or the GPL. +*/ + +/* 0x80 */ BT_OTHER, BT_OTHER, BT_OTHER, BT_OTHER, +/* 0x84 */ BT_OTHER, BT_OTHER, BT_OTHER, BT_OTHER, +/* 0x88 */ BT_OTHER, BT_OTHER, BT_OTHER, BT_OTHER, +/* 0x8C */ BT_OTHER, BT_OTHER, BT_OTHER, BT_OTHER, +/* 0x90 */ BT_OTHER, BT_OTHER, BT_OTHER, BT_OTHER, +/* 0x94 */ BT_OTHER, BT_OTHER, BT_OTHER, BT_OTHER, +/* 0x98 */ BT_OTHER, BT_OTHER, BT_OTHER, BT_OTHER, +/* 0x9C */ BT_OTHER, BT_OTHER, BT_OTHER, BT_OTHER, +/* 0xA0 */ BT_OTHER, BT_OTHER, BT_OTHER, BT_OTHER, +/* 0xA4 */ BT_OTHER, BT_OTHER, BT_OTHER, BT_OTHER, +/* 0xA8 */ BT_OTHER, BT_OTHER, BT_NMSTRT, BT_OTHER, +/* 0xAC */ BT_OTHER, BT_OTHER, BT_OTHER, BT_OTHER, +/* 0xB0 */ BT_OTHER, BT_OTHER, BT_OTHER, BT_OTHER, +/* 0xB4 */ BT_OTHER, BT_NMSTRT, BT_OTHER, BT_NAME, +/* 0xB8 */ BT_OTHER, BT_OTHER, BT_NMSTRT, BT_OTHER, +/* 0xBC */ BT_OTHER, BT_OTHER, BT_OTHER, BT_OTHER, +/* 0xC0 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, +/* 0xC4 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, +/* 0xC8 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, +/* 0xCC */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, +/* 0xD0 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, +/* 0xD4 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_OTHER, +/* 0xD8 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, +/* 0xDC */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, +/* 0xE0 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, +/* 0xE4 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, +/* 0xE8 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, +/* 0xEC */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, +/* 0xF0 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, +/* 0xF4 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_OTHER, +/* 0xF8 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, +/* 0xFC */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, diff --git a/srclib/expat-lite/nametab.h b/srclib/expat-lite/nametab.h new file mode 100644 index 0000000000..b05e62c77a --- /dev/null +++ b/srclib/expat-lite/nametab.h @@ -0,0 +1,150 @@ +static const unsigned namingBitmap[] = { +0x00000000, 0x00000000, 0x00000000, 0x00000000, +0x00000000, 0x00000000, 0x00000000, 0x00000000, +0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, +0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, +0x00000000, 0x04000000, 0x87FFFFFE, 0x07FFFFFE, +0x00000000, 0x00000000, 0xFF7FFFFF, 0xFF7FFFFF, +0xFFFFFFFF, 0x7FF3FFFF, 0xFFFFFDFE, 0x7FFFFFFF, +0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFE00F, 0xFC31FFFF, +0x00FFFFFF, 0x00000000, 0xFFFF0000, 0xFFFFFFFF, +0xFFFFFFFF, 0xF80001FF, 0x00000003, 0x00000000, +0x00000000, 0x00000000, 0x00000000, 0x00000000, +0xFFFFD740, 0xFFFFFFFB, 0x547F7FFF, 0x000FFFFD, +0xFFFFDFFE, 0xFFFFFFFF, 0xDFFEFFFF, 0xFFFFFFFF, +0xFFFF0003, 0xFFFFFFFF, 0xFFFF199F, 0x033FCFFF, +0x00000000, 0xFFFE0000, 0x027FFFFF, 0xFFFFFFFE, +0x0000007F, 0x00000000, 0xFFFF0000, 0x000707FF, +0x00000000, 0x07FFFFFE, 0x000007FE, 0xFFFE0000, +0xFFFFFFFF, 0x7CFFFFFF, 0x002F7FFF, 0x00000060, +0xFFFFFFE0, 0x23FFFFFF, 0xFF000000, 0x00000003, +0xFFF99FE0, 0x03C5FDFF, 0xB0000000, 0x00030003, +0xFFF987E0, 0x036DFDFF, 0x5E000000, 0x001C0000, +0xFFFBAFE0, 0x23EDFDFF, 0x00000000, 0x00000001, +0xFFF99FE0, 0x23CDFDFF, 0xB0000000, 0x00000003, +0xD63DC7E0, 0x03BFC718, 0x00000000, 0x00000000, +0xFFFDDFE0, 0x03EFFDFF, 0x00000000, 0x00000003, +0xFFFDDFE0, 0x03EFFDFF, 0x40000000, 0x00000003, +0xFFFDDFE0, 0x03FFFDFF, 0x00000000, 0x00000003, +0x00000000, 0x00000000, 0x00000000, 0x00000000, +0xFFFFFFFE, 0x000D7FFF, 0x0000003F, 0x00000000, +0xFEF02596, 0x200D6CAE, 0x0000001F, 0x00000000, +0x00000000, 0x00000000, 0xFFFFFEFF, 0x000003FF, +0x00000000, 0x00000000, 0x00000000, 0x00000000, +0x00000000, 0x00000000, 0x00000000, 0x00000000, +0x00000000, 0xFFFFFFFF, 0xFFFF003F, 0x007FFFFF, +0x0007DAED, 0x50000000, 0x82315001, 0x002C62AB, +0x40000000, 0xF580C900, 0x00000007, 0x02010800, +0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, +0x0FFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0x03FFFFFF, +0x3F3FFFFF, 0xFFFFFFFF, 0xAAFF3F3F, 0x3FFFFFFF, +0xFFFFFFFF, 0x5FDFFFFF, 0x0FCF1FDC, 0x1FDC1FFF, +0x00000000, 0x00004C40, 0x00000000, 0x00000000, +0x00000007, 0x00000000, 0x00000000, 0x00000000, +0x00000080, 0x000003FE, 0xFFFFFFFE, 0xFFFFFFFF, +0x001FFFFF, 0xFFFFFFFE, 0xFFFFFFFF, 0x07FFFFFF, +0xFFFFFFE0, 0x00001FFF, 0x00000000, 0x00000000, +0x00000000, 0x00000000, 0x00000000, 0x00000000, +0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, +0xFFFFFFFF, 0x0000003F, 0x00000000, 0x00000000, +0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, +0xFFFFFFFF, 0x0000000F, 0x00000000, 0x00000000, +0x00000000, 0x07FF6000, 0x87FFFFFE, 0x07FFFFFE, +0x00000000, 0x00800000, 0xFF7FFFFF, 0xFF7FFFFF, +0x00FFFFFF, 0x00000000, 0xFFFF0000, 0xFFFFFFFF, +0xFFFFFFFF, 0xF80001FF, 0x00030003, 0x00000000, +0xFFFFFFFF, 0xFFFFFFFF, 0x0000003F, 0x00000003, +0xFFFFD7C0, 0xFFFFFFFB, 0x547F7FFF, 0x000FFFFD, +0xFFFFDFFE, 0xFFFFFFFF, 0xDFFEFFFF, 0xFFFFFFFF, +0xFFFF007B, 0xFFFFFFFF, 0xFFFF199F, 0x033FCFFF, +0x00000000, 0xFFFE0000, 0x027FFFFF, 0xFFFFFFFE, +0xFFFE007F, 0xBBFFFFFB, 0xFFFF0016, 0x000707FF, +0x00000000, 0x07FFFFFE, 0x0007FFFF, 0xFFFF03FF, +0xFFFFFFFF, 0x7CFFFFFF, 0xFFEF7FFF, 0x03FF3DFF, +0xFFFFFFEE, 0xF3FFFFFF, 0xFF1E3FFF, 0x0000FFCF, +0xFFF99FEE, 0xD3C5FDFF, 0xB080399F, 0x0003FFCF, +0xFFF987E4, 0xD36DFDFF, 0x5E003987, 0x001FFFC0, +0xFFFBAFEE, 0xF3EDFDFF, 0x00003BBF, 0x0000FFC1, +0xFFF99FEE, 0xF3CDFDFF, 0xB0C0398F, 0x0000FFC3, +0xD63DC7EC, 0xC3BFC718, 0x00803DC7, 0x0000FF80, +0xFFFDDFEE, 0xC3EFFDFF, 0x00603DDF, 0x0000FFC3, +0xFFFDDFEC, 0xC3EFFDFF, 0x40603DDF, 0x0000FFC3, +0xFFFDDFEC, 0xC3FFFDFF, 0x00803DCF, 0x0000FFC3, +0x00000000, 0x00000000, 0x00000000, 0x00000000, +0xFFFFFFFE, 0x07FF7FFF, 0x03FF7FFF, 0x00000000, +0xFEF02596, 0x3BFF6CAE, 0x03FF3F5F, 0x00000000, +0x03000000, 0xC2A003FF, 0xFFFFFEFF, 0xFFFE03FF, +0xFEBF0FDF, 0x02FE3FFF, 0x00000000, 0x00000000, +0x00000000, 0x00000000, 0x00000000, 0x00000000, +0x00000000, 0x00000000, 0x1FFF0000, 0x00000002, +0x000000A0, 0x003EFFFE, 0xFFFFFFFE, 0xFFFFFFFF, +0x661FFFFF, 0xFFFFFFFE, 0xFFFFFFFF, 0x77FFFFFF, +}; +static const unsigned char nmstrtPages[] = { +0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x00, +0x00, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F, +0x10, 0x11, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, +0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x12, 0x13, +0x00, 0x14, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, +0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, +0x15, 0x16, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, +0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, +0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, +0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x01, +0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, +0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, +0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, +0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, +0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, +0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, +0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, +0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, +0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, +0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x17, +0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, +0x00, 0x00, 0x00, 0x00, 0x01, 0x01, 0x01, 0x01, +0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, +0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, +0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, +0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, +0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x18, +0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, +0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, +0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, +0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, +0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, +}; +static const unsigned char namePages[] = { +0x19, 0x03, 0x1A, 0x1B, 0x1C, 0x1D, 0x1E, 0x00, +0x00, 0x1F, 0x20, 0x21, 0x22, 0x23, 0x24, 0x25, +0x10, 0x11, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, +0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x12, 0x13, +0x26, 0x14, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, +0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, +0x27, 0x16, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, +0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, +0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, +0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x01, +0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, +0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, +0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, +0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, +0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, +0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, +0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, +0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, +0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, +0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x17, +0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, +0x00, 0x00, 0x00, 0x00, 0x01, 0x01, 0x01, 0x01, +0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, +0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, +0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, +0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, +0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x18, +0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, +0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, +0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, +0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, +0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, +}; diff --git a/srclib/expat-lite/utf8tab.h b/srclib/expat-lite/utf8tab.h new file mode 100644 index 0000000000..a38fe624e8 --- /dev/null +++ b/srclib/expat-lite/utf8tab.h @@ -0,0 +1,63 @@ +/* +The contents of this file are subject to the Mozilla Public License +Version 1.1 (the "License"); you may not use this file except in +compliance with the License. You may obtain a copy of the License at +http://www.mozilla.org/MPL/ + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the +License for the specific language governing rights and limitations +under the License. + +The Original Code is expat. + +The Initial Developer of the Original Code is James Clark. +Portions created by James Clark are Copyright (C) 1998, 1999 +James Clark. All Rights Reserved. + +Contributor(s): + +Alternatively, the contents of this file may be used under the terms +of the GNU General Public License (the "GPL"), in which case the +provisions of the GPL are applicable instead of those above. If you +wish to allow use of your version of this file only under the terms of +the GPL and not to allow others to use your version of this file under +the MPL, indicate your decision by deleting the provisions above and +replace them with the notice and other provisions required by the +GPL. If you do not delete the provisions above, a recipient may use +your version of this file under either the MPL or the GPL. +*/ + + +/* 0x80 */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL, +/* 0x84 */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL, +/* 0x88 */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL, +/* 0x8C */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL, +/* 0x90 */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL, +/* 0x94 */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL, +/* 0x98 */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL, +/* 0x9C */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL, +/* 0xA0 */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL, +/* 0xA4 */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL, +/* 0xA8 */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL, +/* 0xAC */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL, +/* 0xB0 */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL, +/* 0xB4 */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL, +/* 0xB8 */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL, +/* 0xBC */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL, +/* 0xC0 */ BT_LEAD2, BT_LEAD2, BT_LEAD2, BT_LEAD2, +/* 0xC4 */ BT_LEAD2, BT_LEAD2, BT_LEAD2, BT_LEAD2, +/* 0xC8 */ BT_LEAD2, BT_LEAD2, BT_LEAD2, BT_LEAD2, +/* 0xCC */ BT_LEAD2, BT_LEAD2, BT_LEAD2, BT_LEAD2, +/* 0xD0 */ BT_LEAD2, BT_LEAD2, BT_LEAD2, BT_LEAD2, +/* 0xD4 */ BT_LEAD2, BT_LEAD2, BT_LEAD2, BT_LEAD2, +/* 0xD8 */ BT_LEAD2, BT_LEAD2, BT_LEAD2, BT_LEAD2, +/* 0xDC */ BT_LEAD2, BT_LEAD2, BT_LEAD2, BT_LEAD2, +/* 0xE0 */ BT_LEAD3, BT_LEAD3, BT_LEAD3, BT_LEAD3, +/* 0xE4 */ BT_LEAD3, BT_LEAD3, BT_LEAD3, BT_LEAD3, +/* 0xE8 */ BT_LEAD3, BT_LEAD3, BT_LEAD3, BT_LEAD3, +/* 0xEC */ BT_LEAD3, BT_LEAD3, BT_LEAD3, BT_LEAD3, +/* 0xF0 */ BT_LEAD4, BT_LEAD4, BT_LEAD4, BT_LEAD4, +/* 0xF4 */ BT_LEAD4, BT_NONXML, BT_NONXML, BT_NONXML, +/* 0xF8 */ BT_NONXML, BT_NONXML, BT_NONXML, BT_NONXML, +/* 0xFC */ BT_NONXML, BT_NONXML, BT_MALFORM, BT_MALFORM, diff --git a/srclib/expat-lite/xmldef.h b/srclib/expat-lite/xmldef.h new file mode 100644 index 0000000000..49ce9ed636 --- /dev/null +++ b/srclib/expat-lite/xmldef.h @@ -0,0 +1,63 @@ +/* +The contents of this file are subject to the Mozilla Public License +Version 1.1 (the "License"); you may not use this file except in +compliance with the License. You may obtain a copy of the License at +http://www.mozilla.org/MPL/ + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the +License for the specific language governing rights and limitations +under the License. + +The Original Code is expat. + +The Initial Developer of the Original Code is James Clark. +Portions created by James Clark are Copyright (C) 1998, 1999 +James Clark. All Rights Reserved. + +Contributor(s): + +Alternatively, the contents of this file may be used under the terms +of the GNU General Public License (the "GPL"), in which case the +provisions of the GPL are applicable instead of those above. If you +wish to allow use of your version of this file only under the terms of +the GPL and not to allow others to use your version of this file under +the MPL, indicate your decision by deleting the provisions above and +replace them with the notice and other provisions required by the +GPL. If you do not delete the provisions above, a recipient may use +your version of this file under either the MPL or the GPL. +*/ + +#include <string.h> + +#ifdef XML_WINLIB + +#define WIN32_LEAN_AND_MEAN +#define STRICT +#include <windows.h> + +#define malloc(x) HeapAlloc(GetProcessHeap(), 0, (x)) +#define calloc(x, y) HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, (x)*(y)) +#define free(x) HeapFree(GetProcessHeap(), 0, (x)) +#define realloc(x, y) HeapReAlloc(GetProcessHeap(), 0, x, y) +#define abort() /* as nothing */ + +#else /* not XML_WINLIB */ + +#include <stdlib.h> + +#endif /* not XML_WINLIB */ + +/* This file can be used for any definitions needed in +particular environments. */ + +#ifdef MOZILLA + +#include "nspr.h" +#define malloc(x) PR_Malloc(x) +#define realloc(x, y) PR_Realloc((x), (y)) +#define calloc(x, y) PR_Calloc((x),(y)) +#define free(x) PR_Free(x) +#define int int32 + +#endif /* MOZILLA */ diff --git a/srclib/expat-lite/xmlparse.c b/srclib/expat-lite/xmlparse.c new file mode 100644 index 0000000000..8f9d09c86e --- /dev/null +++ b/srclib/expat-lite/xmlparse.c @@ -0,0 +1,3256 @@ +/* +The contents of this file are subject to the Mozilla Public License +Version 1.1 (the "License"); you may not use this file except in +compliance with the License. You may obtain a copy of the License at +http://www.mozilla.org/MPL/ + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the +License for the specific language governing rights and limitations +under the License. + +The Original Code is expat. + +The Initial Developer of the Original Code is James Clark. +Portions created by James Clark are Copyright (C) 1998, 1999 +James Clark. All Rights Reserved. + +Contributor(s): + +Alternatively, the contents of this file may be used under the terms +of the GNU General Public License (the "GPL"), in which case the +provisions of the GPL are applicable instead of those above. If you +wish to allow use of your version of this file only under the terms of +the GPL and not to allow others to use your version of this file under +the MPL, indicate your decision by deleting the provisions above and +replace them with the notice and other provisions required by the +GPL. If you do not delete the provisions above, a recipient may use +your version of this file under either the MPL or the GPL. +*/ + +#include "xmldef.h" +#include "xmlparse.h" + +#ifdef XML_UNICODE +#define XML_ENCODE_MAX XML_UTF16_ENCODE_MAX +#define XmlConvert XmlUtf16Convert +#define XmlGetInternalEncoding XmlGetUtf16InternalEncoding +#define XmlGetInternalEncodingNS XmlGetUtf16InternalEncodingNS +#define XmlEncode XmlUtf16Encode +#define MUST_CONVERT(enc, s) (!(enc)->isUtf16 || (((unsigned long)s) & 1)) +typedef unsigned short ICHAR; +#else +#define XML_ENCODE_MAX XML_UTF8_ENCODE_MAX +#define XmlConvert XmlUtf8Convert +#define XmlGetInternalEncoding XmlGetUtf8InternalEncoding +#define XmlGetInternalEncodingNS XmlGetUtf8InternalEncodingNS +#define XmlEncode XmlUtf8Encode +#define MUST_CONVERT(enc, s) (!(enc)->isUtf8) +typedef char ICHAR; +#endif + + +#ifndef XML_NS + +#define XmlInitEncodingNS XmlInitEncoding +#define XmlInitUnknownEncodingNS XmlInitUnknownEncoding +#undef XmlGetInternalEncodingNS +#define XmlGetInternalEncodingNS XmlGetInternalEncoding +#define XmlParseXmlDeclNS XmlParseXmlDecl + +#endif + + +#ifdef XML_UNICODE_WCHAR_T +#define XML_T(x) L ## x +#else +#define XML_T(x) x +#endif + +/* Round up n to be a multiple of sz, where sz is a power of 2. */ +#define ROUND_UP(n, sz) (((n) + ((sz) - 1)) & ~((sz) - 1)) + +#include "xmltok.h" +#include "xmlrole.h" +#include "hashtable.h" + +#define INIT_TAG_BUF_SIZE 32 /* must be a multiple of sizeof(XML_Char) */ +#define INIT_DATA_BUF_SIZE 1024 +#define INIT_ATTS_SIZE 16 +#define INIT_BLOCK_SIZE 1024 +#define INIT_BUFFER_SIZE 1024 + +#define EXPAND_SPARE 24 + +typedef struct binding { + struct prefix *prefix; + struct binding *nextTagBinding; + struct binding *prevPrefixBinding; + const struct attribute_id *attId; + XML_Char *uri; + int uriLen; + int uriAlloc; +} BINDING; + +typedef struct prefix { + const XML_Char *name; + BINDING *binding; +} PREFIX; + +typedef struct { + const XML_Char *str; + const XML_Char *localPart; + int uriLen; +} TAG_NAME; + +typedef struct tag { + struct tag *parent; + const char *rawName; + int rawNameLength; + TAG_NAME name; + char *buf; + char *bufEnd; + BINDING *bindings; +} TAG; + +typedef struct { + const XML_Char *name; + const XML_Char *textPtr; + int textLen; + const XML_Char *systemId; + const XML_Char *base; + const XML_Char *publicId; + const XML_Char *notation; + char open; +} ENTITY; + +typedef struct block { + struct block *next; + int size; + XML_Char s[1]; +} BLOCK; + +typedef struct { + BLOCK *blocks; + BLOCK *freeBlocks; + const XML_Char *end; + XML_Char *ptr; + XML_Char *start; +} STRING_POOL; + +/* The XML_Char before the name is used to determine whether +an attribute has been specified. */ +typedef struct attribute_id { + XML_Char *name; + PREFIX *prefix; + char maybeTokenized; + char xmlns; +} ATTRIBUTE_ID; + +typedef struct { + const ATTRIBUTE_ID *id; + char isCdata; + const XML_Char *value; +} DEFAULT_ATTRIBUTE; + +typedef struct { + const XML_Char *name; + PREFIX *prefix; + int nDefaultAtts; + int allocDefaultAtts; + DEFAULT_ATTRIBUTE *defaultAtts; +} ELEMENT_TYPE; + +typedef struct { + HASH_TABLE generalEntities; + HASH_TABLE elementTypes; + HASH_TABLE attributeIds; + HASH_TABLE prefixes; + STRING_POOL pool; + int complete; + int standalone; + const XML_Char *base; + PREFIX defaultPrefix; +} DTD; + +typedef struct open_internal_entity { + const char *internalEventPtr; + const char *internalEventEndPtr; + struct open_internal_entity *next; + ENTITY *entity; +} OPEN_INTERNAL_ENTITY; + +typedef enum XML_Error Processor(XML_Parser parser, + const char *start, + const char *end, + const char **endPtr); + +static Processor prologProcessor; +static Processor prologInitProcessor; +static Processor contentProcessor; +static Processor cdataSectionProcessor; +static Processor epilogProcessor; +#if 0 +static Processor errorProcessor; +#endif +static Processor externalEntityInitProcessor; +static Processor externalEntityInitProcessor2; +static Processor externalEntityInitProcessor3; +static Processor externalEntityContentProcessor; + +static enum XML_Error +handleUnknownEncoding(XML_Parser parser, const XML_Char *encodingName); +static enum XML_Error +processXmlDecl(XML_Parser parser, int isGeneralTextEntity, const char *, const char *); +static enum XML_Error +initializeEncoding(XML_Parser parser); +static enum XML_Error +doContent(XML_Parser parser, int startTagLevel, const ENCODING *enc, + const char *start, const char *end, const char **endPtr); +static enum XML_Error +doCdataSection(XML_Parser parser, const ENCODING *, const char **startPtr, const char *end, const char **nextPtr); +static enum XML_Error storeAtts(XML_Parser parser, const ENCODING *, const char *s, + TAG_NAME *tagNamePtr, BINDING **bindingsPtr); +static +int addBinding(XML_Parser parser, PREFIX *prefix, const ATTRIBUTE_ID *attId, const XML_Char *uri, BINDING **bindingsPtr); +static int +defineAttribute(ELEMENT_TYPE *type, ATTRIBUTE_ID *, int isCdata, const XML_Char *dfltValue); +static enum XML_Error +storeAttributeValue(XML_Parser parser, const ENCODING *, int isCdata, const char *, const char *, + STRING_POOL *); +static enum XML_Error +appendAttributeValue(XML_Parser parser, const ENCODING *, int isCdata, const char *, const char *, + STRING_POOL *); +static ATTRIBUTE_ID * +getAttributeId(XML_Parser parser, const ENCODING *enc, const char *start, const char *end); +static int setElementTypePrefix(XML_Parser parser, ELEMENT_TYPE *); +static enum XML_Error +storeEntityValue(XML_Parser parser, const char *start, const char *end); +static int +reportProcessingInstruction(XML_Parser parser, const ENCODING *enc, const char *start, const char *end); +static int +reportComment(XML_Parser parser, const ENCODING *enc, const char *start, const char *end); +static void +reportDefault(XML_Parser parser, const ENCODING *enc, const char *start, const char *end); + +static const XML_Char *getContext(XML_Parser parser); +static int setContext(XML_Parser parser, const XML_Char *context); +static void normalizePublicId(XML_Char *s); +static int dtdInit(DTD *); +static void dtdDestroy(DTD *); +static int dtdCopy(DTD *newDtd, const DTD *oldDtd); +static void poolInit(STRING_POOL *); +static void poolClear(STRING_POOL *); +static void poolDestroy(STRING_POOL *); +static XML_Char *poolAppend(STRING_POOL *pool, const ENCODING *enc, + const char *ptr, const char *end); +static XML_Char *poolStoreString(STRING_POOL *pool, const ENCODING *enc, + const char *ptr, const char *end); +static int poolGrow(STRING_POOL *pool); +static const XML_Char *poolCopyString(STRING_POOL *pool, const XML_Char *s); +static const XML_Char *poolCopyStringN(STRING_POOL *pool, const XML_Char *s, int n); + +#define poolStart(pool) ((pool)->start) +#define poolEnd(pool) ((pool)->ptr) +#define poolLength(pool) ((pool)->ptr - (pool)->start) +#define poolChop(pool) ((void)--(pool->ptr)) +#define poolLastChar(pool) (((pool)->ptr)[-1]) +#define poolDiscard(pool) ((pool)->ptr = (pool)->start) +#define poolFinish(pool) ((pool)->start = (pool)->ptr) +#define poolAppendChar(pool, c) \ + (((pool)->ptr == (pool)->end && !poolGrow(pool)) \ + ? 0 \ + : ((*((pool)->ptr)++ = c), 1)) + +typedef struct { + /* The first member must be userData so that the XML_GetUserData macro works. */ + void *m_userData; + void *m_handlerArg; + char *m_buffer; + /* first character to be parsed */ + const char *m_bufferPtr; + /* past last character to be parsed */ + char *m_bufferEnd; + /* allocated end of buffer */ + const char *m_bufferLim; + long m_parseEndByteIndex; + const char *m_parseEndPtr; + XML_Char *m_dataBuf; + XML_Char *m_dataBufEnd; + XML_StartElementHandler m_startElementHandler; + XML_EndElementHandler m_endElementHandler; + XML_CharacterDataHandler m_characterDataHandler; + XML_ProcessingInstructionHandler m_processingInstructionHandler; + XML_CommentHandler m_commentHandler; + XML_StartCdataSectionHandler m_startCdataSectionHandler; + XML_EndCdataSectionHandler m_endCdataSectionHandler; + XML_DefaultHandler m_defaultHandler; + XML_UnparsedEntityDeclHandler m_unparsedEntityDeclHandler; + XML_NotationDeclHandler m_notationDeclHandler; + XML_StartNamespaceDeclHandler m_startNamespaceDeclHandler; + XML_EndNamespaceDeclHandler m_endNamespaceDeclHandler; + XML_NotStandaloneHandler m_notStandaloneHandler; + XML_ExternalEntityRefHandler m_externalEntityRefHandler; + void *m_externalEntityRefHandlerArg; + XML_UnknownEncodingHandler m_unknownEncodingHandler; + const ENCODING *m_encoding; + INIT_ENCODING m_initEncoding; + const XML_Char *m_protocolEncodingName; + int m_ns; + void *m_unknownEncodingMem; + void *m_unknownEncodingData; + void *m_unknownEncodingHandlerData; + void (*m_unknownEncodingRelease)(void *); + PROLOG_STATE m_prologState; + Processor *m_processor; + enum XML_Error m_errorCode; + const char *m_eventPtr; + const char *m_eventEndPtr; + const char *m_positionPtr; + OPEN_INTERNAL_ENTITY *m_openInternalEntities; + int m_defaultExpandInternalEntities; + int m_tagLevel; + ENTITY *m_declEntity; + const XML_Char *m_declNotationName; + const XML_Char *m_declNotationPublicId; + ELEMENT_TYPE *m_declElementType; + ATTRIBUTE_ID *m_declAttributeId; + char m_declAttributeIsCdata; + DTD m_dtd; + TAG *m_tagStack; + TAG *m_freeTagList; + BINDING *m_inheritedBindings; + BINDING *m_freeBindingList; + int m_attsSize; + int m_nSpecifiedAtts; + ATTRIBUTE *m_atts; + POSITION m_position; + STRING_POOL m_tempPool; + STRING_POOL m_temp2Pool; + char *m_groupConnector; + unsigned m_groupSize; + int m_hadExternalDoctype; + XML_Char m_namespaceSeparator; +} Parser; + +#define userData (((Parser *)parser)->m_userData) +#define handlerArg (((Parser *)parser)->m_handlerArg) +#define startElementHandler (((Parser *)parser)->m_startElementHandler) +#define endElementHandler (((Parser *)parser)->m_endElementHandler) +#define characterDataHandler (((Parser *)parser)->m_characterDataHandler) +#define processingInstructionHandler (((Parser *)parser)->m_processingInstructionHandler) +#define commentHandler (((Parser *)parser)->m_commentHandler) +#define startCdataSectionHandler (((Parser *)parser)->m_startCdataSectionHandler) +#define endCdataSectionHandler (((Parser *)parser)->m_endCdataSectionHandler) +#define defaultHandler (((Parser *)parser)->m_defaultHandler) +#define unparsedEntityDeclHandler (((Parser *)parser)->m_unparsedEntityDeclHandler) +#define notationDeclHandler (((Parser *)parser)->m_notationDeclHandler) +#define startNamespaceDeclHandler (((Parser *)parser)->m_startNamespaceDeclHandler) +#define endNamespaceDeclHandler (((Parser *)parser)->m_endNamespaceDeclHandler) +#define notStandaloneHandler (((Parser *)parser)->m_notStandaloneHandler) +#define externalEntityRefHandler (((Parser *)parser)->m_externalEntityRefHandler) +#define externalEntityRefHandlerArg (((Parser *)parser)->m_externalEntityRefHandlerArg) +#define unknownEncodingHandler (((Parser *)parser)->m_unknownEncodingHandler) +#define encoding (((Parser *)parser)->m_encoding) +#define initEncoding (((Parser *)parser)->m_initEncoding) +#define unknownEncodingMem (((Parser *)parser)->m_unknownEncodingMem) +#define unknownEncodingData (((Parser *)parser)->m_unknownEncodingData) +#define unknownEncodingHandlerData \ + (((Parser *)parser)->m_unknownEncodingHandlerData) +#define unknownEncodingRelease (((Parser *)parser)->m_unknownEncodingRelease) +#define protocolEncodingName (((Parser *)parser)->m_protocolEncodingName) +#define ns (((Parser *)parser)->m_ns) +#define prologState (((Parser *)parser)->m_prologState) +#define processor (((Parser *)parser)->m_processor) +#define errorCode (((Parser *)parser)->m_errorCode) +#define eventPtr (((Parser *)parser)->m_eventPtr) +#define eventEndPtr (((Parser *)parser)->m_eventEndPtr) +#define positionPtr (((Parser *)parser)->m_positionPtr) +#define position (((Parser *)parser)->m_position) +#define openInternalEntities (((Parser *)parser)->m_openInternalEntities) +#define defaultExpandInternalEntities (((Parser *)parser)->m_defaultExpandInternalEntities) +#define tagLevel (((Parser *)parser)->m_tagLevel) +#define buffer (((Parser *)parser)->m_buffer) +#define bufferPtr (((Parser *)parser)->m_bufferPtr) +#define bufferEnd (((Parser *)parser)->m_bufferEnd) +#define parseEndByteIndex (((Parser *)parser)->m_parseEndByteIndex) +#define parseEndPtr (((Parser *)parser)->m_parseEndPtr) +#define bufferLim (((Parser *)parser)->m_bufferLim) +#define dataBuf (((Parser *)parser)->m_dataBuf) +#define dataBufEnd (((Parser *)parser)->m_dataBufEnd) +#define dtd (((Parser *)parser)->m_dtd) +#define declEntity (((Parser *)parser)->m_declEntity) +#define declNotationName (((Parser *)parser)->m_declNotationName) +#define declNotationPublicId (((Parser *)parser)->m_declNotationPublicId) +#define declElementType (((Parser *)parser)->m_declElementType) +#define declAttributeId (((Parser *)parser)->m_declAttributeId) +#define declAttributeIsCdata (((Parser *)parser)->m_declAttributeIsCdata) +#define freeTagList (((Parser *)parser)->m_freeTagList) +#define freeBindingList (((Parser *)parser)->m_freeBindingList) +#define inheritedBindings (((Parser *)parser)->m_inheritedBindings) +#define tagStack (((Parser *)parser)->m_tagStack) +#define atts (((Parser *)parser)->m_atts) +#define attsSize (((Parser *)parser)->m_attsSize) +#define nSpecifiedAtts (((Parser *)parser)->m_nSpecifiedAtts) +#define tempPool (((Parser *)parser)->m_tempPool) +#define temp2Pool (((Parser *)parser)->m_temp2Pool) +#define groupConnector (((Parser *)parser)->m_groupConnector) +#define groupSize (((Parser *)parser)->m_groupSize) +#define hadExternalDoctype (((Parser *)parser)->m_hadExternalDoctype) +#define namespaceSeparator (((Parser *)parser)->m_namespaceSeparator) + +#ifdef _MSC_VER +#ifdef _DEBUG +Parser *asParser(XML_Parser parser) +{ + return parser; +} +#endif +#endif + +XML_Parser XML_ParserCreate(const XML_Char *encodingName) +{ + XML_Parser parser = malloc(sizeof(Parser)); + if (!parser) + return parser; + processor = prologInitProcessor; + XmlPrologStateInit(&prologState); + userData = 0; + handlerArg = 0; + startElementHandler = 0; + endElementHandler = 0; + characterDataHandler = 0; + processingInstructionHandler = 0; + commentHandler = 0; + startCdataSectionHandler = 0; + endCdataSectionHandler = 0; + defaultHandler = 0; + unparsedEntityDeclHandler = 0; + notationDeclHandler = 0; + startNamespaceDeclHandler = 0; + endNamespaceDeclHandler = 0; + notStandaloneHandler = 0; + externalEntityRefHandler = 0; + externalEntityRefHandlerArg = parser; + unknownEncodingHandler = 0; + buffer = 0; + bufferPtr = 0; + bufferEnd = 0; + parseEndByteIndex = 0; + parseEndPtr = 0; + bufferLim = 0; + declElementType = 0; + declAttributeId = 0; + declEntity = 0; + declNotationName = 0; + declNotationPublicId = 0; + memset(&position, 0, sizeof(POSITION)); + errorCode = XML_ERROR_NONE; + eventPtr = 0; + eventEndPtr = 0; + positionPtr = 0; + openInternalEntities = 0; + tagLevel = 0; + tagStack = 0; + freeTagList = 0; + freeBindingList = 0; + inheritedBindings = 0; + attsSize = INIT_ATTS_SIZE; + atts = malloc(attsSize * sizeof(ATTRIBUTE)); + nSpecifiedAtts = 0; + dataBuf = malloc(INIT_DATA_BUF_SIZE * sizeof(XML_Char)); + groupSize = 0; + groupConnector = 0; + hadExternalDoctype = 0; + unknownEncodingMem = 0; + unknownEncodingRelease = 0; + unknownEncodingData = 0; + unknownEncodingHandlerData = 0; + namespaceSeparator = '!'; + ns = 0; + poolInit(&tempPool); + poolInit(&temp2Pool); + protocolEncodingName = encodingName ? poolCopyString(&tempPool, encodingName) : 0; + if (!dtdInit(&dtd) || !atts || !dataBuf + || (encodingName && !protocolEncodingName)) { + XML_ParserFree(parser); + return 0; + } + dataBufEnd = dataBuf + INIT_DATA_BUF_SIZE; + XmlInitEncoding(&initEncoding, &encoding, 0); + return parser; +} + +XML_Parser XML_ParserCreateNS(const XML_Char *encodingName, XML_Char nsSep) +{ + static + const XML_Char implicitContext[] = { + XML_T('x'), XML_T('m'), XML_T('l'), XML_T('='), + XML_T('h'), XML_T('t'), XML_T('t'), XML_T('p'), XML_T(':'), + XML_T('/'), XML_T('/'), XML_T('w'), XML_T('w'), XML_T('w'), + XML_T('.'), XML_T('w'), XML_T('3'), + XML_T('.'), XML_T('o'), XML_T('r'), XML_T('g'), + XML_T('/'), XML_T('X'), XML_T('M'), XML_T('L'), + XML_T('/'), XML_T('1'), XML_T('9'), XML_T('9'), XML_T('8'), + XML_T('/'), XML_T('n'), XML_T('a'), XML_T('m'), XML_T('e'), + XML_T('s'), XML_T('p'), XML_T('a'), XML_T('c'), XML_T('e'), + XML_T('\0') + }; + + XML_Parser parser = XML_ParserCreate(encodingName); + if (parser) { + XmlInitEncodingNS(&initEncoding, &encoding, 0); + ns = 1; + namespaceSeparator = nsSep; + } + if (!setContext(parser, implicitContext)) { + XML_ParserFree(parser); + return 0; + } + return parser; +} + +int XML_SetEncoding(XML_Parser parser, const XML_Char *encodingName) +{ + if (!encodingName) + protocolEncodingName = 0; + else { + protocolEncodingName = poolCopyString(&tempPool, encodingName); + if (!protocolEncodingName) + return 0; + } + return 1; +} + +XML_Parser XML_ExternalEntityParserCreate(XML_Parser oldParser, + const XML_Char *context, + const XML_Char *encodingName) +{ + XML_Parser parser = oldParser; + DTD *oldDtd = &dtd; + XML_StartElementHandler oldStartElementHandler = startElementHandler; + XML_EndElementHandler oldEndElementHandler = endElementHandler; + XML_CharacterDataHandler oldCharacterDataHandler = characterDataHandler; + XML_ProcessingInstructionHandler oldProcessingInstructionHandler = processingInstructionHandler; + XML_CommentHandler oldCommentHandler = commentHandler; + XML_StartCdataSectionHandler oldStartCdataSectionHandler = startCdataSectionHandler; + XML_EndCdataSectionHandler oldEndCdataSectionHandler = endCdataSectionHandler; + XML_DefaultHandler oldDefaultHandler = defaultHandler; + XML_StartNamespaceDeclHandler oldStartNamespaceDeclHandler = startNamespaceDeclHandler; + XML_EndNamespaceDeclHandler oldEndNamespaceDeclHandler = endNamespaceDeclHandler; + XML_NotStandaloneHandler oldNotStandaloneHandler = notStandaloneHandler; + XML_ExternalEntityRefHandler oldExternalEntityRefHandler = externalEntityRefHandler; + XML_UnknownEncodingHandler oldUnknownEncodingHandler = unknownEncodingHandler; + void *oldUserData = userData; + void *oldHandlerArg = handlerArg; + int oldDefaultExpandInternalEntities = defaultExpandInternalEntities; + void *oldExternalEntityRefHandlerArg = externalEntityRefHandlerArg; + + parser = (ns + ? XML_ParserCreateNS(encodingName, namespaceSeparator) + : XML_ParserCreate(encodingName)); + if (!parser) + return 0; + startElementHandler = oldStartElementHandler; + endElementHandler = oldEndElementHandler; + characterDataHandler = oldCharacterDataHandler; + processingInstructionHandler = oldProcessingInstructionHandler; + commentHandler = oldCommentHandler; + startCdataSectionHandler = oldStartCdataSectionHandler; + endCdataSectionHandler = oldEndCdataSectionHandler; + defaultHandler = oldDefaultHandler; + startNamespaceDeclHandler = oldStartNamespaceDeclHandler; + endNamespaceDeclHandler = oldEndNamespaceDeclHandler; + notStandaloneHandler = oldNotStandaloneHandler; + externalEntityRefHandler = oldExternalEntityRefHandler; + unknownEncodingHandler = oldUnknownEncodingHandler; + userData = oldUserData; + if (oldUserData == oldHandlerArg) + handlerArg = userData; + else + handlerArg = parser; + if (oldExternalEntityRefHandlerArg != oldParser) + externalEntityRefHandlerArg = oldExternalEntityRefHandlerArg; + defaultExpandInternalEntities = oldDefaultExpandInternalEntities; + if (!dtdCopy(&dtd, oldDtd) || !setContext(parser, context)) { + XML_ParserFree(parser); + return 0; + } + processor = externalEntityInitProcessor; + return parser; +} + +static +void destroyBindings(BINDING *bindings) +{ + for (;;) { + BINDING *b = bindings; + if (!b) + break; + bindings = b->nextTagBinding; + free(b->uri); + free(b); + } +} + +void XML_ParserFree(XML_Parser parser) +{ + for (;;) { + TAG *p; + if (tagStack == 0) { + if (freeTagList == 0) + break; + tagStack = freeTagList; + freeTagList = 0; + } + p = tagStack; + tagStack = tagStack->parent; + free(p->buf); + destroyBindings(p->bindings); + free(p); + } + destroyBindings(freeBindingList); + destroyBindings(inheritedBindings); + poolDestroy(&tempPool); + poolDestroy(&temp2Pool); + dtdDestroy(&dtd); + free((void *)atts); + free(groupConnector); + free(buffer); + free(dataBuf); + free(unknownEncodingMem); + if (unknownEncodingRelease) + unknownEncodingRelease(unknownEncodingData); + free(parser); +} + +void XML_UseParserAsHandlerArg(XML_Parser parser) +{ + handlerArg = parser; +} + +void XML_SetUserData(XML_Parser parser, void *p) +{ + if (handlerArg == userData) + handlerArg = userData = p; + else + userData = p; +} + +int XML_SetBase(XML_Parser parser, const XML_Char *p) +{ + if (p) { + p = poolCopyString(&dtd.pool, p); + if (!p) + return 0; + dtd.base = p; + } + else + dtd.base = 0; + return 1; +} + +const XML_Char *XML_GetBase(XML_Parser parser) +{ + return dtd.base; +} + +int XML_GetSpecifiedAttributeCount(XML_Parser parser) +{ + return nSpecifiedAtts; +} + +void XML_SetElementHandler(XML_Parser parser, + XML_StartElementHandler start, + XML_EndElementHandler end) +{ + startElementHandler = start; + endElementHandler = end; +} + +void XML_SetCharacterDataHandler(XML_Parser parser, + XML_CharacterDataHandler handler) +{ + characterDataHandler = handler; +} + +void XML_SetProcessingInstructionHandler(XML_Parser parser, + XML_ProcessingInstructionHandler handler) +{ + processingInstructionHandler = handler; +} + +void XML_SetCommentHandler(XML_Parser parser, + XML_CommentHandler handler) +{ + commentHandler = handler; +} + +void XML_SetCdataSectionHandler(XML_Parser parser, + XML_StartCdataSectionHandler start, + XML_EndCdataSectionHandler end) +{ + startCdataSectionHandler = start; + endCdataSectionHandler = end; +} + +void XML_SetDefaultHandler(XML_Parser parser, + XML_DefaultHandler handler) +{ + defaultHandler = handler; + defaultExpandInternalEntities = 0; +} + +void XML_SetDefaultHandlerExpand(XML_Parser parser, + XML_DefaultHandler handler) +{ + defaultHandler = handler; + defaultExpandInternalEntities = 1; +} + +void XML_SetUnparsedEntityDeclHandler(XML_Parser parser, + XML_UnparsedEntityDeclHandler handler) +{ + unparsedEntityDeclHandler = handler; +} + +void XML_SetNotationDeclHandler(XML_Parser parser, + XML_NotationDeclHandler handler) +{ + notationDeclHandler = handler; +} + +void XML_SetNamespaceDeclHandler(XML_Parser parser, + XML_StartNamespaceDeclHandler start, + XML_EndNamespaceDeclHandler end) +{ + startNamespaceDeclHandler = start; + endNamespaceDeclHandler = end; +} + +void XML_SetNotStandaloneHandler(XML_Parser parser, + XML_NotStandaloneHandler handler) +{ + notStandaloneHandler = handler; +} + +void XML_SetExternalEntityRefHandler(XML_Parser parser, + XML_ExternalEntityRefHandler handler) +{ + externalEntityRefHandler = handler; +} + +void XML_SetExternalEntityRefHandlerArg(XML_Parser parser, void *arg) +{ + if (arg) + externalEntityRefHandlerArg = arg; + else + externalEntityRefHandlerArg = parser; +} + +void XML_SetUnknownEncodingHandler(XML_Parser parser, + XML_UnknownEncodingHandler handler, + void *data) +{ + unknownEncodingHandler = handler; + unknownEncodingHandlerData = data; +} + +int XML_Parse(XML_Parser parser, const char *s, int len, int isFinal) +{ + if (len == 0) { + if (!isFinal) + return 1; + positionPtr = bufferPtr; + errorCode = processor(parser, bufferPtr, parseEndPtr = bufferEnd, 0); + if (errorCode == XML_ERROR_NONE) + return 1; + eventEndPtr = eventPtr; + return 0; + } + else if (bufferPtr == bufferEnd) { + const char *end; + int nLeftOver; + parseEndByteIndex += len; + positionPtr = s; + if (isFinal) { + errorCode = processor(parser, s, parseEndPtr = s + len, 0); + if (errorCode == XML_ERROR_NONE) + return 1; + eventEndPtr = eventPtr; + return 0; + } + errorCode = processor(parser, s, parseEndPtr = s + len, &end); + if (errorCode != XML_ERROR_NONE) { + eventEndPtr = eventPtr; + return 0; + } + XmlUpdatePosition(encoding, positionPtr, end, &position); + nLeftOver = s + len - end; + if (nLeftOver) { + if (buffer == 0 || nLeftOver > bufferLim - buffer) { + /* FIXME avoid integer overflow */ + buffer = buffer == 0 ? malloc(len * 2) : realloc(buffer, len * 2); + if (!buffer) { + errorCode = XML_ERROR_NO_MEMORY; + eventPtr = eventEndPtr = 0; + return 0; + } + bufferLim = buffer + len * 2; + } + memcpy(buffer, end, nLeftOver); + bufferPtr = buffer; + bufferEnd = buffer + nLeftOver; + } + return 1; + } + else { + memcpy(XML_GetBuffer(parser, len), s, len); + return XML_ParseBuffer(parser, len, isFinal); + } +} + +int XML_ParseBuffer(XML_Parser parser, int len, int isFinal) +{ + const char *start = bufferPtr; + positionPtr = start; + bufferEnd += len; + parseEndByteIndex += len; + errorCode = processor(parser, start, parseEndPtr = bufferEnd, + isFinal ? (const char **)0 : &bufferPtr); + if (errorCode == XML_ERROR_NONE) { + if (!isFinal) + XmlUpdatePosition(encoding, positionPtr, bufferPtr, &position); + return 1; + } + else { + eventEndPtr = eventPtr; + return 0; + } +} + +void *XML_GetBuffer(XML_Parser parser, int len) +{ + if (len > bufferLim - bufferEnd) { + /* FIXME avoid integer overflow */ + int neededSize = len + (bufferEnd - bufferPtr); + if (neededSize <= bufferLim - buffer) { + memmove(buffer, bufferPtr, bufferEnd - bufferPtr); + bufferEnd = buffer + (bufferEnd - bufferPtr); + bufferPtr = buffer; + } + else { + char *newBuf; + int bufferSize = bufferLim - bufferPtr; + if (bufferSize == 0) + bufferSize = INIT_BUFFER_SIZE; + do { + bufferSize *= 2; + } while (bufferSize < neededSize); + newBuf = malloc(bufferSize); + if (newBuf == 0) { + errorCode = XML_ERROR_NO_MEMORY; + return 0; + } + bufferLim = newBuf + bufferSize; + if (bufferPtr) { + memcpy(newBuf, bufferPtr, bufferEnd - bufferPtr); + free(buffer); + } + bufferEnd = newBuf + (bufferEnd - bufferPtr); + bufferPtr = buffer = newBuf; + } + } + return bufferEnd; +} + +enum XML_Error XML_GetErrorCode(XML_Parser parser) +{ + return errorCode; +} + +long XML_GetCurrentByteIndex(XML_Parser parser) +{ + if (eventPtr) + return parseEndByteIndex - (parseEndPtr - eventPtr); + return -1; +} + +int XML_GetCurrentByteCount(XML_Parser parser) +{ + if (eventEndPtr && eventPtr) + return eventEndPtr - eventPtr; + return 0; +} + +int XML_GetCurrentLineNumber(XML_Parser parser) +{ + if (eventPtr) { + XmlUpdatePosition(encoding, positionPtr, eventPtr, &position); + positionPtr = eventPtr; + } + return position.lineNumber + 1; +} + +int XML_GetCurrentColumnNumber(XML_Parser parser) +{ + if (eventPtr) { + XmlUpdatePosition(encoding, positionPtr, eventPtr, &position); + positionPtr = eventPtr; + } + return position.columnNumber; +} + +void XML_DefaultCurrent(XML_Parser parser) +{ + if (defaultHandler) { + if (openInternalEntities) + reportDefault(parser, + ns ? XmlGetInternalEncodingNS() : XmlGetInternalEncoding(), + openInternalEntities->internalEventPtr, + openInternalEntities->internalEventEndPtr); + else + reportDefault(parser, encoding, eventPtr, eventEndPtr); + } +} + +const XML_LChar *XML_ErrorString(int code) +{ + static const XML_LChar *message[] = { + 0, + XML_T("out of memory"), + XML_T("syntax error"), + XML_T("no element found"), + XML_T("not well-formed"), + XML_T("unclosed token"), + XML_T("unclosed token"), + XML_T("mismatched tag"), + XML_T("duplicate attribute"), + XML_T("junk after document element"), + XML_T("illegal parameter entity reference"), + XML_T("undefined entity"), + XML_T("recursive entity reference"), + XML_T("asynchronous entity"), + XML_T("reference to invalid character number"), + XML_T("reference to binary entity"), + XML_T("reference to external entity in attribute"), + XML_T("xml processing instruction not at start of external entity"), + XML_T("unknown encoding"), + XML_T("encoding specified in XML declaration is incorrect"), + XML_T("unclosed CDATA section"), + XML_T("error in processing external entity reference"), + XML_T("document is not standalone") + }; + if (code > 0 && code < sizeof(message)/sizeof(message[0])) + return message[code]; + return 0; +} + +static +enum XML_Error contentProcessor(XML_Parser parser, + const char *start, + const char *end, + const char **endPtr) +{ + return doContent(parser, 0, encoding, start, end, endPtr); +} + +static +enum XML_Error externalEntityInitProcessor(XML_Parser parser, + const char *start, + const char *end, + const char **endPtr) +{ + enum XML_Error result = initializeEncoding(parser); + if (result != XML_ERROR_NONE) + return result; + processor = externalEntityInitProcessor2; + return externalEntityInitProcessor2(parser, start, end, endPtr); +} + +static +enum XML_Error externalEntityInitProcessor2(XML_Parser parser, + const char *start, + const char *end, + const char **endPtr) +{ + const char *next; + int tok = XmlContentTok(encoding, start, end, &next); + switch (tok) { + case XML_TOK_BOM: + start = next; + break; + case XML_TOK_PARTIAL: + if (endPtr) { + *endPtr = start; + return XML_ERROR_NONE; + } + eventPtr = start; + return XML_ERROR_UNCLOSED_TOKEN; + case XML_TOK_PARTIAL_CHAR: + if (endPtr) { + *endPtr = start; + return XML_ERROR_NONE; + } + eventPtr = start; + return XML_ERROR_PARTIAL_CHAR; + } + processor = externalEntityInitProcessor3; + return externalEntityInitProcessor3(parser, start, end, endPtr); +} + +static +enum XML_Error externalEntityInitProcessor3(XML_Parser parser, + const char *start, + const char *end, + const char **endPtr) +{ + const char *next; + int tok = XmlContentTok(encoding, start, end, &next); + switch (tok) { + case XML_TOK_XML_DECL: + { + enum XML_Error result = processXmlDecl(parser, 1, start, next); + if (result != XML_ERROR_NONE) + return result; + start = next; + } + break; + case XML_TOK_PARTIAL: + if (endPtr) { + *endPtr = start; + return XML_ERROR_NONE; + } + eventPtr = start; + return XML_ERROR_UNCLOSED_TOKEN; + case XML_TOK_PARTIAL_CHAR: + if (endPtr) { + *endPtr = start; + return XML_ERROR_NONE; + } + eventPtr = start; + return XML_ERROR_PARTIAL_CHAR; + } + processor = externalEntityContentProcessor; + tagLevel = 1; + return doContent(parser, 1, encoding, start, end, endPtr); +} + +static +enum XML_Error externalEntityContentProcessor(XML_Parser parser, + const char *start, + const char *end, + const char **endPtr) +{ + return doContent(parser, 1, encoding, start, end, endPtr); +} + +static enum XML_Error +doContent(XML_Parser parser, + int startTagLevel, + const ENCODING *enc, + const char *s, + const char *end, + const char **nextPtr) +{ + const ENCODING *internalEnc = ns ? XmlGetInternalEncodingNS() : XmlGetInternalEncoding(); + const char **eventPP; + const char **eventEndPP; + if (enc == encoding) { + eventPP = &eventPtr; + eventEndPP = &eventEndPtr; + } + else { + eventPP = &(openInternalEntities->internalEventPtr); + eventEndPP = &(openInternalEntities->internalEventEndPtr); + } + *eventPP = s; + for (;;) { + const char *next = s; /* XmlContentTok doesn't always set the last arg */ + int tok = XmlContentTok(enc, s, end, &next); + *eventEndPP = next; + switch (tok) { + case XML_TOK_TRAILING_CR: + if (nextPtr) { + *nextPtr = s; + return XML_ERROR_NONE; + } + *eventEndPP = end; + if (characterDataHandler) { + XML_Char c = 0xA; + characterDataHandler(handlerArg, &c, 1); + } + else if (defaultHandler) + reportDefault(parser, enc, s, end); + if (startTagLevel == 0) + return XML_ERROR_NO_ELEMENTS; + if (tagLevel != startTagLevel) + return XML_ERROR_ASYNC_ENTITY; + return XML_ERROR_NONE; + case XML_TOK_NONE: + if (nextPtr) { + *nextPtr = s; + return XML_ERROR_NONE; + } + if (startTagLevel > 0) { + if (tagLevel != startTagLevel) + return XML_ERROR_ASYNC_ENTITY; + return XML_ERROR_NONE; + } + return XML_ERROR_NO_ELEMENTS; + case XML_TOK_INVALID: + *eventPP = next; + return XML_ERROR_INVALID_TOKEN; + case XML_TOK_PARTIAL: + if (nextPtr) { + *nextPtr = s; + return XML_ERROR_NONE; + } + return XML_ERROR_UNCLOSED_TOKEN; + case XML_TOK_PARTIAL_CHAR: + if (nextPtr) { + *nextPtr = s; + return XML_ERROR_NONE; + } + return XML_ERROR_PARTIAL_CHAR; + case XML_TOK_ENTITY_REF: + { + const XML_Char *name; + ENTITY *entity; + XML_Char ch = XmlPredefinedEntityName(enc, + s + enc->minBytesPerChar, + next - enc->minBytesPerChar); + if (ch) { + if (characterDataHandler) + characterDataHandler(handlerArg, &ch, 1); + else if (defaultHandler) + reportDefault(parser, enc, s, next); + break; + } + name = poolStoreString(&dtd.pool, enc, + s + enc->minBytesPerChar, + next - enc->minBytesPerChar); + if (!name) + return XML_ERROR_NO_MEMORY; + entity = (ENTITY *)lookup(&dtd.generalEntities, name, 0); + poolDiscard(&dtd.pool); + if (!entity) { + if (dtd.complete || dtd.standalone) + return XML_ERROR_UNDEFINED_ENTITY; + if (defaultHandler) + reportDefault(parser, enc, s, next); + break; + } + if (entity->open) + return XML_ERROR_RECURSIVE_ENTITY_REF; + if (entity->notation) + return XML_ERROR_BINARY_ENTITY_REF; + if (entity) { + if (entity->textPtr) { + enum XML_Error result; + OPEN_INTERNAL_ENTITY openEntity; + if (defaultHandler && !defaultExpandInternalEntities) { + reportDefault(parser, enc, s, next); + break; + } + entity->open = 1; + openEntity.next = openInternalEntities; + openInternalEntities = &openEntity; + openEntity.entity = entity; + openEntity.internalEventPtr = 0; + openEntity.internalEventEndPtr = 0; + result = doContent(parser, + tagLevel, + internalEnc, + (char *)entity->textPtr, + (char *)(entity->textPtr + entity->textLen), + 0); + entity->open = 0; + openInternalEntities = openEntity.next; + if (result) + return result; + } + else if (externalEntityRefHandler) { + const XML_Char *context; + entity->open = 1; + context = getContext(parser); + entity->open = 0; + if (!context) + return XML_ERROR_NO_MEMORY; + if (!externalEntityRefHandler(externalEntityRefHandlerArg, + context, + dtd.base, + entity->systemId, + entity->publicId)) + return XML_ERROR_EXTERNAL_ENTITY_HANDLING; + poolDiscard(&tempPool); + } + else if (defaultHandler) + reportDefault(parser, enc, s, next); + } + break; + } + case XML_TOK_START_TAG_WITH_ATTS: + if (!startElementHandler) { + enum XML_Error result = storeAtts(parser, enc, s, 0, 0); + if (result) + return result; + } + /* fall through */ + case XML_TOK_START_TAG_NO_ATTS: + { + TAG *tag; + if (freeTagList) { + tag = freeTagList; + freeTagList = freeTagList->parent; + } + else { + tag = malloc(sizeof(TAG)); + if (!tag) + return XML_ERROR_NO_MEMORY; + tag->buf = malloc(INIT_TAG_BUF_SIZE); + if (!tag->buf) + return XML_ERROR_NO_MEMORY; + tag->bufEnd = tag->buf + INIT_TAG_BUF_SIZE; + } + tag->bindings = 0; + tag->parent = tagStack; + tagStack = tag; + tag->name.localPart = 0; + tag->rawName = s + enc->minBytesPerChar; + tag->rawNameLength = XmlNameLength(enc, tag->rawName); + if (nextPtr) { + /* Need to guarantee that: + tag->buf + ROUND_UP(tag->rawNameLength, sizeof(XML_Char)) <= tag->bufEnd - sizeof(XML_Char) */ + if (tag->rawNameLength + (int)(sizeof(XML_Char) - 1) + (int)sizeof(XML_Char) > tag->bufEnd - tag->buf) { + int bufSize = tag->rawNameLength * 4; + bufSize = ROUND_UP(bufSize, sizeof(XML_Char)); + tag->buf = realloc(tag->buf, bufSize); + if (!tag->buf) + return XML_ERROR_NO_MEMORY; + tag->bufEnd = tag->buf + bufSize; + } + memcpy(tag->buf, tag->rawName, tag->rawNameLength); + tag->rawName = tag->buf; + } + ++tagLevel; + if (startElementHandler) { + enum XML_Error result; + XML_Char *toPtr; + for (;;) { + const char *rawNameEnd = tag->rawName + tag->rawNameLength; + const char *fromPtr = tag->rawName; + int bufSize; + if (nextPtr) + toPtr = (XML_Char *)(tag->buf + ROUND_UP(tag->rawNameLength, sizeof(XML_Char))); + else + toPtr = (XML_Char *)tag->buf; + tag->name.str = toPtr; + XmlConvert(enc, + &fromPtr, rawNameEnd, + (ICHAR **)&toPtr, (ICHAR *)tag->bufEnd - 1); + if (fromPtr == rawNameEnd) + break; + bufSize = (tag->bufEnd - tag->buf) << 1; + tag->buf = realloc(tag->buf, bufSize); + if (!tag->buf) + return XML_ERROR_NO_MEMORY; + tag->bufEnd = tag->buf + bufSize; + if (nextPtr) + tag->rawName = tag->buf; + } + *toPtr = XML_T('\0'); + result = storeAtts(parser, enc, s, &(tag->name), &(tag->bindings)); + if (result) + return result; + startElementHandler(handlerArg, tag->name.str, (const XML_Char **)atts); + poolClear(&tempPool); + } + else { + tag->name.str = 0; + if (defaultHandler) + reportDefault(parser, enc, s, next); + } + break; + } + case XML_TOK_EMPTY_ELEMENT_WITH_ATTS: + if (!startElementHandler) { + enum XML_Error result = storeAtts(parser, enc, s, 0, 0); + if (result) + return result; + } + /* fall through */ + case XML_TOK_EMPTY_ELEMENT_NO_ATTS: + if (startElementHandler || endElementHandler) { + const char *rawName = s + enc->minBytesPerChar; + enum XML_Error result; + BINDING *bindings = 0; + TAG_NAME name; + name.str = poolStoreString(&tempPool, enc, rawName, + rawName + XmlNameLength(enc, rawName)); + if (!name.str) + return XML_ERROR_NO_MEMORY; + poolFinish(&tempPool); + result = storeAtts(parser, enc, s, &name, &bindings); + if (result) + return result; + poolFinish(&tempPool); + if (startElementHandler) + startElementHandler(handlerArg, name.str, (const XML_Char **)atts); + if (endElementHandler) { + if (startElementHandler) + *eventPP = *eventEndPP; + endElementHandler(handlerArg, name.str); + } + poolClear(&tempPool); + while (bindings) { + BINDING *b = bindings; + if (endNamespaceDeclHandler) + endNamespaceDeclHandler(handlerArg, b->prefix->name); + bindings = bindings->nextTagBinding; + b->nextTagBinding = freeBindingList; + freeBindingList = b; + b->prefix->binding = b->prevPrefixBinding; + } + } + else if (defaultHandler) + reportDefault(parser, enc, s, next); + if (tagLevel == 0) + return epilogProcessor(parser, next, end, nextPtr); + break; + case XML_TOK_END_TAG: + if (tagLevel == startTagLevel) + return XML_ERROR_ASYNC_ENTITY; + else { + int len; + const char *rawName; + TAG *tag = tagStack; + tagStack = tag->parent; + tag->parent = freeTagList; + freeTagList = tag; + rawName = s + enc->minBytesPerChar*2; + len = XmlNameLength(enc, rawName); + if (len != tag->rawNameLength + || memcmp(tag->rawName, rawName, len) != 0) { + *eventPP = rawName; + return XML_ERROR_TAG_MISMATCH; + } + --tagLevel; + if (endElementHandler && tag->name.str) { + if (tag->name.localPart) { + XML_Char *to = (XML_Char *)tag->name.str + tag->name.uriLen; + const XML_Char *from = tag->name.localPart; + while ((*to++ = *from++) != 0) + ; + } + endElementHandler(handlerArg, tag->name.str); + } + else if (defaultHandler) + reportDefault(parser, enc, s, next); + while (tag->bindings) { + BINDING *b = tag->bindings; + if (endNamespaceDeclHandler) + endNamespaceDeclHandler(handlerArg, b->prefix->name); + tag->bindings = tag->bindings->nextTagBinding; + b->nextTagBinding = freeBindingList; + freeBindingList = b; + b->prefix->binding = b->prevPrefixBinding; + } + if (tagLevel == 0) + return epilogProcessor(parser, next, end, nextPtr); + } + break; + case XML_TOK_CHAR_REF: + { + int n = XmlCharRefNumber(enc, s); + if (n < 0) + return XML_ERROR_BAD_CHAR_REF; + if (characterDataHandler) { + XML_Char buf[XML_ENCODE_MAX]; + characterDataHandler(handlerArg, buf, XmlEncode(n, (ICHAR *)buf)); + } + else if (defaultHandler) + reportDefault(parser, enc, s, next); + } + break; + case XML_TOK_XML_DECL: + return XML_ERROR_MISPLACED_XML_PI; + case XML_TOK_DATA_NEWLINE: + if (characterDataHandler) { + XML_Char c = 0xA; + characterDataHandler(handlerArg, &c, 1); + } + else if (defaultHandler) + reportDefault(parser, enc, s, next); + break; + case XML_TOK_CDATA_SECT_OPEN: + { + enum XML_Error result; + if (startCdataSectionHandler) + startCdataSectionHandler(handlerArg); +#if 0 + /* Suppose you doing a transformation on a document that involves + changing only the character data. You set up a defaultHandler + and a characterDataHandler. The defaultHandler simply copies + characters through. The characterDataHandler does the transformation + and writes the characters out escaping them as necessary. This case + will fail to work if we leave out the following two lines (because & + and < inside CDATA sections will be incorrectly escaped). + + However, now we have a start/endCdataSectionHandler, so it seems + easier to let the user deal with this. */ + + else if (characterDataHandler) + characterDataHandler(handlerArg, dataBuf, 0); +#endif + else if (defaultHandler) + reportDefault(parser, enc, s, next); + result = doCdataSection(parser, enc, &next, end, nextPtr); + if (!next) { + processor = cdataSectionProcessor; + return result; + } + } + break; + case XML_TOK_TRAILING_RSQB: + if (nextPtr) { + *nextPtr = s; + return XML_ERROR_NONE; + } + if (characterDataHandler) { + if (MUST_CONVERT(enc, s)) { + ICHAR *dataPtr = (ICHAR *)dataBuf; + XmlConvert(enc, &s, end, &dataPtr, (ICHAR *)dataBufEnd); + characterDataHandler(handlerArg, dataBuf, dataPtr - (ICHAR *)dataBuf); + } + else + characterDataHandler(handlerArg, + (XML_Char *)s, + (XML_Char *)end - (XML_Char *)s); + } + else if (defaultHandler) + reportDefault(parser, enc, s, end); + if (startTagLevel == 0) { + *eventPP = end; + return XML_ERROR_NO_ELEMENTS; + } + if (tagLevel != startTagLevel) { + *eventPP = end; + return XML_ERROR_ASYNC_ENTITY; + } + return XML_ERROR_NONE; + case XML_TOK_DATA_CHARS: + if (characterDataHandler) { + if (MUST_CONVERT(enc, s)) { + for (;;) { + ICHAR *dataPtr = (ICHAR *)dataBuf; + XmlConvert(enc, &s, next, &dataPtr, (ICHAR *)dataBufEnd); + *eventEndPP = s; + characterDataHandler(handlerArg, dataBuf, dataPtr - (ICHAR *)dataBuf); + if (s == next) + break; + *eventPP = s; + } + } + else + characterDataHandler(handlerArg, + (XML_Char *)s, + (XML_Char *)next - (XML_Char *)s); + } + else if (defaultHandler) + reportDefault(parser, enc, s, next); + break; + case XML_TOK_PI: + if (!reportProcessingInstruction(parser, enc, s, next)) + return XML_ERROR_NO_MEMORY; + break; + case XML_TOK_COMMENT: + if (!reportComment(parser, enc, s, next)) + return XML_ERROR_NO_MEMORY; + break; + default: + if (defaultHandler) + reportDefault(parser, enc, s, next); + break; + } + *eventPP = s = next; + } + /* not reached */ +} + +/* If tagNamePtr is non-null, build a real list of attributes, +otherwise just check the attributes for well-formedness. */ + +static enum XML_Error storeAtts(XML_Parser parser, const ENCODING *enc, + const char *s, TAG_NAME *tagNamePtr, + BINDING **bindingsPtr) +{ + ELEMENT_TYPE *elementType = 0; + int nDefaultAtts = 0; + const XML_Char **appAtts; + int attIndex = 0; + int i; + int n; + int nPrefixes = 0; + BINDING *binding; + const XML_Char *localPart; + + if (tagNamePtr) { + elementType = (ELEMENT_TYPE *)lookup(&dtd.elementTypes, tagNamePtr->str, 0); + if (!elementType) { + tagNamePtr->str = poolCopyString(&dtd.pool, tagNamePtr->str); + if (!tagNamePtr->str) + return XML_ERROR_NO_MEMORY; + elementType = (ELEMENT_TYPE *)lookup(&dtd.elementTypes, tagNamePtr->str, sizeof(ELEMENT_TYPE)); + if (!elementType) + return XML_ERROR_NO_MEMORY; + if (ns && !setElementTypePrefix(parser, elementType)) + return XML_ERROR_NO_MEMORY; + } + nDefaultAtts = elementType->nDefaultAtts; + } + n = XmlGetAttributes(enc, s, attsSize, atts); + if (n + nDefaultAtts > attsSize) { + int oldAttsSize = attsSize; + attsSize = n + nDefaultAtts + INIT_ATTS_SIZE; + atts = realloc((void *)atts, attsSize * sizeof(ATTRIBUTE)); + if (!atts) + return XML_ERROR_NO_MEMORY; + if (n > oldAttsSize) + XmlGetAttributes(enc, s, n, atts); + } + appAtts = (const XML_Char **)atts; + for (i = 0; i < n; i++) { + ATTRIBUTE_ID *attId = getAttributeId(parser, enc, atts[i].name, + atts[i].name + + XmlNameLength(enc, atts[i].name)); + if (!attId) + return XML_ERROR_NO_MEMORY; + if ((attId->name)[-1]) { + if (enc == encoding) + eventPtr = atts[i].name; + return XML_ERROR_DUPLICATE_ATTRIBUTE; + } + (attId->name)[-1] = 1; + appAtts[attIndex++] = attId->name; + if (!atts[i].normalized) { + enum XML_Error result; + int isCdata = 1; + + if (attId->maybeTokenized) { + int j; + for (j = 0; j < nDefaultAtts; j++) { + if (attId == elementType->defaultAtts[j].id) { + isCdata = elementType->defaultAtts[j].isCdata; + break; + } + } + } + + result = storeAttributeValue(parser, enc, isCdata, + atts[i].valuePtr, atts[i].valueEnd, + &tempPool); + if (result) + return result; + if (tagNamePtr) { + appAtts[attIndex] = poolStart(&tempPool); + poolFinish(&tempPool); + } + else + poolDiscard(&tempPool); + } + else if (tagNamePtr) { + appAtts[attIndex] = poolStoreString(&tempPool, enc, atts[i].valuePtr, atts[i].valueEnd); + if (appAtts[attIndex] == 0) + return XML_ERROR_NO_MEMORY; + poolFinish(&tempPool); + } + if (attId->prefix && tagNamePtr) { + if (attId->xmlns) { + if (!addBinding(parser, attId->prefix, attId, appAtts[attIndex], bindingsPtr)) + return XML_ERROR_NO_MEMORY; + --attIndex; + } + else { + attIndex++; + nPrefixes++; + (attId->name)[-1] = 2; + } + } + else + attIndex++; + } + nSpecifiedAtts = attIndex; + if (tagNamePtr) { + int j; + for (j = 0; j < nDefaultAtts; j++) { + const DEFAULT_ATTRIBUTE *da = elementType->defaultAtts + j; + if (!(da->id->name)[-1] && da->value) { + if (da->id->prefix) { + if (da->id->xmlns) { + if (!addBinding(parser, da->id->prefix, da->id, da->value, bindingsPtr)) + return XML_ERROR_NO_MEMORY; + } + else { + (da->id->name)[-1] = 2; + nPrefixes++; + appAtts[attIndex++] = da->id->name; + appAtts[attIndex++] = da->value; + } + } + else { + (da->id->name)[-1] = 1; + appAtts[attIndex++] = da->id->name; + appAtts[attIndex++] = da->value; + } + } + } + appAtts[attIndex] = 0; + } + i = 0; + if (nPrefixes) { + for (; i < attIndex; i += 2) { + if (appAtts[i][-1] == 2) { + ATTRIBUTE_ID *id; + ((XML_Char *)(appAtts[i]))[-1] = 0; + id = (ATTRIBUTE_ID *)lookup(&dtd.attributeIds, appAtts[i], 0); + if (id->prefix->binding) { + int j; + const BINDING *b = id->prefix->binding; + const XML_Char *ss = appAtts[i]; + for (j = 0; j < b->uriLen; j++) { + if (!poolAppendChar(&tempPool, b->uri[j])) + return XML_ERROR_NO_MEMORY; + } + while (*ss++ != ':') + ; + do { + if (!poolAppendChar(&tempPool, *ss)) + return XML_ERROR_NO_MEMORY; + } while (*ss++); + appAtts[i] = poolStart(&tempPool); + poolFinish(&tempPool); + } + if (!--nPrefixes) + break; + } + else + ((XML_Char *)(appAtts[i]))[-1] = 0; + } + } + for (; i < attIndex; i += 2) + ((XML_Char *)(appAtts[i]))[-1] = 0; + if (!tagNamePtr) + return XML_ERROR_NONE; + for (binding = *bindingsPtr; binding; binding = binding->nextTagBinding) + binding->attId->name[-1] = 0; + if (elementType->prefix) { + binding = elementType->prefix->binding; + if (!binding) + return XML_ERROR_NONE; + localPart = tagNamePtr->str; + while (*localPart++ != XML_T(':')) + ; + } + else if (dtd.defaultPrefix.binding) { + binding = dtd.defaultPrefix.binding; + localPart = tagNamePtr->str; + } + else + return XML_ERROR_NONE; + tagNamePtr->localPart = localPart; + tagNamePtr->uriLen = binding->uriLen; + i = binding->uriLen; + do { + if (i == binding->uriAlloc) { + binding->uri = realloc(binding->uri, binding->uriAlloc *= 2); + if (!binding->uri) + return XML_ERROR_NO_MEMORY; + } + binding->uri[i++] = *localPart; + } while (*localPart++); + tagNamePtr->str = binding->uri; + return XML_ERROR_NONE; +} + +static +int addBinding(XML_Parser parser, PREFIX *prefix, const ATTRIBUTE_ID *attId, const XML_Char *uri, BINDING **bindingsPtr) +{ + BINDING *b; + int len; + for (len = 0; uri[len]; len++) + ; + if (namespaceSeparator) + len++; + if (freeBindingList) { + b = freeBindingList; + if (len > b->uriAlloc) { + b->uri = realloc(b->uri, len + EXPAND_SPARE); + if (!b->uri) + return 0; + b->uriAlloc = len + EXPAND_SPARE; + } + freeBindingList = b->nextTagBinding; + } + else { + b = malloc(sizeof(BINDING)); + if (!b) + return 0; + b->uri = malloc(sizeof(XML_Char) * len + EXPAND_SPARE); + if (!b->uri) { + free(b); + return 0; + } + b->uriAlloc = len; + } + b->uriLen = len; + memcpy(b->uri, uri, len * sizeof(XML_Char)); + if (namespaceSeparator) + b->uri[len - 1] = namespaceSeparator; + b->prefix = prefix; + b->attId = attId; + b->prevPrefixBinding = prefix->binding; + if (*uri == XML_T('\0') && prefix == &dtd.defaultPrefix) + prefix->binding = 0; + else + prefix->binding = b; + b->nextTagBinding = *bindingsPtr; + *bindingsPtr = b; + if (startNamespaceDeclHandler) + startNamespaceDeclHandler(handlerArg, prefix->name, + prefix->binding ? uri : 0); + return 1; +} + +/* The idea here is to avoid using stack for each CDATA section when +the whole file is parsed with one call. */ + +static +enum XML_Error cdataSectionProcessor(XML_Parser parser, + const char *start, + const char *end, + const char **endPtr) +{ + enum XML_Error result = doCdataSection(parser, encoding, &start, end, endPtr); + if (start) { + processor = contentProcessor; + return contentProcessor(parser, start, end, endPtr); + } + return result; +} + +/* startPtr gets set to non-null is the section is closed, and to null if +the section is not yet closed. */ + +static +enum XML_Error doCdataSection(XML_Parser parser, + const ENCODING *enc, + const char **startPtr, + const char *end, + const char **nextPtr) +{ + const char *s = *startPtr; + const char **eventPP; + const char **eventEndPP; + if (enc == encoding) { + eventPP = &eventPtr; + *eventPP = s; + eventEndPP = &eventEndPtr; + } + else { + eventPP = &(openInternalEntities->internalEventPtr); + eventEndPP = &(openInternalEntities->internalEventEndPtr); + } + *eventPP = s; + *startPtr = 0; + for (;;) { + const char *next; + int tok = XmlCdataSectionTok(enc, s, end, &next); + *eventEndPP = next; + switch (tok) { + case XML_TOK_CDATA_SECT_CLOSE: + if (endCdataSectionHandler) + endCdataSectionHandler(handlerArg); +#if 0 + /* see comment under XML_TOK_CDATA_SECT_OPEN */ + else if (characterDataHandler) + characterDataHandler(handlerArg, dataBuf, 0); +#endif + else if (defaultHandler) + reportDefault(parser, enc, s, next); + *startPtr = next; + return XML_ERROR_NONE; + case XML_TOK_DATA_NEWLINE: + if (characterDataHandler) { + XML_Char c = 0xA; + characterDataHandler(handlerArg, &c, 1); + } + else if (defaultHandler) + reportDefault(parser, enc, s, next); + break; + case XML_TOK_DATA_CHARS: + if (characterDataHandler) { + if (MUST_CONVERT(enc, s)) { + for (;;) { + ICHAR *dataPtr = (ICHAR *)dataBuf; + XmlConvert(enc, &s, next, &dataPtr, (ICHAR *)dataBufEnd); + *eventEndPP = next; + characterDataHandler(handlerArg, dataBuf, dataPtr - (ICHAR *)dataBuf); + if (s == next) + break; + *eventPP = s; + } + } + else + characterDataHandler(handlerArg, + (XML_Char *)s, + (XML_Char *)next - (XML_Char *)s); + } + else if (defaultHandler) + reportDefault(parser, enc, s, next); + break; + case XML_TOK_INVALID: + *eventPP = next; + return XML_ERROR_INVALID_TOKEN; + case XML_TOK_PARTIAL_CHAR: + if (nextPtr) { + *nextPtr = s; + return XML_ERROR_NONE; + } + return XML_ERROR_PARTIAL_CHAR; + case XML_TOK_PARTIAL: + case XML_TOK_NONE: + if (nextPtr) { + *nextPtr = s; + return XML_ERROR_NONE; + } + return XML_ERROR_UNCLOSED_CDATA_SECTION; + default: + abort(); + } + *eventPP = s = next; + } + /* not reached */ +} + +static enum XML_Error +initializeEncoding(XML_Parser parser) +{ + const char *s; +#ifdef XML_UNICODE + char encodingBuf[128]; + if (!protocolEncodingName) + s = 0; + else { + int i; + for (i = 0; protocolEncodingName[i]; i++) { + if (i == sizeof(encodingBuf) - 1 + || protocolEncodingName[i] >= 0x80 + || protocolEncodingName[i] < 0) { + encodingBuf[0] = '\0'; + break; + } + encodingBuf[i] = (char)protocolEncodingName[i]; + } + encodingBuf[i] = '\0'; + s = encodingBuf; + } +#else + s = protocolEncodingName; +#endif + if ((ns ? XmlInitEncodingNS : XmlInitEncoding)(&initEncoding, &encoding, s)) + return XML_ERROR_NONE; + return handleUnknownEncoding(parser, protocolEncodingName); +} + +static enum XML_Error +processXmlDecl(XML_Parser parser, int isGeneralTextEntity, + const char *s, const char *next) +{ + const char *encodingName = 0; + const ENCODING *newEncoding = 0; + const char *version; + int standalone = -1; + if (!(ns + ? XmlParseXmlDeclNS + : XmlParseXmlDecl)(isGeneralTextEntity, + encoding, + s, + next, + &eventPtr, + &version, + &encodingName, + &newEncoding, + &standalone)) + return XML_ERROR_SYNTAX; + if (!isGeneralTextEntity && standalone == 1) + dtd.standalone = 1; + if (defaultHandler) + reportDefault(parser, encoding, s, next); + if (!protocolEncodingName) { + if (newEncoding) { + if (newEncoding->minBytesPerChar != encoding->minBytesPerChar) { + eventPtr = encodingName; + return XML_ERROR_INCORRECT_ENCODING; + } + encoding = newEncoding; + } + else if (encodingName) { + enum XML_Error result; + const XML_Char *ss = poolStoreString(&tempPool, + encoding, + encodingName, + encodingName + + XmlNameLength(encoding, encodingName)); + if (!ss) + return XML_ERROR_NO_MEMORY; + result = handleUnknownEncoding(parser, ss); + poolDiscard(&tempPool); + if (result == XML_ERROR_UNKNOWN_ENCODING) + eventPtr = encodingName; + return result; + } + } + return XML_ERROR_NONE; +} + +static enum XML_Error +handleUnknownEncoding(XML_Parser parser, const XML_Char *encodingName) +{ + if (unknownEncodingHandler) { + XML_Encoding info; + int i; + for (i = 0; i < 256; i++) + info.map[i] = -1; + info.convert = 0; + info.data = 0; + info.release = 0; + if (unknownEncodingHandler(unknownEncodingHandlerData, encodingName, &info)) { + ENCODING *enc; + unknownEncodingMem = malloc(XmlSizeOfUnknownEncoding()); + if (!unknownEncodingMem) { + if (info.release) + info.release(info.data); + return XML_ERROR_NO_MEMORY; + } + enc = (ns + ? XmlInitUnknownEncodingNS + : XmlInitUnknownEncoding)(unknownEncodingMem, + info.map, + info.convert, + info.data); + if (enc) { + unknownEncodingData = info.data; + unknownEncodingRelease = info.release; + encoding = enc; + return XML_ERROR_NONE; + } + } + if (info.release) + info.release(info.data); + } + return XML_ERROR_UNKNOWN_ENCODING; +} + +static enum XML_Error +prologInitProcessor(XML_Parser parser, + const char *s, + const char *end, + const char **nextPtr) +{ + enum XML_Error result = initializeEncoding(parser); + if (result != XML_ERROR_NONE) + return result; + processor = prologProcessor; + return prologProcessor(parser, s, end, nextPtr); +} + +static enum XML_Error +prologProcessor(XML_Parser parser, + const char *s, + const char *end, + const char **nextPtr) +{ + for (;;) { + const char *next; + int tok = XmlPrologTok(encoding, s, end, &next); + if (tok <= 0) { + if (nextPtr != 0 && tok != XML_TOK_INVALID) { + *nextPtr = s; + return XML_ERROR_NONE; + } + switch (tok) { + case XML_TOK_INVALID: + eventPtr = next; + return XML_ERROR_INVALID_TOKEN; + case XML_TOK_NONE: + return XML_ERROR_NO_ELEMENTS; + case XML_TOK_PARTIAL: + return XML_ERROR_UNCLOSED_TOKEN; + case XML_TOK_PARTIAL_CHAR: + return XML_ERROR_PARTIAL_CHAR; + case XML_TOK_TRAILING_CR: + eventPtr = s + encoding->minBytesPerChar; + return XML_ERROR_NO_ELEMENTS; + default: + abort(); + } + } + switch (XmlTokenRole(&prologState, tok, s, next, encoding)) { + case XML_ROLE_XML_DECL: + { + enum XML_Error result = processXmlDecl(parser, 0, s, next); + if (result != XML_ERROR_NONE) + return result; + } + break; + case XML_ROLE_DOCTYPE_SYSTEM_ID: + if (!dtd.standalone + && notStandaloneHandler + && !notStandaloneHandler(handlerArg)) + return XML_ERROR_NOT_STANDALONE; + hadExternalDoctype = 1; + break; + case XML_ROLE_DOCTYPE_PUBLIC_ID: + case XML_ROLE_ENTITY_PUBLIC_ID: + if (!XmlIsPublicId(encoding, s, next, &eventPtr)) + return XML_ERROR_SYNTAX; + if (declEntity) { + XML_Char *tem = poolStoreString(&dtd.pool, + encoding, + s + encoding->minBytesPerChar, + next - encoding->minBytesPerChar); + if (!tem) + return XML_ERROR_NO_MEMORY; + normalizePublicId(tem); + declEntity->publicId = tem; + poolFinish(&dtd.pool); + } + break; + case XML_ROLE_INSTANCE_START: + processor = contentProcessor; + if (hadExternalDoctype) + dtd.complete = 0; + return contentProcessor(parser, s, end, nextPtr); + case XML_ROLE_ATTLIST_ELEMENT_NAME: + { + const XML_Char *name = poolStoreString(&dtd.pool, encoding, s, next); + if (!name) + return XML_ERROR_NO_MEMORY; + declElementType = (ELEMENT_TYPE *)lookup(&dtd.elementTypes, name, sizeof(ELEMENT_TYPE)); + if (!declElementType) + return XML_ERROR_NO_MEMORY; + if (declElementType->name != name) + poolDiscard(&dtd.pool); + else { + poolFinish(&dtd.pool); + if (!setElementTypePrefix(parser, declElementType)) + return XML_ERROR_NO_MEMORY; + } + break; + } + case XML_ROLE_ATTRIBUTE_NAME: + declAttributeId = getAttributeId(parser, encoding, s, next); + if (!declAttributeId) + return XML_ERROR_NO_MEMORY; + declAttributeIsCdata = 0; + break; + case XML_ROLE_ATTRIBUTE_TYPE_CDATA: + declAttributeIsCdata = 1; + break; + case XML_ROLE_IMPLIED_ATTRIBUTE_VALUE: + case XML_ROLE_REQUIRED_ATTRIBUTE_VALUE: + if (dtd.complete + && !defineAttribute(declElementType, declAttributeId, declAttributeIsCdata, 0)) + return XML_ERROR_NO_MEMORY; + break; + case XML_ROLE_DEFAULT_ATTRIBUTE_VALUE: + case XML_ROLE_FIXED_ATTRIBUTE_VALUE: + { + const XML_Char *attVal; + enum XML_Error result + = storeAttributeValue(parser, encoding, declAttributeIsCdata, + s + encoding->minBytesPerChar, + next - encoding->minBytesPerChar, + &dtd.pool); + if (result) + return result; + attVal = poolStart(&dtd.pool); + poolFinish(&dtd.pool); + if (dtd.complete + && !defineAttribute(declElementType, declAttributeId, declAttributeIsCdata, attVal)) + return XML_ERROR_NO_MEMORY; + break; + } + case XML_ROLE_ENTITY_VALUE: + { + enum XML_Error result = storeEntityValue(parser, s, next); + if (result != XML_ERROR_NONE) + return result; + } + break; + case XML_ROLE_ENTITY_SYSTEM_ID: + if (declEntity) { + declEntity->systemId = poolStoreString(&dtd.pool, encoding, + s + encoding->minBytesPerChar, + next - encoding->minBytesPerChar); + if (!declEntity->systemId) + return XML_ERROR_NO_MEMORY; + declEntity->base = dtd.base; + poolFinish(&dtd.pool); + } + break; + case XML_ROLE_ENTITY_NOTATION_NAME: + if (declEntity) { + declEntity->notation = poolStoreString(&dtd.pool, encoding, s, next); + if (!declEntity->notation) + return XML_ERROR_NO_MEMORY; + poolFinish(&dtd.pool); + if (unparsedEntityDeclHandler) { + eventPtr = eventEndPtr = s; + unparsedEntityDeclHandler(handlerArg, + declEntity->name, + declEntity->base, + declEntity->systemId, + declEntity->publicId, + declEntity->notation); + } + + } + break; + case XML_ROLE_GENERAL_ENTITY_NAME: + { + const XML_Char *name; + if (XmlPredefinedEntityName(encoding, s, next)) { + declEntity = 0; + break; + } + name = poolStoreString(&dtd.pool, encoding, s, next); + if (!name) + return XML_ERROR_NO_MEMORY; + if (dtd.complete) { + declEntity = (ENTITY *)lookup(&dtd.generalEntities, name, sizeof(ENTITY)); + if (!declEntity) + return XML_ERROR_NO_MEMORY; + if (declEntity->name != name) { + poolDiscard(&dtd.pool); + declEntity = 0; + } + else + poolFinish(&dtd.pool); + } + else { + poolDiscard(&dtd.pool); + declEntity = 0; + } + } + break; + case XML_ROLE_PARAM_ENTITY_NAME: + declEntity = 0; + break; + case XML_ROLE_NOTATION_NAME: + declNotationPublicId = 0; + declNotationName = 0; + if (notationDeclHandler) { + declNotationName = poolStoreString(&tempPool, encoding, s, next); + if (!declNotationName) + return XML_ERROR_NO_MEMORY; + poolFinish(&tempPool); + } + break; + case XML_ROLE_NOTATION_PUBLIC_ID: + if (!XmlIsPublicId(encoding, s, next, &eventPtr)) + return XML_ERROR_SYNTAX; + if (declNotationName) { + XML_Char *tem = poolStoreString(&tempPool, + encoding, + s + encoding->minBytesPerChar, + next - encoding->minBytesPerChar); + if (!tem) + return XML_ERROR_NO_MEMORY; + normalizePublicId(tem); + declNotationPublicId = tem; + poolFinish(&tempPool); + } + break; + case XML_ROLE_NOTATION_SYSTEM_ID: + if (declNotationName && notationDeclHandler) { + const XML_Char *systemId + = poolStoreString(&tempPool, encoding, + s + encoding->minBytesPerChar, + next - encoding->minBytesPerChar); + if (!systemId) + return XML_ERROR_NO_MEMORY; + eventPtr = eventEndPtr = s; + notationDeclHandler(handlerArg, + declNotationName, + dtd.base, + systemId, + declNotationPublicId); + } + poolClear(&tempPool); + break; + case XML_ROLE_NOTATION_NO_SYSTEM_ID: + if (declNotationPublicId && notationDeclHandler) { + eventPtr = eventEndPtr = s; + notationDeclHandler(handlerArg, + declNotationName, + dtd.base, + 0, + declNotationPublicId); + } + poolClear(&tempPool); + break; + case XML_ROLE_ERROR: + eventPtr = s; + switch (tok) { + case XML_TOK_PARAM_ENTITY_REF: + return XML_ERROR_PARAM_ENTITY_REF; + case XML_TOK_XML_DECL: + return XML_ERROR_MISPLACED_XML_PI; + default: + return XML_ERROR_SYNTAX; + } + case XML_ROLE_GROUP_OPEN: + if (prologState.level >= groupSize) { + if (groupSize) + groupConnector = realloc(groupConnector, groupSize *= 2); + else + groupConnector = malloc(groupSize = 32); + if (!groupConnector) + return XML_ERROR_NO_MEMORY; + } + groupConnector[prologState.level] = 0; + break; + case XML_ROLE_GROUP_SEQUENCE: + if (groupConnector[prologState.level] == '|') { + eventPtr = s; + return XML_ERROR_SYNTAX; + } + groupConnector[prologState.level] = ','; + break; + case XML_ROLE_GROUP_CHOICE: + if (groupConnector[prologState.level] == ',') { + eventPtr = s; + return XML_ERROR_SYNTAX; + } + groupConnector[prologState.level] = '|'; + break; + case XML_ROLE_PARAM_ENTITY_REF: + if (!dtd.standalone + && notStandaloneHandler + && !notStandaloneHandler(handlerArg)) + return XML_ERROR_NOT_STANDALONE; + dtd.complete = 0; + break; + case XML_ROLE_NONE: + switch (tok) { + case XML_TOK_PI: + eventPtr = s; + eventEndPtr = next; + if (!reportProcessingInstruction(parser, encoding, s, next)) + return XML_ERROR_NO_MEMORY; + break; + case XML_TOK_COMMENT: + eventPtr = s; + eventEndPtr = next; + if (!reportComment(parser, encoding, s, next)) + return XML_ERROR_NO_MEMORY; + break; + } + break; + } + if (defaultHandler) { + switch (tok) { + case XML_TOK_PI: + case XML_TOK_COMMENT: + case XML_TOK_BOM: + case XML_TOK_XML_DECL: + break; + default: + eventPtr = s; + eventEndPtr = next; + reportDefault(parser, encoding, s, next); + } + } + s = next; + } + /* not reached */ +} + +static +enum XML_Error epilogProcessor(XML_Parser parser, + const char *s, + const char *end, + const char **nextPtr) +{ + processor = epilogProcessor; + eventPtr = s; + for (;;) { + const char *next; + int tok = XmlPrologTok(encoding, s, end, &next); + eventEndPtr = next; + switch (tok) { + case XML_TOK_TRAILING_CR: + if (defaultHandler) { + eventEndPtr = end; + reportDefault(parser, encoding, s, end); + } + /* fall through */ + case XML_TOK_NONE: + if (nextPtr) + *nextPtr = end; + return XML_ERROR_NONE; + case XML_TOK_PROLOG_S: + if (defaultHandler) + reportDefault(parser, encoding, s, next); + break; + case XML_TOK_PI: + if (!reportProcessingInstruction(parser, encoding, s, next)) + return XML_ERROR_NO_MEMORY; + break; + case XML_TOK_COMMENT: + if (!reportComment(parser, encoding, s, next)) + return XML_ERROR_NO_MEMORY; + break; + case XML_TOK_INVALID: + eventPtr = next; + return XML_ERROR_INVALID_TOKEN; + case XML_TOK_PARTIAL: + if (nextPtr) { + *nextPtr = s; + return XML_ERROR_NONE; + } + return XML_ERROR_UNCLOSED_TOKEN; + case XML_TOK_PARTIAL_CHAR: + if (nextPtr) { + *nextPtr = s; + return XML_ERROR_NONE; + } + return XML_ERROR_PARTIAL_CHAR; + default: + return XML_ERROR_JUNK_AFTER_DOC_ELEMENT; + } + eventPtr = s = next; + } +} + +#if 0 +static +enum XML_Error errorProcessor(XML_Parser parser, + const char *s, + const char *end, + const char **nextPtr) +{ + return errorCode; +} +#endif + +static enum XML_Error +storeAttributeValue(XML_Parser parser, const ENCODING *enc, int isCdata, + const char *ptr, const char *end, + STRING_POOL *pool) +{ + enum XML_Error result = appendAttributeValue(parser, enc, isCdata, ptr, end, pool); + if (result) + return result; + if (!isCdata && poolLength(pool) && poolLastChar(pool) == 0x20) + poolChop(pool); + if (!poolAppendChar(pool, XML_T('\0'))) + return XML_ERROR_NO_MEMORY; + return XML_ERROR_NONE; +} + +static enum XML_Error +appendAttributeValue(XML_Parser parser, const ENCODING *enc, int isCdata, + const char *ptr, const char *end, + STRING_POOL *pool) +{ + const ENCODING *internalEnc = ns ? XmlGetInternalEncodingNS() : XmlGetInternalEncoding(); + for (;;) { + const char *next; + int tok = XmlAttributeValueTok(enc, ptr, end, &next); + switch (tok) { + case XML_TOK_NONE: + return XML_ERROR_NONE; + case XML_TOK_INVALID: + if (enc == encoding) + eventPtr = next; + return XML_ERROR_INVALID_TOKEN; + case XML_TOK_PARTIAL: + if (enc == encoding) + eventPtr = ptr; + return XML_ERROR_INVALID_TOKEN; + case XML_TOK_CHAR_REF: + { + XML_Char buf[XML_ENCODE_MAX]; + int i; + int n = XmlCharRefNumber(enc, ptr); + if (n < 0) { + if (enc == encoding) + eventPtr = ptr; + return XML_ERROR_BAD_CHAR_REF; + } + if (!isCdata + && n == 0x20 /* space */ + && (poolLength(pool) == 0 || poolLastChar(pool) == 0x20)) + break; + n = XmlEncode(n, (ICHAR *)buf); + if (!n) { + if (enc == encoding) + eventPtr = ptr; + return XML_ERROR_BAD_CHAR_REF; + } + for (i = 0; i < n; i++) { + if (!poolAppendChar(pool, buf[i])) + return XML_ERROR_NO_MEMORY; + } + } + break; + case XML_TOK_DATA_CHARS: + if (!poolAppend(pool, enc, ptr, next)) + return XML_ERROR_NO_MEMORY; + break; + break; + case XML_TOK_TRAILING_CR: + next = ptr + enc->minBytesPerChar; + /* fall through */ + case XML_TOK_ATTRIBUTE_VALUE_S: + case XML_TOK_DATA_NEWLINE: + if (!isCdata && (poolLength(pool) == 0 || poolLastChar(pool) == 0x20)) + break; + if (!poolAppendChar(pool, 0x20)) + return XML_ERROR_NO_MEMORY; + break; + case XML_TOK_ENTITY_REF: + { + const XML_Char *name; + ENTITY *entity; + XML_Char ch = XmlPredefinedEntityName(enc, + ptr + enc->minBytesPerChar, + next - enc->minBytesPerChar); + if (ch) { + if (!poolAppendChar(pool, ch)) + return XML_ERROR_NO_MEMORY; + break; + } + name = poolStoreString(&temp2Pool, enc, + ptr + enc->minBytesPerChar, + next - enc->minBytesPerChar); + if (!name) + return XML_ERROR_NO_MEMORY; + entity = (ENTITY *)lookup(&dtd.generalEntities, name, 0); + poolDiscard(&temp2Pool); + if (!entity) { + if (dtd.complete) { + if (enc == encoding) + eventPtr = ptr; + return XML_ERROR_UNDEFINED_ENTITY; + } + } + else if (entity->open) { + if (enc == encoding) + eventPtr = ptr; + return XML_ERROR_RECURSIVE_ENTITY_REF; + } + else if (entity->notation) { + if (enc == encoding) + eventPtr = ptr; + return XML_ERROR_BINARY_ENTITY_REF; + } + else if (!entity->textPtr) { + if (enc == encoding) + eventPtr = ptr; + return XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF; + } + else { + enum XML_Error result; + const XML_Char *textEnd = entity->textPtr + entity->textLen; + entity->open = 1; + result = appendAttributeValue(parser, internalEnc, isCdata, (char *)entity->textPtr, (char *)textEnd, pool); + entity->open = 0; + if (result) + return result; + } + } + break; + default: + abort(); + } + ptr = next; + } + /* not reached */ +} + +static +enum XML_Error storeEntityValue(XML_Parser parser, + const char *entityTextPtr, + const char *entityTextEnd) +{ +#if 0 + const ENCODING *internalEnc = ns ? XmlGetInternalEncodingNS() : XmlGetInternalEncoding(); +#endif + STRING_POOL *pool = &(dtd.pool); + entityTextPtr += encoding->minBytesPerChar; + entityTextEnd -= encoding->minBytesPerChar; + for (;;) { + const char *next; + int tok = XmlEntityValueTok(encoding, entityTextPtr, entityTextEnd, &next); + switch (tok) { + case XML_TOK_PARAM_ENTITY_REF: + eventPtr = entityTextPtr; + return XML_ERROR_SYNTAX; + case XML_TOK_NONE: + if (declEntity) { + declEntity->textPtr = pool->start; + declEntity->textLen = pool->ptr - pool->start; + poolFinish(pool); + } + else + poolDiscard(pool); + return XML_ERROR_NONE; + case XML_TOK_ENTITY_REF: + case XML_TOK_DATA_CHARS: + if (!poolAppend(pool, encoding, entityTextPtr, next)) + return XML_ERROR_NO_MEMORY; + break; + case XML_TOK_TRAILING_CR: + next = entityTextPtr + encoding->minBytesPerChar; + /* fall through */ + case XML_TOK_DATA_NEWLINE: + if (pool->end == pool->ptr && !poolGrow(pool)) + return XML_ERROR_NO_MEMORY; + *(pool->ptr)++ = 0xA; + break; + case XML_TOK_CHAR_REF: + { + XML_Char buf[XML_ENCODE_MAX]; + int i; + int n = XmlCharRefNumber(encoding, entityTextPtr); + if (n < 0) { + eventPtr = entityTextPtr; + return XML_ERROR_BAD_CHAR_REF; + } + n = XmlEncode(n, (ICHAR *)buf); + if (!n) { + eventPtr = entityTextPtr; + return XML_ERROR_BAD_CHAR_REF; + } + for (i = 0; i < n; i++) { + if (pool->end == pool->ptr && !poolGrow(pool)) + return XML_ERROR_NO_MEMORY; + *(pool->ptr)++ = buf[i]; + } + } + break; + case XML_TOK_PARTIAL: + eventPtr = entityTextPtr; + return XML_ERROR_INVALID_TOKEN; + case XML_TOK_INVALID: + eventPtr = next; + return XML_ERROR_INVALID_TOKEN; + default: + abort(); + } + entityTextPtr = next; + } + /* not reached */ +} + +static void +normalizeLines(XML_Char *s) +{ + XML_Char *p; + for (;; s++) { + if (*s == XML_T('\0')) + return; + if (*s == 0xD) + break; + } + p = s; + do { + if (*s == 0xD) { + *p++ = 0xA; + if (*++s == 0xA) + s++; + } + else + *p++ = *s++; + } while (*s); + *p = XML_T('\0'); +} + +static int +reportProcessingInstruction(XML_Parser parser, const ENCODING *enc, const char *start, const char *end) +{ + const XML_Char *target; + XML_Char *data; + const char *tem; + if (!processingInstructionHandler) { + if (defaultHandler) + reportDefault(parser, enc, start, end); + return 1; + } + start += enc->minBytesPerChar * 2; + tem = start + XmlNameLength(enc, start); + target = poolStoreString(&tempPool, enc, start, tem); + if (!target) + return 0; + poolFinish(&tempPool); + data = poolStoreString(&tempPool, enc, + XmlSkipS(enc, tem), + end - enc->minBytesPerChar*2); + if (!data) + return 0; + normalizeLines(data); + processingInstructionHandler(handlerArg, target, data); + poolClear(&tempPool); + return 1; +} + +static int +reportComment(XML_Parser parser, const ENCODING *enc, const char *start, const char *end) +{ + XML_Char *data; + if (!commentHandler) { + if (defaultHandler) + reportDefault(parser, enc, start, end); + return 1; + } + data = poolStoreString(&tempPool, + enc, + start + enc->minBytesPerChar * 4, + end - enc->minBytesPerChar * 3); + if (!data) + return 0; + normalizeLines(data); + commentHandler(handlerArg, data); + poolClear(&tempPool); + return 1; +} + +static void +reportDefault(XML_Parser parser, const ENCODING *enc, const char *s, const char *end) +{ + if (MUST_CONVERT(enc, s)) { + const char **eventPP; + const char **eventEndPP; + if (enc == encoding) { + eventPP = &eventPtr; + eventEndPP = &eventEndPtr; + } + else { + eventPP = &(openInternalEntities->internalEventPtr); + eventEndPP = &(openInternalEntities->internalEventEndPtr); + } + do { + ICHAR *dataPtr = (ICHAR *)dataBuf; + XmlConvert(enc, &s, end, &dataPtr, (ICHAR *)dataBufEnd); + *eventEndPP = s; + defaultHandler(handlerArg, dataBuf, dataPtr - (ICHAR *)dataBuf); + *eventPP = s; + } while (s != end); + } + else + defaultHandler(handlerArg, (XML_Char *)s, (XML_Char *)end - (XML_Char *)s); +} + + +static int +defineAttribute(ELEMENT_TYPE *type, ATTRIBUTE_ID *attId, int isCdata, const XML_Char *value) +{ + DEFAULT_ATTRIBUTE *att; + if (type->nDefaultAtts == type->allocDefaultAtts) { + if (type->allocDefaultAtts == 0) { + type->allocDefaultAtts = 8; + type->defaultAtts = malloc(type->allocDefaultAtts*sizeof(DEFAULT_ATTRIBUTE)); + } + else { + type->allocDefaultAtts *= 2; + type->defaultAtts = realloc(type->defaultAtts, + type->allocDefaultAtts*sizeof(DEFAULT_ATTRIBUTE)); + } + if (!type->defaultAtts) + return 0; + } + att = type->defaultAtts + type->nDefaultAtts; + att->id = attId; + att->value = value; + att->isCdata = isCdata; + if (!isCdata) + attId->maybeTokenized = 1; + type->nDefaultAtts += 1; + return 1; +} + +static int setElementTypePrefix(XML_Parser parser, ELEMENT_TYPE *elementType) +{ + const XML_Char *name; + for (name = elementType->name; *name; name++) { + if (*name == XML_T(':')) { + PREFIX *prefix; + const XML_Char *s; + for (s = elementType->name; s != name; s++) { + if (!poolAppendChar(&dtd.pool, *s)) + return 0; + } + if (!poolAppendChar(&dtd.pool, XML_T('\0'))) + return 0; + prefix = (PREFIX *)lookup(&dtd.prefixes, poolStart(&dtd.pool), sizeof(PREFIX)); + if (!prefix) + return 0; + if (prefix->name == poolStart(&dtd.pool)) + poolFinish(&dtd.pool); + else + poolDiscard(&dtd.pool); + elementType->prefix = prefix; + + } + } + return 1; +} + +static ATTRIBUTE_ID * +getAttributeId(XML_Parser parser, const ENCODING *enc, const char *start, const char *end) +{ + ATTRIBUTE_ID *id; + const XML_Char *name; + if (!poolAppendChar(&dtd.pool, XML_T('\0'))) + return 0; + name = poolStoreString(&dtd.pool, enc, start, end); + if (!name) + return 0; + ++name; + id = (ATTRIBUTE_ID *)lookup(&dtd.attributeIds, name, sizeof(ATTRIBUTE_ID)); + if (!id) + return 0; + if (id->name != name) + poolDiscard(&dtd.pool); + else { + poolFinish(&dtd.pool); + if (!ns) + ; + else if (name[0] == 'x' + && name[1] == 'm' + && name[2] == 'l' + && name[3] == 'n' + && name[4] == 's' + && (name[5] == XML_T('\0') || name[5] == XML_T(':'))) { + if (name[5] == '\0') + id->prefix = &dtd.defaultPrefix; + else + id->prefix = (PREFIX *)lookup(&dtd.prefixes, name + 6, sizeof(PREFIX)); + id->xmlns = 1; + } + else { + int i; + for (i = 0; name[i]; i++) { + if (name[i] == XML_T(':')) { + int j; + for (j = 0; j < i; j++) { + if (!poolAppendChar(&dtd.pool, name[j])) + return 0; + } + if (!poolAppendChar(&dtd.pool, XML_T('\0'))) + return 0; + id->prefix = (PREFIX *)lookup(&dtd.prefixes, poolStart(&dtd.pool), sizeof(PREFIX)); + if (id->prefix->name == poolStart(&dtd.pool)) + poolFinish(&dtd.pool); + else + poolDiscard(&dtd.pool); + break; + } + } + } + } + return id; +} + +#define CONTEXT_SEP XML_T('\f') + +static +const XML_Char *getContext(XML_Parser parser) +{ + HASH_TABLE_ITER iter; + int needSep = 0; + + if (dtd.defaultPrefix.binding) { + int i; + int len; + if (!poolAppendChar(&tempPool, XML_T('='))) + return 0; + len = dtd.defaultPrefix.binding->uriLen; + if (namespaceSeparator != XML_T('\0')) + len--; + for (i = 0; i < len; i++) + if (!poolAppendChar(&tempPool, dtd.defaultPrefix.binding->uri[i])) + return 0; + needSep = 1; + } + + hashTableIterInit(&iter, &(dtd.prefixes)); + for (;;) { + int i; + int len; + const XML_Char *s; + PREFIX *prefix = (PREFIX *)hashTableIterNext(&iter); + if (!prefix) + break; + if (!prefix->binding) + continue; + if (needSep && !poolAppendChar(&tempPool, CONTEXT_SEP)) + return 0; + for (s = prefix->name; *s; s++) + if (!poolAppendChar(&tempPool, *s)) + return 0; + if (!poolAppendChar(&tempPool, XML_T('='))) + return 0; + len = prefix->binding->uriLen; + if (namespaceSeparator != XML_T('\0')) + len--; + for (i = 0; i < len; i++) + if (!poolAppendChar(&tempPool, prefix->binding->uri[i])) + return 0; + needSep = 1; + } + + + hashTableIterInit(&iter, &(dtd.generalEntities)); + for (;;) { + const XML_Char *s; + ENTITY *e = (ENTITY *)hashTableIterNext(&iter); + if (!e) + break; + if (!e->open) + continue; + if (needSep && !poolAppendChar(&tempPool, CONTEXT_SEP)) + return 0; + for (s = e->name; *s; s++) + if (!poolAppendChar(&tempPool, *s)) + return 0; + needSep = 1; + } + + if (!poolAppendChar(&tempPool, XML_T('\0'))) + return 0; + return tempPool.start; +} + +static +int setContext(XML_Parser parser, const XML_Char *context) +{ + const XML_Char *s = context; + + while (*context != XML_T('\0')) { + if (*s == CONTEXT_SEP || *s == XML_T('\0')) { + ENTITY *e; + if (!poolAppendChar(&tempPool, XML_T('\0'))) + return 0; + e = (ENTITY *)lookup(&dtd.generalEntities, poolStart(&tempPool), 0); + if (e) + e->open = 1; + if (*s != XML_T('\0')) + s++; + context = s; + poolDiscard(&tempPool); + } + else if (*s == '=') { + PREFIX *prefix; + if (poolLength(&tempPool) == 0) + prefix = &dtd.defaultPrefix; + else { + if (!poolAppendChar(&tempPool, XML_T('\0'))) + return 0; + prefix = (PREFIX *)lookup(&dtd.prefixes, poolStart(&tempPool), sizeof(PREFIX)); + if (!prefix) + return 0; + if (prefix->name == poolStart(&tempPool)) + poolFinish(&tempPool); + else + poolDiscard(&tempPool); + } + for (context = s + 1; *context != CONTEXT_SEP && *context != XML_T('\0'); context++) + if (!poolAppendChar(&tempPool, *context)) + return 0; + if (!poolAppendChar(&tempPool, XML_T('\0'))) + return 0; + if (!addBinding(parser, prefix, 0, poolStart(&tempPool), &inheritedBindings)) + return 0; + poolDiscard(&tempPool); + if (*context != XML_T('\0')) + ++context; + s = context; + } + else { + if (!poolAppendChar(&tempPool, *s)) + return 0; + s++; + } + } + return 1; +} + + +static +void normalizePublicId(XML_Char *publicId) +{ + XML_Char *p = publicId; + XML_Char *s; + for (s = publicId; *s; s++) { + switch (*s) { + case 0x20: + case 0xD: + case 0xA: + if (p != publicId && p[-1] != 0x20) + *p++ = 0x20; + break; + default: + *p++ = *s; + } + } + if (p != publicId && p[-1] == 0x20) + --p; + *p = XML_T('\0'); +} + +static int dtdInit(DTD *p) +{ + poolInit(&(p->pool)); + hashTableInit(&(p->generalEntities)); + hashTableInit(&(p->elementTypes)); + hashTableInit(&(p->attributeIds)); + hashTableInit(&(p->prefixes)); + p->complete = 1; + p->standalone = 0; + p->base = 0; + p->defaultPrefix.name = 0; + p->defaultPrefix.binding = 0; + return 1; +} + +static void dtdDestroy(DTD *p) +{ + HASH_TABLE_ITER iter; + hashTableIterInit(&iter, &(p->elementTypes)); + for (;;) { + ELEMENT_TYPE *e = (ELEMENT_TYPE *)hashTableIterNext(&iter); + if (!e) + break; + if (e->allocDefaultAtts != 0) + free(e->defaultAtts); + } + hashTableDestroy(&(p->generalEntities)); + hashTableDestroy(&(p->elementTypes)); + hashTableDestroy(&(p->attributeIds)); + hashTableDestroy(&(p->prefixes)); + poolDestroy(&(p->pool)); +} + +/* Do a deep copy of the DTD. Return 0 for out of memory; non-zero otherwise. +The new DTD has already been initialized. */ + +static int dtdCopy(DTD *newDtd, const DTD *oldDtd) +{ + HASH_TABLE_ITER iter; + + if (oldDtd->base) { + const XML_Char *tem = poolCopyString(&(newDtd->pool), oldDtd->base); + if (!tem) + return 0; + newDtd->base = tem; + } + + /* Copy the prefix table. */ + + hashTableIterInit(&iter, &(oldDtd->prefixes)); + for (;;) { + const XML_Char *name; + const PREFIX *oldP = (PREFIX *)hashTableIterNext(&iter); + if (!oldP) + break; + name = poolCopyString(&(newDtd->pool), oldP->name); + if (!name) + return 0; + if (!lookup(&(newDtd->prefixes), name, sizeof(PREFIX))) + return 0; + } + + hashTableIterInit(&iter, &(oldDtd->attributeIds)); + + /* Copy the attribute id table. */ + + for (;;) { + ATTRIBUTE_ID *newA; + const XML_Char *name; + const ATTRIBUTE_ID *oldA = (ATTRIBUTE_ID *)hashTableIterNext(&iter); + + if (!oldA) + break; + /* Remember to allocate the scratch byte before the name. */ + if (!poolAppendChar(&(newDtd->pool), XML_T('\0'))) + return 0; + name = poolCopyString(&(newDtd->pool), oldA->name); + if (!name) + return 0; + ++name; + newA = (ATTRIBUTE_ID *)lookup(&(newDtd->attributeIds), name, sizeof(ATTRIBUTE_ID)); + if (!newA) + return 0; + newA->maybeTokenized = oldA->maybeTokenized; + if (oldA->prefix) { + newA->xmlns = oldA->xmlns; + if (oldA->prefix == &oldDtd->defaultPrefix) + newA->prefix = &newDtd->defaultPrefix; + else + newA->prefix = (PREFIX *)lookup(&(newDtd->prefixes), oldA->prefix->name, 0); + } + } + + /* Copy the element type table. */ + + hashTableIterInit(&iter, &(oldDtd->elementTypes)); + + for (;;) { + int i; + ELEMENT_TYPE *newE; + const XML_Char *name; + const ELEMENT_TYPE *oldE = (ELEMENT_TYPE *)hashTableIterNext(&iter); + if (!oldE) + break; + name = poolCopyString(&(newDtd->pool), oldE->name); + if (!name) + return 0; + newE = (ELEMENT_TYPE *)lookup(&(newDtd->elementTypes), name, sizeof(ELEMENT_TYPE)); + if (!newE) + return 0; + if (oldE->nDefaultAtts) { + newE->defaultAtts = (DEFAULT_ATTRIBUTE *)malloc(oldE->nDefaultAtts * sizeof(DEFAULT_ATTRIBUTE)); + if (!newE->defaultAtts) + return 0; + } + newE->allocDefaultAtts = newE->nDefaultAtts = oldE->nDefaultAtts; + if (oldE->prefix) + newE->prefix = (PREFIX *)lookup(&(newDtd->prefixes), oldE->prefix->name, 0); + for (i = 0; i < newE->nDefaultAtts; i++) { + newE->defaultAtts[i].id = (ATTRIBUTE_ID *)lookup(&(newDtd->attributeIds), oldE->defaultAtts[i].id->name, 0); + newE->defaultAtts[i].isCdata = oldE->defaultAtts[i].isCdata; + if (oldE->defaultAtts[i].value) { + newE->defaultAtts[i].value = poolCopyString(&(newDtd->pool), oldE->defaultAtts[i].value); + if (!newE->defaultAtts[i].value) + return 0; + } + else + newE->defaultAtts[i].value = 0; + } + } + + /* Copy the entity table. */ + + hashTableIterInit(&iter, &(oldDtd->generalEntities)); + + for (;;) { + ENTITY *newE; + const XML_Char *name; + const ENTITY *oldE = (ENTITY *)hashTableIterNext(&iter); + if (!oldE) + break; + name = poolCopyString(&(newDtd->pool), oldE->name); + if (!name) + return 0; + newE = (ENTITY *)lookup(&(newDtd->generalEntities), name, sizeof(ENTITY)); + if (!newE) + return 0; + if (oldE->systemId) { + const XML_Char *tem = poolCopyString(&(newDtd->pool), oldE->systemId); + if (!tem) + return 0; + newE->systemId = tem; + if (oldE->base) { + if (oldE->base == oldDtd->base) + newE->base = newDtd->base; + tem = poolCopyString(&(newDtd->pool), oldE->base); + if (!tem) + return 0; + newE->base = tem; + } + } + else { + const XML_Char *tem = poolCopyStringN(&(newDtd->pool), oldE->textPtr, oldE->textLen); + if (!tem) + return 0; + newE->textPtr = tem; + newE->textLen = oldE->textLen; + } + if (oldE->notation) { + const XML_Char *tem = poolCopyString(&(newDtd->pool), oldE->notation); + if (!tem) + return 0; + newE->notation = tem; + } + } + + newDtd->complete = oldDtd->complete; + newDtd->standalone = oldDtd->standalone; + return 1; +} + +static +void poolInit(STRING_POOL *pool) +{ + pool->blocks = 0; + pool->freeBlocks = 0; + pool->start = 0; + pool->ptr = 0; + pool->end = 0; +} + +static +void poolClear(STRING_POOL *pool) +{ + if (!pool->freeBlocks) + pool->freeBlocks = pool->blocks; + else { + BLOCK *p = pool->blocks; + while (p) { + BLOCK *tem = p->next; + p->next = pool->freeBlocks; + pool->freeBlocks = p; + p = tem; + } + } + pool->blocks = 0; + pool->start = 0; + pool->ptr = 0; + pool->end = 0; +} + +static +void poolDestroy(STRING_POOL *pool) +{ + BLOCK *p = pool->blocks; + while (p) { + BLOCK *tem = p->next; + free(p); + p = tem; + } + pool->blocks = 0; + p = pool->freeBlocks; + while (p) { + BLOCK *tem = p->next; + free(p); + p = tem; + } + pool->freeBlocks = 0; + pool->ptr = 0; + pool->start = 0; + pool->end = 0; +} + +static +XML_Char *poolAppend(STRING_POOL *pool, const ENCODING *enc, + const char *ptr, const char *end) +{ + if (!pool->ptr && !poolGrow(pool)) + return 0; + for (;;) { + XmlConvert(enc, &ptr, end, (ICHAR **)&(pool->ptr), (ICHAR *)pool->end); + if (ptr == end) + break; + if (!poolGrow(pool)) + return 0; + } + return pool->start; +} + +static const XML_Char *poolCopyString(STRING_POOL *pool, const XML_Char *s) +{ + do { + if (!poolAppendChar(pool, *s)) + return 0; + } while (*s++); + s = pool->start; + poolFinish(pool); + return s; +} + +static const XML_Char *poolCopyStringN(STRING_POOL *pool, const XML_Char *s, int n) +{ + if (!pool->ptr && !poolGrow(pool)) + return 0; + for (; n > 0; --n, s++) { + if (!poolAppendChar(pool, *s)) + return 0; + + } + s = pool->start; + poolFinish(pool); + return s; +} + +static +XML_Char *poolStoreString(STRING_POOL *pool, const ENCODING *enc, + const char *ptr, const char *end) +{ + if (!poolAppend(pool, enc, ptr, end)) + return 0; + if (pool->ptr == pool->end && !poolGrow(pool)) + return 0; + *(pool->ptr)++ = 0; + return pool->start; +} + +static +int poolGrow(STRING_POOL *pool) +{ + if (pool->freeBlocks) { + if (pool->start == 0) { + pool->blocks = pool->freeBlocks; + pool->freeBlocks = pool->freeBlocks->next; + pool->blocks->next = 0; + pool->start = pool->blocks->s; + pool->end = pool->start + pool->blocks->size; + pool->ptr = pool->start; + return 1; + } + if (pool->end - pool->start < pool->freeBlocks->size) { + BLOCK *tem = pool->freeBlocks->next; + pool->freeBlocks->next = pool->blocks; + pool->blocks = pool->freeBlocks; + pool->freeBlocks = tem; + memcpy(pool->blocks->s, pool->start, (pool->end - pool->start) * sizeof(XML_Char)); + pool->ptr = pool->blocks->s + (pool->ptr - pool->start); + pool->start = pool->blocks->s; + pool->end = pool->start + pool->blocks->size; + return 1; + } + } + if (pool->blocks && pool->start == pool->blocks->s) { + int blockSize = (pool->end - pool->start)*2; + pool->blocks = realloc(pool->blocks, offsetof(BLOCK, s) + blockSize * sizeof(XML_Char)); + if (!pool->blocks) + return 0; + pool->blocks->size = blockSize; + pool->ptr = pool->blocks->s + (pool->ptr - pool->start); + pool->start = pool->blocks->s; + pool->end = pool->start + blockSize; + } + else { + BLOCK *tem; + int blockSize = pool->end - pool->start; + if (blockSize < INIT_BLOCK_SIZE) + blockSize = INIT_BLOCK_SIZE; + else + blockSize *= 2; + tem = malloc(offsetof(BLOCK, s) + blockSize * sizeof(XML_Char)); + if (!tem) + return 0; + tem->size = blockSize; + tem->next = pool->blocks; + pool->blocks = tem; + memcpy(tem->s, pool->start, (pool->ptr - pool->start) * sizeof(XML_Char)); + pool->ptr = tem->s + (pool->ptr - pool->start); + pool->start = tem->s; + pool->end = tem->s + blockSize; + } + return 1; +} diff --git a/srclib/expat-lite/xmlparse.h b/srclib/expat-lite/xmlparse.h new file mode 100644 index 0000000000..f2f9c9be1c --- /dev/null +++ b/srclib/expat-lite/xmlparse.h @@ -0,0 +1,482 @@ +/* +The contents of this file are subject to the Mozilla Public License +Version 1.1 (the "License"); you may not use this file except in +compliance with the License. You may obtain a copy of the License at +http://www.mozilla.org/MPL/ + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the +License for the specific language governing rights and limitations +under the License. + +The Original Code is expat. + +The Initial Developer of the Original Code is James Clark. +Portions created by James Clark are Copyright (C) 1998, 1999 +James Clark. All Rights Reserved. + +Contributor(s): + +Alternatively, the contents of this file may be used under the terms +of the GNU General Public License (the "GPL"), in which case the +provisions of the GPL are applicable instead of those above. If you +wish to allow use of your version of this file only under the terms of +the GPL and not to allow others to use your version of this file under +the MPL, indicate your decision by deleting the provisions above and +replace them with the notice and other provisions required by the +GPL. If you do not delete the provisions above, a recipient may use +your version of this file under either the MPL or the GPL. +*/ + +#ifndef XmlParse_INCLUDED +#define XmlParse_INCLUDED 1 + +#ifdef __cplusplus +extern "C" { +#endif + +#ifndef XMLPARSEAPI +#define XMLPARSEAPI /* as nothing */ +#endif + +typedef void *XML_Parser; + +#ifdef XML_UNICODE_WCHAR_T + +/* XML_UNICODE_WCHAR_T will work only if sizeof(wchar_t) == 2 and wchar_t +uses Unicode. */ +/* Information is UTF-16 encoded as wchar_ts */ + +#ifndef XML_UNICODE +#define XML_UNICODE +#endif + +#include <stddef.h> +typedef wchar_t XML_Char; +typedef wchar_t XML_LChar; + +#else /* not XML_UNICODE_WCHAR_T */ + +#ifdef XML_UNICODE + +/* Information is UTF-16 encoded as unsigned shorts */ +typedef unsigned short XML_Char; +typedef char XML_LChar; + +#else /* not XML_UNICODE */ + +/* Information is UTF-8 encoded. */ +typedef char XML_Char; +typedef char XML_LChar; + +#endif /* not XML_UNICODE */ + +#endif /* not XML_UNICODE_WCHAR_T */ + + +/* Constructs a new parser; encoding is the encoding specified by the external +protocol or null if there is none specified. */ + +XML_Parser XMLPARSEAPI +XML_ParserCreate(const XML_Char *encoding); + +/* Constructs a new parser and namespace processor. Element type names +and attribute names that belong to a namespace will be expanded; +unprefixed attribute names are never expanded; unprefixed element type +names are expanded only if there is a default namespace. The expanded +name is the concatenation of the namespace URI, the namespace separator character, +and the local part of the name. If the namespace separator is '\0' then +the namespace URI and the local part will be concatenated without any +separator. When a namespace is not declared, the name and prefix will be +passed through without expansion. */ + +XML_Parser XMLPARSEAPI +XML_ParserCreateNS(const XML_Char *encoding, XML_Char namespaceSeparator); + + +/* atts is array of name/value pairs, terminated by 0; + names and values are 0 terminated. */ + +typedef void (*XML_StartElementHandler)(void *userData, + const XML_Char *name, + const XML_Char **atts); + +typedef void (*XML_EndElementHandler)(void *userData, + const XML_Char *name); + +/* s is not 0 terminated. */ +typedef void (*XML_CharacterDataHandler)(void *userData, + const XML_Char *s, + int len); + +/* target and data are 0 terminated */ +typedef void (*XML_ProcessingInstructionHandler)(void *userData, + const XML_Char *target, + const XML_Char *data); + +/* data is 0 terminated */ +typedef void (*XML_CommentHandler)(void *userData, const XML_Char *data); + +typedef void (*XML_StartCdataSectionHandler)(void *userData); +typedef void (*XML_EndCdataSectionHandler)(void *userData); + +/* This is called for any characters in the XML document for +which there is no applicable handler. This includes both +characters that are part of markup which is of a kind that is +not reported (comments, markup declarations), or characters +that are part of a construct which could be reported but +for which no handler has been supplied. The characters are passed +exactly as they were in the XML document except that +they will be encoded in UTF-8. Line boundaries are not normalized. +Note that a byte order mark character is not passed to the default handler. +There are no guarantees about how characters are divided between calls +to the default handler: for example, a comment might be split between +multiple calls. */ + +typedef void (*XML_DefaultHandler)(void *userData, + const XML_Char *s, + int len); + +/* This is called for a declaration of an unparsed (NDATA) +entity. The base argument is whatever was set by XML_SetBase. +The entityName, systemId and notationName arguments will never be null. +The other arguments may be. */ + +typedef void (*XML_UnparsedEntityDeclHandler)(void *userData, + const XML_Char *entityName, + const XML_Char *base, + const XML_Char *systemId, + const XML_Char *publicId, + const XML_Char *notationName); + +/* This is called for a declaration of notation. +The base argument is whatever was set by XML_SetBase. +The notationName will never be null. The other arguments can be. */ + +typedef void (*XML_NotationDeclHandler)(void *userData, + const XML_Char *notationName, + const XML_Char *base, + const XML_Char *systemId, + const XML_Char *publicId); + +/* When namespace processing is enabled, these are called once for +each namespace declaration. The call to the start and end element +handlers occur between the calls to the start and end namespace +declaration handlers. For an xmlns attribute, prefix will be null. +For an xmlns="" attribute, uri will be null. */ + +typedef void (*XML_StartNamespaceDeclHandler)(void *userData, + const XML_Char *prefix, + const XML_Char *uri); + +typedef void (*XML_EndNamespaceDeclHandler)(void *userData, + const XML_Char *prefix); + +/* This is called if the document is not standalone (it has an +external subset or a reference to a parameter entity, but does not +have standalone="yes"). If this handler returns 0, then processing +will not continue, and the parser will return a +XML_ERROR_NOT_STANDALONE error. */ + +typedef int (*XML_NotStandaloneHandler)(void *userData); + +/* This is called for a reference to an external parsed general entity. +The referenced entity is not automatically parsed. +The application can parse it immediately or later using +XML_ExternalEntityParserCreate. +The parser argument is the parser parsing the entity containing the reference; +it can be passed as the parser argument to XML_ExternalEntityParserCreate. +The systemId argument is the system identifier as specified in the entity declaration; +it will not be null. +The base argument is the system identifier that should be used as the base for +resolving systemId if systemId was relative; this is set by XML_SetBase; +it may be null. +The publicId argument is the public identifier as specified in the entity declaration, +or null if none was specified; the whitespace in the public identifier +will have been normalized as required by the XML spec. +The context argument specifies the parsing context in the format +expected by the context argument to +XML_ExternalEntityParserCreate; context is valid only until the handler +returns, so if the referenced entity is to be parsed later, it must be copied. +The handler should return 0 if processing should not continue because of +a fatal error in the handling of the external entity. +In this case the calling parser will return an XML_ERROR_EXTERNAL_ENTITY_HANDLING +error. +Note that unlike other handlers the first argument is the parser, not userData. */ + +typedef int (*XML_ExternalEntityRefHandler)(XML_Parser parser, + const XML_Char *context, + const XML_Char *base, + const XML_Char *systemId, + const XML_Char *publicId); + +/* This structure is filled in by the XML_UnknownEncodingHandler +to provide information to the parser about encodings that are unknown +to the parser. +The map[b] member gives information about byte sequences +whose first byte is b. +If map[b] is c where c is >= 0, then b by itself encodes the Unicode scalar value c. +If map[b] is -1, then the byte sequence is malformed. +If map[b] is -n, where n >= 2, then b is the first byte of an n-byte +sequence that encodes a single Unicode scalar value. +The data member will be passed as the first argument to the convert function. +The convert function is used to convert multibyte sequences; +s will point to a n-byte sequence where map[(unsigned char)*s] == -n. +The convert function must return the Unicode scalar value +represented by this byte sequence or -1 if the byte sequence is malformed. +The convert function may be null if the encoding is a single-byte encoding, +that is if map[b] >= -1 for all bytes b. +When the parser is finished with the encoding, then if release is not null, +it will call release passing it the data member; +once release has been called, the convert function will not be called again. + +Expat places certain restrictions on the encodings that are supported +using this mechanism. + +1. Every ASCII character that can appear in a well-formed XML document, +other than the characters + + $@\^`{}~ + +must be represented by a single byte, and that byte must be the +same byte that represents that character in ASCII. + +2. No character may require more than 4 bytes to encode. + +3. All characters encoded must have Unicode scalar values <= 0xFFFF, +(ie characters that would be encoded by surrogates in UTF-16 +are not allowed). Note that this restriction doesn't apply to +the built-in support for UTF-8 and UTF-16. + +4. No Unicode character may be encoded by more than one distinct sequence +of bytes. */ + +typedef struct { + int map[256]; + void *data; + int (*convert)(void *data, const char *s); + void (*release)(void *data); +} XML_Encoding; + +/* This is called for an encoding that is unknown to the parser. +The encodingHandlerData argument is that which was passed as the +second argument to XML_SetUnknownEncodingHandler. +The name argument gives the name of the encoding as specified in +the encoding declaration. +If the callback can provide information about the encoding, +it must fill in the XML_Encoding structure, and return 1. +Otherwise it must return 0. +If info does not describe a suitable encoding, +then the parser will return an XML_UNKNOWN_ENCODING error. */ + +typedef int (*XML_UnknownEncodingHandler)(void *encodingHandlerData, + const XML_Char *name, + XML_Encoding *info); + +void XMLPARSEAPI +XML_SetElementHandler(XML_Parser parser, + XML_StartElementHandler start, + XML_EndElementHandler end); + +void XMLPARSEAPI +XML_SetCharacterDataHandler(XML_Parser parser, + XML_CharacterDataHandler handler); + +void XMLPARSEAPI +XML_SetProcessingInstructionHandler(XML_Parser parser, + XML_ProcessingInstructionHandler handler); +void XMLPARSEAPI +XML_SetCommentHandler(XML_Parser parser, + XML_CommentHandler handler); + +void XMLPARSEAPI +XML_SetCdataSectionHandler(XML_Parser parser, + XML_StartCdataSectionHandler start, + XML_EndCdataSectionHandler end); + +/* This sets the default handler and also inhibits expansion of internal entities. +The entity reference will be passed to the default handler. */ + +void XMLPARSEAPI +XML_SetDefaultHandler(XML_Parser parser, + XML_DefaultHandler handler); + +/* This sets the default handler but does not inhibit expansion of internal entities. +The entity reference will not be passed to the default handler. */ + +void XMLPARSEAPI +XML_SetDefaultHandlerExpand(XML_Parser parser, + XML_DefaultHandler handler); + +void XMLPARSEAPI +XML_SetUnparsedEntityDeclHandler(XML_Parser parser, + XML_UnparsedEntityDeclHandler handler); + +void XMLPARSEAPI +XML_SetNotationDeclHandler(XML_Parser parser, + XML_NotationDeclHandler handler); + +void XMLPARSEAPI +XML_SetNamespaceDeclHandler(XML_Parser parser, + XML_StartNamespaceDeclHandler start, + XML_EndNamespaceDeclHandler end); + +void XMLPARSEAPI +XML_SetNotStandaloneHandler(XML_Parser parser, + XML_NotStandaloneHandler handler); + +void XMLPARSEAPI +XML_SetExternalEntityRefHandler(XML_Parser parser, + XML_ExternalEntityRefHandler handler); + +/* If a non-null value for arg is specified here, then it will be passed +as the first argument to the external entity ref handler instead +of the parser object. */ +void XMLPARSEAPI +XML_SetExternalEntityRefHandlerArg(XML_Parser, void *arg); + +void XMLPARSEAPI +XML_SetUnknownEncodingHandler(XML_Parser parser, + XML_UnknownEncodingHandler handler, + void *encodingHandlerData); + +/* This can be called within a handler for a start element, end element, +processing instruction or character data. It causes the corresponding +markup to be passed to the default handler. */ +void XMLPARSEAPI XML_DefaultCurrent(XML_Parser parser); + +/* This value is passed as the userData argument to callbacks. */ +void XMLPARSEAPI +XML_SetUserData(XML_Parser parser, void *userData); + +/* Returns the last value set by XML_SetUserData or null. */ +#define XML_GetUserData(parser) (*(void **)(parser)) + +/* This is equivalent to supplying an encoding argument +to XML_CreateParser. It must not be called after XML_Parse +or XML_ParseBuffer. */ + +int XMLPARSEAPI +XML_SetEncoding(XML_Parser parser, const XML_Char *encoding); + +/* If this function is called, then the parser will be passed +as the first argument to callbacks instead of userData. +The userData will still be accessible using XML_GetUserData. */ + +void XMLPARSEAPI +XML_UseParserAsHandlerArg(XML_Parser parser); + +/* Sets the base to be used for resolving relative URIs in system identifiers in +declarations. Resolving relative identifiers is left to the application: +this value will be passed through as the base argument to the +XML_ExternalEntityRefHandler, XML_NotationDeclHandler +and XML_UnparsedEntityDeclHandler. The base argument will be copied. +Returns zero if out of memory, non-zero otherwise. */ + +int XMLPARSEAPI +XML_SetBase(XML_Parser parser, const XML_Char *base); + +const XML_Char XMLPARSEAPI * +XML_GetBase(XML_Parser parser); + +/* Returns the number of the attributes passed in last call to the +XML_StartElementHandler that were specified in the start-tag rather +than defaulted. */ + +int XMLPARSEAPI XML_GetSpecifiedAttributeCount(XML_Parser parser); + +/* Parses some input. Returns 0 if a fatal error is detected. +The last call to XML_Parse must have isFinal true; +len may be zero for this call (or any other). */ +int XMLPARSEAPI +XML_Parse(XML_Parser parser, const char *s, int len, int isFinal); + +void XMLPARSEAPI * +XML_GetBuffer(XML_Parser parser, int len); + +int XMLPARSEAPI +XML_ParseBuffer(XML_Parser parser, int len, int isFinal); + +/* Creates an XML_Parser object that can parse an external general entity; +context is a '\0'-terminated string specifying the parse context; +encoding is a '\0'-terminated string giving the name of the externally specified encoding, +or null if there is no externally specified encoding. +The context string consists of a sequence of tokens separated by formfeeds (\f); +a token consisting of a name specifies that the general entity of the name +is open; a token of the form prefix=uri specifies the namespace for a particular +prefix; a token of the form =uri specifies the default namespace. +This can be called at any point after the first call to an ExternalEntityRefHandler +so longer as the parser has not yet been freed. +The new parser is completely independent and may safely be used in a separate thread. +The handlers and userData are initialized from the parser argument. +Returns 0 if out of memory. Otherwise returns a new XML_Parser object. */ +XML_Parser XMLPARSEAPI +XML_ExternalEntityParserCreate(XML_Parser parser, + const XML_Char *context, + const XML_Char *encoding); + +enum XML_Error { + XML_ERROR_NONE, + XML_ERROR_NO_MEMORY, + XML_ERROR_SYNTAX, + XML_ERROR_NO_ELEMENTS, + XML_ERROR_INVALID_TOKEN, + XML_ERROR_UNCLOSED_TOKEN, + XML_ERROR_PARTIAL_CHAR, + XML_ERROR_TAG_MISMATCH, + XML_ERROR_DUPLICATE_ATTRIBUTE, + XML_ERROR_JUNK_AFTER_DOC_ELEMENT, + XML_ERROR_PARAM_ENTITY_REF, + XML_ERROR_UNDEFINED_ENTITY, + XML_ERROR_RECURSIVE_ENTITY_REF, + XML_ERROR_ASYNC_ENTITY, + XML_ERROR_BAD_CHAR_REF, + XML_ERROR_BINARY_ENTITY_REF, + XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF, + XML_ERROR_MISPLACED_XML_PI, + XML_ERROR_UNKNOWN_ENCODING, + XML_ERROR_INCORRECT_ENCODING, + XML_ERROR_UNCLOSED_CDATA_SECTION, + XML_ERROR_EXTERNAL_ENTITY_HANDLING, + XML_ERROR_NOT_STANDALONE +}; + +/* If XML_Parse or XML_ParseBuffer have returned 0, then XML_GetErrorCode +returns information about the error. */ + +enum XML_Error XMLPARSEAPI XML_GetErrorCode(XML_Parser parser); + +/* These functions return information about the current parse location. +They may be called when XML_Parse or XML_ParseBuffer return 0; +in this case the location is the location of the character at which +the error was detected. +They may also be called from any other callback called to report +some parse event; in this the location is the location of the first +of the sequence of characters that generated the event. */ + +int XMLPARSEAPI XML_GetCurrentLineNumber(XML_Parser parser); +int XMLPARSEAPI XML_GetCurrentColumnNumber(XML_Parser parser); +long XMLPARSEAPI XML_GetCurrentByteIndex(XML_Parser parser); + +/* Return the number of bytes in the current event. +Returns 0 if the event is in an internal entity. */ + +int XMLPARSEAPI XML_GetCurrentByteCount(XML_Parser parser); + +/* For backwards compatibility with previous versions. */ +#define XML_GetErrorLineNumber XML_GetCurrentLineNumber +#define XML_GetErrorColumnNumber XML_GetCurrentColumnNumber +#define XML_GetErrorByteIndex XML_GetCurrentByteIndex + +/* Frees memory used by the parser. */ +void XMLPARSEAPI +XML_ParserFree(XML_Parser parser); + +/* Returns a string describing the error. */ +const XML_LChar XMLPARSEAPI *XML_ErrorString(int code); + +#ifdef __cplusplus +} +#endif + +#endif /* not XmlParse_INCLUDED */ diff --git a/srclib/expat-lite/xmlrole.c b/srclib/expat-lite/xmlrole.c new file mode 100644 index 0000000000..b18e35eb3c --- /dev/null +++ b/srclib/expat-lite/xmlrole.c @@ -0,0 +1,1113 @@ +/* +The contents of this file are subject to the Mozilla Public License +Version 1.1 (the "License"); you may not use this file except in +compliance with the License. You may obtain a copy of the License at +http://www.mozilla.org/MPL/ + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the +License for the specific language governing rights and limitations +under the License. + +The Original Code is expat. + +The Initial Developer of the Original Code is James Clark. +Portions created by James Clark are Copyright (C) 1998, 1999 +James Clark. All Rights Reserved. + +Contributor(s): + +Alternatively, the contents of this file may be used under the terms +of the GNU General Public License (the "GPL"), in which case the +provisions of the GPL are applicable instead of those above. If you +wish to allow use of your version of this file only under the terms of +the GPL and not to allow others to use your version of this file under +the MPL, indicate your decision by deleting the provisions above and +replace them with the notice and other provisions required by the +GPL. If you do not delete the provisions above, a recipient may use +your version of this file under either the MPL or the GPL. +*/ + +#include "xmldef.h" +#include "xmlrole.h" + +/* Doesn't check: + + that ,| are not mixed in a model group + content of literals + +*/ + +#ifndef MIN_BYTES_PER_CHAR +#define MIN_BYTES_PER_CHAR(enc) ((enc)->minBytesPerChar) +#endif + +typedef int PROLOG_HANDLER(struct prolog_state *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc); + +static PROLOG_HANDLER + prolog0, prolog1, prolog2, + doctype0, doctype1, doctype2, doctype3, doctype4, doctype5, + internalSubset, + entity0, entity1, entity2, entity3, entity4, entity5, entity6, + entity7, entity8, entity9, + notation0, notation1, notation2, notation3, notation4, + attlist0, attlist1, attlist2, attlist3, attlist4, attlist5, attlist6, + attlist7, attlist8, attlist9, + element0, element1, element2, element3, element4, element5, element6, + element7, + declClose, + error; + +static +int syntaxError(PROLOG_STATE *); + +static +int prolog0(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + state->handler = prolog1; + return XML_ROLE_NONE; + case XML_TOK_XML_DECL: + state->handler = prolog1; + return XML_ROLE_XML_DECL; + case XML_TOK_PI: + state->handler = prolog1; + return XML_ROLE_NONE; + case XML_TOK_COMMENT: + state->handler = prolog1; + case XML_TOK_BOM: + return XML_ROLE_NONE; + case XML_TOK_DECL_OPEN: + if (!XmlNameMatchesAscii(enc, + ptr + 2 * MIN_BYTES_PER_CHAR(enc), + "DOCTYPE")) + break; + state->handler = doctype0; + return XML_ROLE_NONE; + case XML_TOK_INSTANCE_START: + state->handler = error; + return XML_ROLE_INSTANCE_START; + } + return syntaxError(state); +} + +static +int prolog1(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_PI: + case XML_TOK_COMMENT: + case XML_TOK_BOM: + return XML_ROLE_NONE; + case XML_TOK_DECL_OPEN: + if (!XmlNameMatchesAscii(enc, + ptr + 2 * MIN_BYTES_PER_CHAR(enc), + "DOCTYPE")) + break; + state->handler = doctype0; + return XML_ROLE_NONE; + case XML_TOK_INSTANCE_START: + state->handler = error; + return XML_ROLE_INSTANCE_START; + } + return syntaxError(state); +} + +static +int prolog2(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_PI: + case XML_TOK_COMMENT: + return XML_ROLE_NONE; + case XML_TOK_INSTANCE_START: + state->handler = error; + return XML_ROLE_INSTANCE_START; + } + return syntaxError(state); +} + +static +int doctype0(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_NAME: + case XML_TOK_PREFIXED_NAME: + state->handler = doctype1; + return XML_ROLE_DOCTYPE_NAME; + } + return syntaxError(state); +} + +static +int doctype1(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_OPEN_BRACKET: + state->handler = internalSubset; + return XML_ROLE_NONE; + case XML_TOK_DECL_CLOSE: + state->handler = prolog2; + return XML_ROLE_DOCTYPE_CLOSE; + case XML_TOK_NAME: + if (XmlNameMatchesAscii(enc, ptr, "SYSTEM")) { + state->handler = doctype3; + return XML_ROLE_NONE; + } + if (XmlNameMatchesAscii(enc, ptr, "PUBLIC")) { + state->handler = doctype2; + return XML_ROLE_NONE; + } + break; + } + return syntaxError(state); +} + +static +int doctype2(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_LITERAL: + state->handler = doctype3; + return XML_ROLE_DOCTYPE_PUBLIC_ID; + } + return syntaxError(state); +} + +static +int doctype3(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_LITERAL: + state->handler = doctype4; + return XML_ROLE_DOCTYPE_SYSTEM_ID; + } + return syntaxError(state); +} + +static +int doctype4(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_OPEN_BRACKET: + state->handler = internalSubset; + return XML_ROLE_NONE; + case XML_TOK_DECL_CLOSE: + state->handler = prolog2; + return XML_ROLE_DOCTYPE_CLOSE; + } + return syntaxError(state); +} + +static +int doctype5(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_DECL_CLOSE: + state->handler = prolog2; + return XML_ROLE_DOCTYPE_CLOSE; + } + return syntaxError(state); +} + +static +int internalSubset(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_DECL_OPEN: + if (XmlNameMatchesAscii(enc, + ptr + 2 * MIN_BYTES_PER_CHAR(enc), + "ENTITY")) { + state->handler = entity0; + return XML_ROLE_NONE; + } + if (XmlNameMatchesAscii(enc, + ptr + 2 * MIN_BYTES_PER_CHAR(enc), + "ATTLIST")) { + state->handler = attlist0; + return XML_ROLE_NONE; + } + if (XmlNameMatchesAscii(enc, + ptr + 2 * MIN_BYTES_PER_CHAR(enc), + "ELEMENT")) { + state->handler = element0; + return XML_ROLE_NONE; + } + if (XmlNameMatchesAscii(enc, + ptr + 2 * MIN_BYTES_PER_CHAR(enc), + "NOTATION")) { + state->handler = notation0; + return XML_ROLE_NONE; + } + break; + case XML_TOK_PI: + case XML_TOK_COMMENT: + return XML_ROLE_NONE; + case XML_TOK_PARAM_ENTITY_REF: + return XML_ROLE_PARAM_ENTITY_REF; + case XML_TOK_CLOSE_BRACKET: + state->handler = doctype5; + return XML_ROLE_NONE; + } + return syntaxError(state); +} + +static +int entity0(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_PERCENT: + state->handler = entity1; + return XML_ROLE_NONE; + case XML_TOK_NAME: + state->handler = entity2; + return XML_ROLE_GENERAL_ENTITY_NAME; + } + return syntaxError(state); +} + +static +int entity1(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_NAME: + state->handler = entity7; + return XML_ROLE_PARAM_ENTITY_NAME; + } + return syntaxError(state); +} + +static +int entity2(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_NAME: + if (XmlNameMatchesAscii(enc, ptr, "SYSTEM")) { + state->handler = entity4; + return XML_ROLE_NONE; + } + if (XmlNameMatchesAscii(enc, ptr, "PUBLIC")) { + state->handler = entity3; + return XML_ROLE_NONE; + } + break; + case XML_TOK_LITERAL: + state->handler = declClose; + return XML_ROLE_ENTITY_VALUE; + } + return syntaxError(state); +} + +static +int entity3(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_LITERAL: + state->handler = entity4; + return XML_ROLE_ENTITY_PUBLIC_ID; + } + return syntaxError(state); +} + + +static +int entity4(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_LITERAL: + state->handler = entity5; + return XML_ROLE_ENTITY_SYSTEM_ID; + } + return syntaxError(state); +} + +static +int entity5(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_DECL_CLOSE: + state->handler = internalSubset; + return XML_ROLE_NONE; + case XML_TOK_NAME: + if (XmlNameMatchesAscii(enc, ptr, "NDATA")) { + state->handler = entity6; + return XML_ROLE_NONE; + } + break; + } + return syntaxError(state); +} + +static +int entity6(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_NAME: + state->handler = declClose; + return XML_ROLE_ENTITY_NOTATION_NAME; + } + return syntaxError(state); +} + +static +int entity7(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_NAME: + if (XmlNameMatchesAscii(enc, ptr, "SYSTEM")) { + state->handler = entity9; + return XML_ROLE_NONE; + } + if (XmlNameMatchesAscii(enc, ptr, "PUBLIC")) { + state->handler = entity8; + return XML_ROLE_NONE; + } + break; + case XML_TOK_LITERAL: + state->handler = declClose; + return XML_ROLE_ENTITY_VALUE; + } + return syntaxError(state); +} + +static +int entity8(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_LITERAL: + state->handler = entity9; + return XML_ROLE_ENTITY_PUBLIC_ID; + } + return syntaxError(state); +} + +static +int entity9(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_LITERAL: + state->handler = declClose; + return XML_ROLE_ENTITY_SYSTEM_ID; + } + return syntaxError(state); +} + +static +int notation0(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_NAME: + state->handler = notation1; + return XML_ROLE_NOTATION_NAME; + } + return syntaxError(state); +} + +static +int notation1(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_NAME: + if (XmlNameMatchesAscii(enc, ptr, "SYSTEM")) { + state->handler = notation3; + return XML_ROLE_NONE; + } + if (XmlNameMatchesAscii(enc, ptr, "PUBLIC")) { + state->handler = notation2; + return XML_ROLE_NONE; + } + break; + } + return syntaxError(state); +} + +static +int notation2(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_LITERAL: + state->handler = notation4; + return XML_ROLE_NOTATION_PUBLIC_ID; + } + return syntaxError(state); +} + +static +int notation3(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_LITERAL: + state->handler = declClose; + return XML_ROLE_NOTATION_SYSTEM_ID; + } + return syntaxError(state); +} + +static +int notation4(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_LITERAL: + state->handler = declClose; + return XML_ROLE_NOTATION_SYSTEM_ID; + case XML_TOK_DECL_CLOSE: + state->handler = internalSubset; + return XML_ROLE_NOTATION_NO_SYSTEM_ID; + } + return syntaxError(state); +} + +static +int attlist0(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_NAME: + case XML_TOK_PREFIXED_NAME: + state->handler = attlist1; + return XML_ROLE_ATTLIST_ELEMENT_NAME; + } + return syntaxError(state); +} + +static +int attlist1(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_DECL_CLOSE: + state->handler = internalSubset; + return XML_ROLE_NONE; + case XML_TOK_NAME: + case XML_TOK_PREFIXED_NAME: + state->handler = attlist2; + return XML_ROLE_ATTRIBUTE_NAME; + } + return syntaxError(state); +} + +static +int attlist2(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_NAME: + { + static const char *types[] = { + "CDATA", + "ID", + "IDREF", + "IDREFS", + "ENTITY", + "ENTITIES", + "NMTOKEN", + "NMTOKENS", + }; + int i; + for (i = 0; i < (int)(sizeof(types)/sizeof(types[0])); i++) + if (XmlNameMatchesAscii(enc, ptr, types[i])) { + state->handler = attlist8; + return XML_ROLE_ATTRIBUTE_TYPE_CDATA + i; + } + } + if (XmlNameMatchesAscii(enc, ptr, "NOTATION")) { + state->handler = attlist5; + return XML_ROLE_NONE; + } + break; + case XML_TOK_OPEN_PAREN: + state->handler = attlist3; + return XML_ROLE_NONE; + } + return syntaxError(state); +} + +static +int attlist3(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_NMTOKEN: + case XML_TOK_NAME: + case XML_TOK_PREFIXED_NAME: + state->handler = attlist4; + return XML_ROLE_ATTRIBUTE_ENUM_VALUE; + } + return syntaxError(state); +} + +static +int attlist4(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_CLOSE_PAREN: + state->handler = attlist8; + return XML_ROLE_NONE; + case XML_TOK_OR: + state->handler = attlist3; + return XML_ROLE_NONE; + } + return syntaxError(state); +} + +static +int attlist5(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_OPEN_PAREN: + state->handler = attlist6; + return XML_ROLE_NONE; + } + return syntaxError(state); +} + + +static +int attlist6(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_NAME: + state->handler = attlist7; + return XML_ROLE_ATTRIBUTE_NOTATION_VALUE; + } + return syntaxError(state); +} + +static +int attlist7(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_CLOSE_PAREN: + state->handler = attlist8; + return XML_ROLE_NONE; + case XML_TOK_OR: + state->handler = attlist6; + return XML_ROLE_NONE; + } + return syntaxError(state); +} + +/* default value */ +static +int attlist8(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_POUND_NAME: + if (XmlNameMatchesAscii(enc, + ptr + MIN_BYTES_PER_CHAR(enc), + "IMPLIED")) { + state->handler = attlist1; + return XML_ROLE_IMPLIED_ATTRIBUTE_VALUE; + } + if (XmlNameMatchesAscii(enc, + ptr + MIN_BYTES_PER_CHAR(enc), + "REQUIRED")) { + state->handler = attlist1; + return XML_ROLE_REQUIRED_ATTRIBUTE_VALUE; + } + if (XmlNameMatchesAscii(enc, + ptr + MIN_BYTES_PER_CHAR(enc), + "FIXED")) { + state->handler = attlist9; + return XML_ROLE_NONE; + } + break; + case XML_TOK_LITERAL: + state->handler = attlist1; + return XML_ROLE_DEFAULT_ATTRIBUTE_VALUE; + } + return syntaxError(state); +} + +static +int attlist9(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_LITERAL: + state->handler = attlist1; + return XML_ROLE_FIXED_ATTRIBUTE_VALUE; + } + return syntaxError(state); +} + +static +int element0(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_NAME: + case XML_TOK_PREFIXED_NAME: + state->handler = element1; + return XML_ROLE_ELEMENT_NAME; + } + return syntaxError(state); +} + +static +int element1(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_NAME: + if (XmlNameMatchesAscii(enc, ptr, "EMPTY")) { + state->handler = declClose; + return XML_ROLE_CONTENT_EMPTY; + } + if (XmlNameMatchesAscii(enc, ptr, "ANY")) { + state->handler = declClose; + return XML_ROLE_CONTENT_ANY; + } + break; + case XML_TOK_OPEN_PAREN: + state->handler = element2; + state->level = 1; + return XML_ROLE_GROUP_OPEN; + } + return syntaxError(state); +} + +static +int element2(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_POUND_NAME: + if (XmlNameMatchesAscii(enc, + ptr + MIN_BYTES_PER_CHAR(enc), + "PCDATA")) { + state->handler = element3; + return XML_ROLE_CONTENT_PCDATA; + } + break; + case XML_TOK_OPEN_PAREN: + state->level = 2; + state->handler = element6; + return XML_ROLE_GROUP_OPEN; + case XML_TOK_NAME: + case XML_TOK_PREFIXED_NAME: + state->handler = element7; + return XML_ROLE_CONTENT_ELEMENT; + case XML_TOK_NAME_QUESTION: + state->handler = element7; + return XML_ROLE_CONTENT_ELEMENT_OPT; + case XML_TOK_NAME_ASTERISK: + state->handler = element7; + return XML_ROLE_CONTENT_ELEMENT_REP; + case XML_TOK_NAME_PLUS: + state->handler = element7; + return XML_ROLE_CONTENT_ELEMENT_PLUS; + } + return syntaxError(state); +} + +static +int element3(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_CLOSE_PAREN: + case XML_TOK_CLOSE_PAREN_ASTERISK: + state->handler = declClose; + return XML_ROLE_GROUP_CLOSE_REP; + case XML_TOK_OR: + state->handler = element4; + return XML_ROLE_NONE; + } + return syntaxError(state); +} + +static +int element4(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_NAME: + case XML_TOK_PREFIXED_NAME: + state->handler = element5; + return XML_ROLE_CONTENT_ELEMENT; + } + return syntaxError(state); +} + +static +int element5(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_CLOSE_PAREN_ASTERISK: + state->handler = declClose; + return XML_ROLE_GROUP_CLOSE_REP; + case XML_TOK_OR: + state->handler = element4; + return XML_ROLE_NONE; + } + return syntaxError(state); +} + +static +int element6(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_OPEN_PAREN: + state->level += 1; + return XML_ROLE_GROUP_OPEN; + case XML_TOK_NAME: + case XML_TOK_PREFIXED_NAME: + state->handler = element7; + return XML_ROLE_CONTENT_ELEMENT; + case XML_TOK_NAME_QUESTION: + state->handler = element7; + return XML_ROLE_CONTENT_ELEMENT_OPT; + case XML_TOK_NAME_ASTERISK: + state->handler = element7; + return XML_ROLE_CONTENT_ELEMENT_REP; + case XML_TOK_NAME_PLUS: + state->handler = element7; + return XML_ROLE_CONTENT_ELEMENT_PLUS; + } + return syntaxError(state); +} + +static +int element7(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_CLOSE_PAREN: + state->level -= 1; + if (state->level == 0) + state->handler = declClose; + return XML_ROLE_GROUP_CLOSE; + case XML_TOK_CLOSE_PAREN_ASTERISK: + state->level -= 1; + if (state->level == 0) + state->handler = declClose; + return XML_ROLE_GROUP_CLOSE_REP; + case XML_TOK_CLOSE_PAREN_QUESTION: + state->level -= 1; + if (state->level == 0) + state->handler = declClose; + return XML_ROLE_GROUP_CLOSE_OPT; + case XML_TOK_CLOSE_PAREN_PLUS: + state->level -= 1; + if (state->level == 0) + state->handler = declClose; + return XML_ROLE_GROUP_CLOSE_PLUS; + case XML_TOK_COMMA: + state->handler = element6; + return XML_ROLE_GROUP_SEQUENCE; + case XML_TOK_OR: + state->handler = element6; + return XML_ROLE_GROUP_CHOICE; + } + return syntaxError(state); +} + +static +int declClose(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_PROLOG_S: + return XML_ROLE_NONE; + case XML_TOK_DECL_CLOSE: + state->handler = internalSubset; + return XML_ROLE_NONE; + } + return syntaxError(state); +} + +#if 0 + +static +int ignore(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + switch (tok) { + case XML_TOK_DECL_CLOSE: + state->handler = internalSubset; + return 0; + default: + return XML_ROLE_NONE; + } + return syntaxError(state); +} +#endif + +static +int error(PROLOG_STATE *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc) +{ + return XML_ROLE_NONE; +} + +static +int syntaxError(PROLOG_STATE *state) +{ + state->handler = error; + return XML_ROLE_ERROR; +} + +void XmlPrologStateInit(PROLOG_STATE *state) +{ + state->handler = prolog0; +} diff --git a/srclib/expat-lite/xmlrole.h b/srclib/expat-lite/xmlrole.h new file mode 100644 index 0000000000..877c40ba1f --- /dev/null +++ b/srclib/expat-lite/xmlrole.h @@ -0,0 +1,111 @@ +/* +The contents of this file are subject to the Mozilla Public License +Version 1.1 (the "License"); you may not use this file except in +compliance with the License. You may obtain a copy of the License at +http://www.mozilla.org/MPL/ + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the +License for the specific language governing rights and limitations +under the License. + +The Original Code is expat. + +The Initial Developer of the Original Code is James Clark. +Portions created by James Clark are Copyright (C) 1998, 1999 +James Clark. All Rights Reserved. + +Contributor(s): + +Alternatively, the contents of this file may be used under the terms +of the GNU General Public License (the "GPL"), in which case the +provisions of the GPL are applicable instead of those above. If you +wish to allow use of your version of this file only under the terms of +the GPL and not to allow others to use your version of this file under +the MPL, indicate your decision by deleting the provisions above and +replace them with the notice and other provisions required by the +GPL. If you do not delete the provisions above, a recipient may use +your version of this file under either the MPL or the GPL. +*/ + +#ifndef XmlRole_INCLUDED +#define XmlRole_INCLUDED 1 + +#include "xmltok.h" + +#ifdef __cplusplus +extern "C" { +#endif + +enum { + XML_ROLE_ERROR = -1, + XML_ROLE_NONE = 0, + XML_ROLE_XML_DECL, + XML_ROLE_INSTANCE_START, + XML_ROLE_DOCTYPE_NAME, + XML_ROLE_DOCTYPE_SYSTEM_ID, + XML_ROLE_DOCTYPE_PUBLIC_ID, + XML_ROLE_DOCTYPE_CLOSE, + XML_ROLE_GENERAL_ENTITY_NAME, + XML_ROLE_PARAM_ENTITY_NAME, + XML_ROLE_ENTITY_VALUE, + XML_ROLE_ENTITY_SYSTEM_ID, + XML_ROLE_ENTITY_PUBLIC_ID, + XML_ROLE_ENTITY_NOTATION_NAME, + XML_ROLE_NOTATION_NAME, + XML_ROLE_NOTATION_SYSTEM_ID, + XML_ROLE_NOTATION_NO_SYSTEM_ID, + XML_ROLE_NOTATION_PUBLIC_ID, + XML_ROLE_ATTRIBUTE_NAME, + XML_ROLE_ATTRIBUTE_TYPE_CDATA, + XML_ROLE_ATTRIBUTE_TYPE_ID, + XML_ROLE_ATTRIBUTE_TYPE_IDREF, + XML_ROLE_ATTRIBUTE_TYPE_IDREFS, + XML_ROLE_ATTRIBUTE_TYPE_ENTITY, + XML_ROLE_ATTRIBUTE_TYPE_ENTITIES, + XML_ROLE_ATTRIBUTE_TYPE_NMTOKEN, + XML_ROLE_ATTRIBUTE_TYPE_NMTOKENS, + XML_ROLE_ATTRIBUTE_ENUM_VALUE, + XML_ROLE_ATTRIBUTE_NOTATION_VALUE, + XML_ROLE_ATTLIST_ELEMENT_NAME, + XML_ROLE_IMPLIED_ATTRIBUTE_VALUE, + XML_ROLE_REQUIRED_ATTRIBUTE_VALUE, + XML_ROLE_DEFAULT_ATTRIBUTE_VALUE, + XML_ROLE_FIXED_ATTRIBUTE_VALUE, + XML_ROLE_ELEMENT_NAME, + XML_ROLE_CONTENT_ANY, + XML_ROLE_CONTENT_EMPTY, + XML_ROLE_CONTENT_PCDATA, + XML_ROLE_GROUP_OPEN, + XML_ROLE_GROUP_CLOSE, + XML_ROLE_GROUP_CLOSE_REP, + XML_ROLE_GROUP_CLOSE_OPT, + XML_ROLE_GROUP_CLOSE_PLUS, + XML_ROLE_GROUP_CHOICE, + XML_ROLE_GROUP_SEQUENCE, + XML_ROLE_CONTENT_ELEMENT, + XML_ROLE_CONTENT_ELEMENT_REP, + XML_ROLE_CONTENT_ELEMENT_OPT, + XML_ROLE_CONTENT_ELEMENT_PLUS, + XML_ROLE_PARAM_ENTITY_REF +}; + +typedef struct prolog_state { + int (*handler)(struct prolog_state *state, + int tok, + const char *ptr, + const char *end, + const ENCODING *enc); + unsigned level; +} PROLOG_STATE; + +void XMLTOKAPI XmlPrologStateInit(PROLOG_STATE *); + +#define XmlTokenRole(state, tok, ptr, end, enc) \ + (((state)->handler)(state, tok, ptr, end, enc)) + +#ifdef __cplusplus +} +#endif + +#endif /* not XmlRole_INCLUDED */ diff --git a/srclib/expat-lite/xmltok.c b/srclib/expat-lite/xmltok.c new file mode 100644 index 0000000000..a847d0108c --- /dev/null +++ b/srclib/expat-lite/xmltok.c @@ -0,0 +1,1527 @@ +/* +The contents of this file are subject to the Mozilla Public License +Version 1.1 (the "License"); you may not use this file except in +compliance with the License. You may obtain a copy of the License at +http://www.mozilla.org/MPL/ + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the +License for the specific language governing rights and limitations +under the License. + +The Original Code is expat. + +The Initial Developer of the Original Code is James Clark. +Portions created by James Clark are Copyright (C) 1998, 1999 +James Clark. All Rights Reserved. + +Contributor(s): + +Alternatively, the contents of this file may be used under the terms +of the GNU General Public License (the "GPL"), in which case the +provisions of the GPL are applicable instead of those above. If you +wish to allow use of your version of this file only under the terms of +the GPL and not to allow others to use your version of this file under +the MPL, indicate your decision by deleting the provisions above and +replace them with the notice and other provisions required by the +GPL. If you do not delete the provisions above, a recipient may use +your version of this file under either the MPL or the GPL. +*/ + +#include "xmldef.h" +#include "xmltok.h" +#include "nametab.h" + +#define VTABLE1 \ + { PREFIX(prologTok), PREFIX(contentTok), PREFIX(cdataSectionTok) }, \ + { PREFIX(attributeValueTok), PREFIX(entityValueTok) }, \ + PREFIX(sameName), \ + PREFIX(nameMatchesAscii), \ + PREFIX(nameLength), \ + PREFIX(skipS), \ + PREFIX(getAtts), \ + PREFIX(charRefNumber), \ + PREFIX(predefinedEntityName), \ + PREFIX(updatePosition), \ + PREFIX(isPublicId) + +#define VTABLE VTABLE1, PREFIX(toUtf8), PREFIX(toUtf16) + +#define UCS2_GET_NAMING(pages, hi, lo) \ + (namingBitmap[(pages[hi] << 3) + ((lo) >> 5)] & (1 << ((lo) & 0x1F))) + +/* A 2 byte UTF-8 representation splits the characters 11 bits +between the bottom 5 and 6 bits of the bytes. +We need 8 bits to index into pages, 3 bits to add to that index and +5 bits to generate the mask. */ +#define UTF8_GET_NAMING2(pages, byte) \ + (namingBitmap[((pages)[(((byte)[0]) >> 2) & 7] << 3) \ + + ((((byte)[0]) & 3) << 1) \ + + ((((byte)[1]) >> 5) & 1)] \ + & (1 << (((byte)[1]) & 0x1F))) + +/* A 3 byte UTF-8 representation splits the characters 16 bits +between the bottom 4, 6 and 6 bits of the bytes. +We need 8 bits to index into pages, 3 bits to add to that index and +5 bits to generate the mask. */ +#define UTF8_GET_NAMING3(pages, byte) \ + (namingBitmap[((pages)[((((byte)[0]) & 0xF) << 4) \ + + ((((byte)[1]) >> 2) & 0xF)] \ + << 3) \ + + ((((byte)[1]) & 3) << 1) \ + + ((((byte)[2]) >> 5) & 1)] \ + & (1 << (((byte)[2]) & 0x1F))) + +#define UTF8_GET_NAMING(pages, p, n) \ + ((n) == 2 \ + ? UTF8_GET_NAMING2(pages, (const unsigned char *)(p)) \ + : ((n) == 3 \ + ? UTF8_GET_NAMING3(pages, (const unsigned char *)(p)) \ + : 0)) + +#define UTF8_INVALID3(p) \ + ((*p) == 0xED \ + ? (((p)[1] & 0x20) != 0) \ + : ((*p) == 0xEF \ + ? ((p)[1] == 0xBF && ((p)[2] == 0xBF || (p)[2] == 0xBE)) \ + : 0)) + +#define UTF8_INVALID4(p) ((*p) == 0xF4 && ((p)[1] & 0x30) != 0) + +static +int isNever(const ENCODING *enc, const char *p) +{ + return 0; +} + +static +int utf8_isName2(const ENCODING *enc, const char *p) +{ + return UTF8_GET_NAMING2(namePages, (const unsigned char *)p); +} + +static +int utf8_isName3(const ENCODING *enc, const char *p) +{ + return UTF8_GET_NAMING3(namePages, (const unsigned char *)p); +} + +#define utf8_isName4 isNever + +static +int utf8_isNmstrt2(const ENCODING *enc, const char *p) +{ + return UTF8_GET_NAMING2(nmstrtPages, (const unsigned char *)p); +} + +static +int utf8_isNmstrt3(const ENCODING *enc, const char *p) +{ + return UTF8_GET_NAMING3(nmstrtPages, (const unsigned char *)p); +} + +#define utf8_isNmstrt4 isNever + +#define utf8_isInvalid2 isNever + +static +int utf8_isInvalid3(const ENCODING *enc, const char *p) +{ + return UTF8_INVALID3((const unsigned char *)p); +} + +static +int utf8_isInvalid4(const ENCODING *enc, const char *p) +{ + return UTF8_INVALID4((const unsigned char *)p); +} + +struct normal_encoding { + ENCODING enc; + unsigned char type[256]; +#ifdef XML_MIN_SIZE + int (*byteType)(const ENCODING *, const char *); + int (*isNameMin)(const ENCODING *, const char *); + int (*isNmstrtMin)(const ENCODING *, const char *); + int (*byteToAscii)(const ENCODING *, const char *); + int (*charMatches)(const ENCODING *, const char *, int); +#endif /* XML_MIN_SIZE */ + int (*isName2)(const ENCODING *, const char *); + int (*isName3)(const ENCODING *, const char *); + int (*isName4)(const ENCODING *, const char *); + int (*isNmstrt2)(const ENCODING *, const char *); + int (*isNmstrt3)(const ENCODING *, const char *); + int (*isNmstrt4)(const ENCODING *, const char *); + int (*isInvalid2)(const ENCODING *, const char *); + int (*isInvalid3)(const ENCODING *, const char *); + int (*isInvalid4)(const ENCODING *, const char *); +}; + +#ifdef XML_MIN_SIZE + +#define STANDARD_VTABLE(E) \ + E ## byteType, \ + E ## isNameMin, \ + E ## isNmstrtMin, \ + E ## byteToAscii, \ + E ## charMatches, + +#else + +#define STANDARD_VTABLE(E) /* as nothing */ + +#endif + +#define NORMAL_VTABLE(E) \ + E ## isName2, \ + E ## isName3, \ + E ## isName4, \ + E ## isNmstrt2, \ + E ## isNmstrt3, \ + E ## isNmstrt4, \ + E ## isInvalid2, \ + E ## isInvalid3, \ + E ## isInvalid4 + +static int checkCharRefNumber(int); + +#include "xmltok_impl.h" + +#ifdef XML_MIN_SIZE +#define sb_isNameMin isNever +#define sb_isNmstrtMin isNever +#endif + +#ifdef XML_MIN_SIZE +#define MINBPC(enc) ((enc)->minBytesPerChar) +#else +/* minimum bytes per character */ +#define MINBPC(enc) 1 +#endif + +#define SB_BYTE_TYPE(enc, p) \ + (((struct normal_encoding *)(enc))->type[(unsigned char)*(p)]) + +#ifdef XML_MIN_SIZE +static +int sb_byteType(const ENCODING *enc, const char *p) +{ + return SB_BYTE_TYPE(enc, p); +} +#define BYTE_TYPE(enc, p) \ + (((const struct normal_encoding *)(enc))->byteType(enc, p)) +#else +#define BYTE_TYPE(enc, p) SB_BYTE_TYPE(enc, p) +#endif + +#ifdef XML_MIN_SIZE +#define BYTE_TO_ASCII(enc, p) \ + (((const struct normal_encoding *)(enc))->byteToAscii(enc, p)) +static +int sb_byteToAscii(const ENCODING *enc, const char *p) +{ + return *p; +} +#else +#define BYTE_TO_ASCII(enc, p) (*p) +#endif + +#define IS_NAME_CHAR(enc, p, n) \ + (((const struct normal_encoding *)(enc))->isName ## n(enc, p)) +#define IS_NMSTRT_CHAR(enc, p, n) \ + (((const struct normal_encoding *)(enc))->isNmstrt ## n(enc, p)) +#define IS_INVALID_CHAR(enc, p, n) \ + (((const struct normal_encoding *)(enc))->isInvalid ## n(enc, p)) + +#ifdef XML_MIN_SIZE +#define IS_NAME_CHAR_MINBPC(enc, p) \ + (((const struct normal_encoding *)(enc))->isNameMin(enc, p)) +#define IS_NMSTRT_CHAR_MINBPC(enc, p) \ + (((const struct normal_encoding *)(enc))->isNmstrtMin(enc, p)) +#else +#define IS_NAME_CHAR_MINBPC(enc, p) (0) +#define IS_NMSTRT_CHAR_MINBPC(enc, p) (0) +#endif + +#ifdef XML_MIN_SIZE +#define CHAR_MATCHES(enc, p, c) \ + (((const struct normal_encoding *)(enc))->charMatches(enc, p, c)) +static +int sb_charMatches(const ENCODING *enc, const char *p, int c) +{ + return *p == c; +} +#else +/* c is an ASCII character */ +#define CHAR_MATCHES(enc, p, c) (*(p) == c) +#endif + +#define PREFIX(ident) normal_ ## ident +#include "xmltok_impl.c" + +#undef MINBPC +#undef BYTE_TYPE +#undef BYTE_TO_ASCII +#undef CHAR_MATCHES +#undef IS_NAME_CHAR +#undef IS_NAME_CHAR_MINBPC +#undef IS_NMSTRT_CHAR +#undef IS_NMSTRT_CHAR_MINBPC +#undef IS_INVALID_CHAR + +enum { /* UTF8_cvalN is value of masked first byte of N byte sequence */ + UTF8_cval1 = 0x00, + UTF8_cval2 = 0xc0, + UTF8_cval3 = 0xe0, + UTF8_cval4 = 0xf0 +}; + +static +void utf8_toUtf8(const ENCODING *enc, + const char **fromP, const char *fromLim, + char **toP, const char *toLim) +{ + char *to; + const char *from; + if (fromLim - *fromP > toLim - *toP) { + /* Avoid copying partial characters. */ + for (fromLim = *fromP + (toLim - *toP); fromLim > *fromP; fromLim--) + if (((unsigned char)fromLim[-1] & 0xc0) != 0x80) + break; + } + for (to = *toP, from = *fromP; from != fromLim; from++, to++) + *to = *from; + *fromP = from; + *toP = to; +} + +static +void utf8_toUtf16(const ENCODING *enc, + const char **fromP, const char *fromLim, + unsigned short **toP, const unsigned short *toLim) +{ + unsigned short *to = *toP; + const char *from = *fromP; + while (from != fromLim && to != toLim) { + switch (((struct normal_encoding *)enc)->type[(unsigned char)*from]) { + case BT_LEAD2: + *to++ = ((from[0] & 0x1f) << 6) | (from[1] & 0x3f); + from += 2; + break; + case BT_LEAD3: + *to++ = ((from[0] & 0xf) << 12) | ((from[1] & 0x3f) << 6) | (from[2] & 0x3f); + from += 3; + break; + case BT_LEAD4: + { + unsigned long n; + if (to + 1 == toLim) + break; + n = ((from[0] & 0x7) << 18) | ((from[1] & 0x3f) << 12) | ((from[2] & 0x3f) << 6) | (from[3] & 0x3f); + n -= 0x10000; + to[0] = (unsigned short)((n >> 10) | 0xD800); + to[1] = (unsigned short)((n & 0x3FF) | 0xDC00); + to += 2; + from += 4; + } + break; + default: + *to++ = *from++; + break; + } + } + *fromP = from; + *toP = to; +} + +#ifdef XML_NS +static const struct normal_encoding utf8_encoding_ns = { + { VTABLE1, utf8_toUtf8, utf8_toUtf16, 1, 1, 0 }, + { +#include "asciitab.h" +#include "utf8tab.h" + }, + STANDARD_VTABLE(sb_) NORMAL_VTABLE(utf8_) +}; +#endif + +static const struct normal_encoding utf8_encoding = { + { VTABLE1, utf8_toUtf8, utf8_toUtf16, 1, 1, 0 }, + { +#define BT_COLON BT_NMSTRT +#include "asciitab.h" +#undef BT_COLON +#include "utf8tab.h" + }, + STANDARD_VTABLE(sb_) NORMAL_VTABLE(utf8_) +}; + +#ifdef XML_NS + +static const struct normal_encoding internal_utf8_encoding_ns = { + { VTABLE1, utf8_toUtf8, utf8_toUtf16, 1, 1, 0 }, + { +#include "iasciitab.h" +#include "utf8tab.h" + }, + STANDARD_VTABLE(sb_) NORMAL_VTABLE(utf8_) +}; + +#endif + +static const struct normal_encoding internal_utf8_encoding = { + { VTABLE1, utf8_toUtf8, utf8_toUtf16, 1, 1, 0 }, + { +#define BT_COLON BT_NMSTRT +#include "iasciitab.h" +#undef BT_COLON +#include "utf8tab.h" + }, + STANDARD_VTABLE(sb_) NORMAL_VTABLE(utf8_) +}; + +static +void latin1_toUtf8(const ENCODING *enc, + const char **fromP, const char *fromLim, + char **toP, const char *toLim) +{ + for (;;) { + unsigned char c; + if (*fromP == fromLim) + break; + c = (unsigned char)**fromP; + if (c & 0x80) { + if (toLim - *toP < 2) + break; + *(*toP)++ = ((c >> 6) | UTF8_cval2); + *(*toP)++ = ((c & 0x3f) | 0x80); + (*fromP)++; + } + else { + if (*toP == toLim) + break; + *(*toP)++ = *(*fromP)++; + } + } +} + +static +void latin1_toUtf16(const ENCODING *enc, + const char **fromP, const char *fromLim, + unsigned short **toP, const unsigned short *toLim) +{ + while (*fromP != fromLim && *toP != toLim) + *(*toP)++ = (unsigned char)*(*fromP)++; +} + +#ifdef XML_NS + +static const struct normal_encoding latin1_encoding_ns = { + { VTABLE1, latin1_toUtf8, latin1_toUtf16, 1, 0, 0 }, + { +#include "asciitab.h" +#include "latin1tab.h" + }, + STANDARD_VTABLE(sb_) +}; + +#endif + +static const struct normal_encoding latin1_encoding = { + { VTABLE1, latin1_toUtf8, latin1_toUtf16, 1, 0, 0 }, + { +#define BT_COLON BT_NMSTRT +#include "asciitab.h" +#undef BT_COLON +#include "latin1tab.h" + }, + STANDARD_VTABLE(sb_) +}; + +static +void ascii_toUtf8(const ENCODING *enc, + const char **fromP, const char *fromLim, + char **toP, const char *toLim) +{ + while (*fromP != fromLim && *toP != toLim) + *(*toP)++ = *(*fromP)++; +} + +#ifdef XML_NS + +static const struct normal_encoding ascii_encoding_ns = { + { VTABLE1, ascii_toUtf8, latin1_toUtf16, 1, 1, 0 }, + { +#include "asciitab.h" +/* BT_NONXML == 0 */ + }, + STANDARD_VTABLE(sb_) +}; + +#endif + +static const struct normal_encoding ascii_encoding = { + { VTABLE1, ascii_toUtf8, latin1_toUtf16, 1, 1, 0 }, + { +#define BT_COLON BT_NMSTRT +#include "asciitab.h" +#undef BT_COLON +/* BT_NONXML == 0 */ + }, + STANDARD_VTABLE(sb_) +}; + +static int unicode_byte_type(char hi, char lo) +{ + switch ((unsigned char)hi) { + case 0xD8: case 0xD9: case 0xDA: case 0xDB: + return BT_LEAD4; + case 0xDC: case 0xDD: case 0xDE: case 0xDF: + return BT_TRAIL; + case 0xFF: + switch ((unsigned char)lo) { + case 0xFF: + case 0xFE: + return BT_NONXML; + } + break; + } + return BT_NONASCII; +} + +#define DEFINE_UTF16_TO_UTF8(E) \ +static \ +void E ## toUtf8(const ENCODING *enc, \ + const char **fromP, const char *fromLim, \ + char **toP, const char *toLim) \ +{ \ + const char *from; \ + for (from = *fromP; from != fromLim; from += 2) { \ + int plane; \ + unsigned char lo2; \ + unsigned char lo = GET_LO(from); \ + unsigned char hi = GET_HI(from); \ + switch (hi) { \ + case 0: \ + if (lo < 0x80) { \ + if (*toP == toLim) { \ + *fromP = from; \ + return; \ + } \ + *(*toP)++ = lo; \ + break; \ + } \ + /* fall through */ \ + case 0x1: case 0x2: case 0x3: \ + case 0x4: case 0x5: case 0x6: case 0x7: \ + if (toLim - *toP < 2) { \ + *fromP = from; \ + return; \ + } \ + *(*toP)++ = ((lo >> 6) | (hi << 2) | UTF8_cval2); \ + *(*toP)++ = ((lo & 0x3f) | 0x80); \ + break; \ + default: \ + if (toLim - *toP < 3) { \ + *fromP = from; \ + return; \ + } \ + /* 16 bits divided 4, 6, 6 amongst 3 bytes */ \ + *(*toP)++ = ((hi >> 4) | UTF8_cval3); \ + *(*toP)++ = (((hi & 0xf) << 2) | (lo >> 6) | 0x80); \ + *(*toP)++ = ((lo & 0x3f) | 0x80); \ + break; \ + case 0xD8: case 0xD9: case 0xDA: case 0xDB: \ + if (toLim - *toP < 4) { \ + *fromP = from; \ + return; \ + } \ + plane = (((hi & 0x3) << 2) | ((lo >> 6) & 0x3)) + 1; \ + *(*toP)++ = ((plane >> 2) | UTF8_cval4); \ + *(*toP)++ = (((lo >> 2) & 0xF) | ((plane & 0x3) << 4) | 0x80); \ + from += 2; \ + lo2 = GET_LO(from); \ + *(*toP)++ = (((lo & 0x3) << 4) \ + | ((GET_HI(from) & 0x3) << 2) \ + | (lo2 >> 6) \ + | 0x80); \ + *(*toP)++ = ((lo2 & 0x3f) | 0x80); \ + break; \ + } \ + } \ + *fromP = from; \ +} + +#define DEFINE_UTF16_TO_UTF16(E) \ +static \ +void E ## toUtf16(const ENCODING *enc, \ + const char **fromP, const char *fromLim, \ + unsigned short **toP, const unsigned short *toLim) \ +{ \ + /* Avoid copying first half only of surrogate */ \ + if (fromLim - *fromP > ((toLim - *toP) << 1) \ + && (GET_HI(fromLim - 2) & 0xF8) == 0xD8) \ + fromLim -= 2; \ + for (; *fromP != fromLim && *toP != toLim; *fromP += 2) \ + *(*toP)++ = (GET_HI(*fromP) << 8) | GET_LO(*fromP); \ +} + +#define SET2(ptr, ch) \ + (((ptr)[0] = ((ch) & 0xff)), ((ptr)[1] = ((ch) >> 8))) +#define GET_LO(ptr) ((unsigned char)(ptr)[0]) +#define GET_HI(ptr) ((unsigned char)(ptr)[1]) + +DEFINE_UTF16_TO_UTF8(little2_) +DEFINE_UTF16_TO_UTF16(little2_) + +#undef SET2 +#undef GET_LO +#undef GET_HI + +#define SET2(ptr, ch) \ + (((ptr)[0] = ((ch) >> 8)), ((ptr)[1] = ((ch) & 0xFF))) +#define GET_LO(ptr) ((unsigned char)(ptr)[1]) +#define GET_HI(ptr) ((unsigned char)(ptr)[0]) + +DEFINE_UTF16_TO_UTF8(big2_) +DEFINE_UTF16_TO_UTF16(big2_) + +#undef SET2 +#undef GET_LO +#undef GET_HI + +#define LITTLE2_BYTE_TYPE(enc, p) \ + ((p)[1] == 0 \ + ? ((struct normal_encoding *)(enc))->type[(unsigned char)*(p)] \ + : unicode_byte_type((p)[1], (p)[0])) +#define LITTLE2_BYTE_TO_ASCII(enc, p) ((p)[1] == 0 ? (p)[0] : -1) +#define LITTLE2_CHAR_MATCHES(enc, p, c) ((p)[1] == 0 && (p)[0] == c) +#define LITTLE2_IS_NAME_CHAR_MINBPC(enc, p) \ + UCS2_GET_NAMING(namePages, (unsigned char)p[1], (unsigned char)p[0]) +#define LITTLE2_IS_NMSTRT_CHAR_MINBPC(enc, p) \ + UCS2_GET_NAMING(nmstrtPages, (unsigned char)p[1], (unsigned char)p[0]) + +#ifdef XML_MIN_SIZE + +static +int little2_byteType(const ENCODING *enc, const char *p) +{ + return LITTLE2_BYTE_TYPE(enc, p); +} + +static +int little2_byteToAscii(const ENCODING *enc, const char *p) +{ + return LITTLE2_BYTE_TO_ASCII(enc, p); +} + +static +int little2_charMatches(const ENCODING *enc, const char *p, int c) +{ + return LITTLE2_CHAR_MATCHES(enc, p, c); +} + +static +int little2_isNameMin(const ENCODING *enc, const char *p) +{ + return LITTLE2_IS_NAME_CHAR_MINBPC(enc, p); +} + +static +int little2_isNmstrtMin(const ENCODING *enc, const char *p) +{ + return LITTLE2_IS_NMSTRT_CHAR_MINBPC(enc, p); +} + +#undef VTABLE +#define VTABLE VTABLE1, little2_toUtf8, little2_toUtf16 + +#else /* not XML_MIN_SIZE */ + +#undef PREFIX +#define PREFIX(ident) little2_ ## ident +#define MINBPC(enc) 2 +/* CHAR_MATCHES is guaranteed to have MINBPC bytes available. */ +#define BYTE_TYPE(enc, p) LITTLE2_BYTE_TYPE(enc, p) +#define BYTE_TO_ASCII(enc, p) LITTLE2_BYTE_TO_ASCII(enc, p) +#define CHAR_MATCHES(enc, p, c) LITTLE2_CHAR_MATCHES(enc, p, c) +#define IS_NAME_CHAR(enc, p, n) 0 +#define IS_NAME_CHAR_MINBPC(enc, p) LITTLE2_IS_NAME_CHAR_MINBPC(enc, p) +#define IS_NMSTRT_CHAR(enc, p, n) (0) +#define IS_NMSTRT_CHAR_MINBPC(enc, p) LITTLE2_IS_NMSTRT_CHAR_MINBPC(enc, p) + +#include "xmltok_impl.c" + +#undef MINBPC +#undef BYTE_TYPE +#undef BYTE_TO_ASCII +#undef CHAR_MATCHES +#undef IS_NAME_CHAR +#undef IS_NAME_CHAR_MINBPC +#undef IS_NMSTRT_CHAR +#undef IS_NMSTRT_CHAR_MINBPC +#undef IS_INVALID_CHAR + +#endif /* not XML_MIN_SIZE */ + +#ifdef XML_NS + +static const struct normal_encoding little2_encoding_ns = { + { VTABLE, 2, 0, +#if XML_BYTE_ORDER == 12 + 1 +#else + 0 +#endif + }, + { +#include "asciitab.h" +#include "latin1tab.h" + }, + STANDARD_VTABLE(little2_) +}; + +#endif + +static const struct normal_encoding little2_encoding = { + { VTABLE, 2, 0, +#if XML_BYTE_ORDER == 12 + 1 +#else + 0 +#endif + }, + { +#define BT_COLON BT_NMSTRT +#include "asciitab.h" +#undef BT_COLON +#include "latin1tab.h" + }, + STANDARD_VTABLE(little2_) +}; + +#if XML_BYTE_ORDER != 21 + +#ifdef XML_NS + +static const struct normal_encoding internal_little2_encoding_ns = { + { VTABLE, 2, 0, 1 }, + { +#include "iasciitab.h" +#include "latin1tab.h" + }, + STANDARD_VTABLE(little2_) +}; + +#endif + +static const struct normal_encoding internal_little2_encoding = { + { VTABLE, 2, 0, 1 }, + { +#define BT_COLON BT_NMSTRT +#include "iasciitab.h" +#undef BT_COLON +#include "latin1tab.h" + }, + STANDARD_VTABLE(little2_) +}; + +#endif + + +#define BIG2_BYTE_TYPE(enc, p) \ + ((p)[0] == 0 \ + ? ((struct normal_encoding *)(enc))->type[(unsigned char)(p)[1]] \ + : unicode_byte_type((p)[0], (p)[1])) +#define BIG2_BYTE_TO_ASCII(enc, p) ((p)[0] == 0 ? (p)[1] : -1) +#define BIG2_CHAR_MATCHES(enc, p, c) ((p)[0] == 0 && (p)[1] == c) +#define BIG2_IS_NAME_CHAR_MINBPC(enc, p) \ + UCS2_GET_NAMING(namePages, (unsigned char)p[0], (unsigned char)p[1]) +#define BIG2_IS_NMSTRT_CHAR_MINBPC(enc, p) \ + UCS2_GET_NAMING(nmstrtPages, (unsigned char)p[0], (unsigned char)p[1]) + +#ifdef XML_MIN_SIZE + +static +int big2_byteType(const ENCODING *enc, const char *p) +{ + return BIG2_BYTE_TYPE(enc, p); +} + +static +int big2_byteToAscii(const ENCODING *enc, const char *p) +{ + return BIG2_BYTE_TO_ASCII(enc, p); +} + +static +int big2_charMatches(const ENCODING *enc, const char *p, int c) +{ + return BIG2_CHAR_MATCHES(enc, p, c); +} + +static +int big2_isNameMin(const ENCODING *enc, const char *p) +{ + return BIG2_IS_NAME_CHAR_MINBPC(enc, p); +} + +static +int big2_isNmstrtMin(const ENCODING *enc, const char *p) +{ + return BIG2_IS_NMSTRT_CHAR_MINBPC(enc, p); +} + +#undef VTABLE +#define VTABLE VTABLE1, big2_toUtf8, big2_toUtf16 + +#else /* not XML_MIN_SIZE */ + +#undef PREFIX +#define PREFIX(ident) big2_ ## ident +#define MINBPC(enc) 2 +/* CHAR_MATCHES is guaranteed to have MINBPC bytes available. */ +#define BYTE_TYPE(enc, p) BIG2_BYTE_TYPE(enc, p) +#define BYTE_TO_ASCII(enc, p) BIG2_BYTE_TO_ASCII(enc, p) +#define CHAR_MATCHES(enc, p, c) BIG2_CHAR_MATCHES(enc, p, c) +#define IS_NAME_CHAR(enc, p, n) 0 +#define IS_NAME_CHAR_MINBPC(enc, p) BIG2_IS_NAME_CHAR_MINBPC(enc, p) +#define IS_NMSTRT_CHAR(enc, p, n) (0) +#define IS_NMSTRT_CHAR_MINBPC(enc, p) BIG2_IS_NMSTRT_CHAR_MINBPC(enc, p) + +#include "xmltok_impl.c" + +#undef MINBPC +#undef BYTE_TYPE +#undef BYTE_TO_ASCII +#undef CHAR_MATCHES +#undef IS_NAME_CHAR +#undef IS_NAME_CHAR_MINBPC +#undef IS_NMSTRT_CHAR +#undef IS_NMSTRT_CHAR_MINBPC +#undef IS_INVALID_CHAR + +#endif /* not XML_MIN_SIZE */ + +#ifdef XML_NS + +static const struct normal_encoding big2_encoding_ns = { + { VTABLE, 2, 0, +#if XML_BYTE_ORDER == 21 + 1 +#else + 0 +#endif + }, + { +#include "asciitab.h" +#include "latin1tab.h" + }, + STANDARD_VTABLE(big2_) +}; + +#endif + +static const struct normal_encoding big2_encoding = { + { VTABLE, 2, 0, +#if XML_BYTE_ORDER == 21 + 1 +#else + 0 +#endif + }, + { +#define BT_COLON BT_NMSTRT +#include "asciitab.h" +#undef BT_COLON +#include "latin1tab.h" + }, + STANDARD_VTABLE(big2_) +}; + +#if XML_BYTE_ORDER != 12 + +#ifdef XML_NS + +static const struct normal_encoding internal_big2_encoding_ns = { + { VTABLE, 2, 0, 1 }, + { +#include "iasciitab.h" +#include "latin1tab.h" + }, + STANDARD_VTABLE(big2_) +}; + +#endif + +static const struct normal_encoding internal_big2_encoding = { + { VTABLE, 2, 0, 1 }, + { +#define BT_COLON BT_NMSTRT +#include "iasciitab.h" +#undef BT_COLON +#include "latin1tab.h" + }, + STANDARD_VTABLE(big2_) +}; + +#endif + +#undef PREFIX + +static +int streqci(const char *s1, const char *s2) +{ + for (;;) { + char c1 = *s1++; + char c2 = *s2++; + if ('a' <= c1 && c1 <= 'z') + c1 += 'A' - 'a'; + if ('a' <= c2 && c2 <= 'z') + c2 += 'A' - 'a'; + if (c1 != c2) + return 0; + if (!c1) + break; + } + return 1; +} + +static +void initUpdatePosition(const ENCODING *enc, const char *ptr, + const char *end, POSITION *pos) +{ + normal_updatePosition(&utf8_encoding.enc, ptr, end, pos); +} + +static +int toAscii(const ENCODING *enc, const char *ptr, const char *end) +{ + char buf[1]; + char *p = buf; + XmlUtf8Convert(enc, &ptr, end, &p, p + 1); + if (p == buf) + return -1; + else + return buf[0]; +} + +static +int isSpace(int c) +{ + switch (c) { + case 0x20: + case 0xD: + case 0xA: + case 0x9: + return 1; + } + return 0; +} + +/* Return 1 if there's just optional white space +or there's an S followed by name=val. */ +static +int parsePseudoAttribute(const ENCODING *enc, + const char *ptr, + const char *end, + const char **namePtr, + const char **valPtr, + const char **nextTokPtr) +{ + int c; + char open; + if (ptr == end) { + *namePtr = 0; + return 1; + } + if (!isSpace(toAscii(enc, ptr, end))) { + *nextTokPtr = ptr; + return 0; + } + do { + ptr += enc->minBytesPerChar; + } while (isSpace(toAscii(enc, ptr, end))); + if (ptr == end) { + *namePtr = 0; + return 1; + } + *namePtr = ptr; + for (;;) { + c = toAscii(enc, ptr, end); + if (c == -1) { + *nextTokPtr = ptr; + return 0; + } + if (c == '=') + break; + if (isSpace(c)) { + do { + ptr += enc->minBytesPerChar; + } while (isSpace(c = toAscii(enc, ptr, end))); + if (c != '=') { + *nextTokPtr = ptr; + return 0; + } + break; + } + ptr += enc->minBytesPerChar; + } + if (ptr == *namePtr) { + *nextTokPtr = ptr; + return 0; + } + ptr += enc->minBytesPerChar; + c = toAscii(enc, ptr, end); + while (isSpace(c)) { + ptr += enc->minBytesPerChar; + c = toAscii(enc, ptr, end); + } + if (c != '"' && c != '\'') { + *nextTokPtr = ptr; + return 0; + } + open = c; + ptr += enc->minBytesPerChar; + *valPtr = ptr; + for (;; ptr += enc->minBytesPerChar) { + c = toAscii(enc, ptr, end); + if (c == open) + break; + if (!('a' <= c && c <= 'z') + && !('A' <= c && c <= 'Z') + && !('0' <= c && c <= '9') + && c != '.' + && c != '-' + && c != '_') { + *nextTokPtr = ptr; + return 0; + } + } + *nextTokPtr = ptr + enc->minBytesPerChar; + return 1; +} + +static +int doParseXmlDecl(const ENCODING *(*encodingFinder)(const ENCODING *, + const char *, + const char *), + int isGeneralTextEntity, + const ENCODING *enc, + const char *ptr, + const char *end, + const char **badPtr, + const char **versionPtr, + const char **encodingName, + const ENCODING **encoding, + int *standalone) +{ + const char *val = 0; + const char *name = 0; + ptr += 5 * enc->minBytesPerChar; + end -= 2 * enc->minBytesPerChar; + if (!parsePseudoAttribute(enc, ptr, end, &name, &val, &ptr) || !name) { + *badPtr = ptr; + return 0; + } + if (!XmlNameMatchesAscii(enc, name, "version")) { + if (!isGeneralTextEntity) { + *badPtr = name; + return 0; + } + } + else { + if (versionPtr) + *versionPtr = val; + if (!parsePseudoAttribute(enc, ptr, end, &name, &val, &ptr)) { + *badPtr = ptr; + return 0; + } + if (!name) { + if (isGeneralTextEntity) { + /* a TextDecl must have an EncodingDecl */ + *badPtr = ptr; + return 0; + } + return 1; + } + } + if (XmlNameMatchesAscii(enc, name, "encoding")) { + int c = toAscii(enc, val, end); + if (!('a' <= c && c <= 'z') && !('A' <= c && c <= 'Z')) { + *badPtr = val; + return 0; + } + if (encodingName) + *encodingName = val; + if (encoding) + *encoding = encodingFinder(enc, val, ptr - enc->minBytesPerChar); + if (!parsePseudoAttribute(enc, ptr, end, &name, &val, &ptr)) { + *badPtr = ptr; + return 0; + } + if (!name) + return 1; + } + if (!XmlNameMatchesAscii(enc, name, "standalone") || isGeneralTextEntity) { + *badPtr = name; + return 0; + } + if (XmlNameMatchesAscii(enc, val, "yes")) { + if (standalone) + *standalone = 1; + } + else if (XmlNameMatchesAscii(enc, val, "no")) { + if (standalone) + *standalone = 0; + } + else { + *badPtr = val; + return 0; + } + while (isSpace(toAscii(enc, ptr, end))) + ptr += enc->minBytesPerChar; + if (ptr != end) { + *badPtr = ptr; + return 0; + } + return 1; +} + +static +int checkCharRefNumber(int result) +{ + switch (result >> 8) { + case 0xD8: case 0xD9: case 0xDA: case 0xDB: + case 0xDC: case 0xDD: case 0xDE: case 0xDF: + return -1; + case 0: + if (latin1_encoding.type[result] == BT_NONXML) + return -1; + break; + case 0xFF: + if (result == 0xFFFE || result == 0xFFFF) + return -1; + break; + } + return result; +} + +int XmlUtf8Encode(int c, char *buf) +{ + enum { + /* minN is minimum legal resulting value for N byte sequence */ + min2 = 0x80, + min3 = 0x800, + min4 = 0x10000 + }; + + if (c < 0) + return 0; + if (c < min2) { + buf[0] = (c | UTF8_cval1); + return 1; + } + if (c < min3) { + buf[0] = ((c >> 6) | UTF8_cval2); + buf[1] = ((c & 0x3f) | 0x80); + return 2; + } + if (c < min4) { + buf[0] = ((c >> 12) | UTF8_cval3); + buf[1] = (((c >> 6) & 0x3f) | 0x80); + buf[2] = ((c & 0x3f) | 0x80); + return 3; + } + if (c < 0x110000) { + buf[0] = ((c >> 18) | UTF8_cval4); + buf[1] = (((c >> 12) & 0x3f) | 0x80); + buf[2] = (((c >> 6) & 0x3f) | 0x80); + buf[3] = ((c & 0x3f) | 0x80); + return 4; + } + return 0; +} + +int XmlUtf16Encode(int charNum, unsigned short *buf) +{ + if (charNum < 0) + return 0; + if (charNum < 0x10000) { + buf[0] = charNum; + return 1; + } + if (charNum < 0x110000) { + charNum -= 0x10000; + buf[0] = (charNum >> 10) + 0xD800; + buf[1] = (charNum & 0x3FF) + 0xDC00; + return 2; + } + return 0; +} + +struct unknown_encoding { + struct normal_encoding normal; + int (*convert)(void *userData, const char *p); + void *userData; + unsigned short utf16[256]; + char utf8[256][4]; +}; + +int XmlSizeOfUnknownEncoding(void) +{ + return sizeof(struct unknown_encoding); +} + +static +int unknown_isName(const ENCODING *enc, const char *p) +{ + int c = ((const struct unknown_encoding *)enc) + ->convert(((const struct unknown_encoding *)enc)->userData, p); + if (c & ~0xFFFF) + return 0; + return UCS2_GET_NAMING(namePages, c >> 8, c & 0xFF); +} + +static +int unknown_isNmstrt(const ENCODING *enc, const char *p) +{ + int c = ((const struct unknown_encoding *)enc) + ->convert(((const struct unknown_encoding *)enc)->userData, p); + if (c & ~0xFFFF) + return 0; + return UCS2_GET_NAMING(nmstrtPages, c >> 8, c & 0xFF); +} + +static +int unknown_isInvalid(const ENCODING *enc, const char *p) +{ + int c = ((const struct unknown_encoding *)enc) + ->convert(((const struct unknown_encoding *)enc)->userData, p); + return (c & ~0xFFFF) || checkCharRefNumber(c) < 0; +} + +static +void unknown_toUtf8(const ENCODING *enc, + const char **fromP, const char *fromLim, + char **toP, const char *toLim) +{ + char buf[XML_UTF8_ENCODE_MAX]; + for (;;) { + const char *utf8; + int n; + if (*fromP == fromLim) + break; + utf8 = ((const struct unknown_encoding *)enc)->utf8[(unsigned char)**fromP]; + n = *utf8++; + if (n == 0) { + int c = ((const struct unknown_encoding *)enc) + ->convert(((const struct unknown_encoding *)enc)->userData, *fromP); + n = XmlUtf8Encode(c, buf); + if (n > toLim - *toP) + break; + utf8 = buf; + *fromP += ((const struct normal_encoding *)enc)->type[(unsigned char)**fromP] + - (BT_LEAD2 - 2); + } + else { + if (n > toLim - *toP) + break; + (*fromP)++; + } + do { + *(*toP)++ = *utf8++; + } while (--n != 0); + } +} + +static +void unknown_toUtf16(const ENCODING *enc, + const char **fromP, const char *fromLim, + unsigned short **toP, const unsigned short *toLim) +{ + while (*fromP != fromLim && *toP != toLim) { + unsigned short c + = ((const struct unknown_encoding *)enc)->utf16[(unsigned char)**fromP]; + if (c == 0) { + c = (unsigned short)((const struct unknown_encoding *)enc) + ->convert(((const struct unknown_encoding *)enc)->userData, *fromP); + *fromP += ((const struct normal_encoding *)enc)->type[(unsigned char)**fromP] + - (BT_LEAD2 - 2); + } + else + (*fromP)++; + *(*toP)++ = c; + } +} + +ENCODING * +XmlInitUnknownEncoding(void *mem, + int *table, + int (*convert)(void *userData, const char *p), + void *userData) +{ + int i; + struct unknown_encoding *e = mem; + for (i = 0; i < sizeof(struct normal_encoding); i++) + ((char *)mem)[i] = ((char *)&latin1_encoding)[i]; + for (i = 0; i < 128; i++) + if (latin1_encoding.type[i] != BT_OTHER + && latin1_encoding.type[i] != BT_NONXML + && table[i] != i) + return 0; + for (i = 0; i < 256; i++) { + int c = table[i]; + if (c == -1) { + e->normal.type[i] = BT_MALFORM; + /* This shouldn't really get used. */ + e->utf16[i] = 0xFFFF; + e->utf8[i][0] = 1; + e->utf8[i][1] = 0; + } + else if (c < 0) { + if (c < -4) + return 0; + e->normal.type[i] = BT_LEAD2 - (c + 2); + e->utf8[i][0] = 0; + e->utf16[i] = 0; + } + else if (c < 0x80) { + if (latin1_encoding.type[c] != BT_OTHER + && latin1_encoding.type[c] != BT_NONXML + && c != i) + return 0; + e->normal.type[i] = latin1_encoding.type[c]; + e->utf8[i][0] = 1; + e->utf8[i][1] = (char)c; + e->utf16[i] = c == 0 ? 0xFFFF : c; + } + else if (checkCharRefNumber(c) < 0) { + e->normal.type[i] = BT_NONXML; + /* This shouldn't really get used. */ + e->utf16[i] = 0xFFFF; + e->utf8[i][0] = 1; + e->utf8[i][1] = 0; + } + else { + if (c > 0xFFFF) + return 0; + if (UCS2_GET_NAMING(nmstrtPages, c >> 8, c & 0xff)) + e->normal.type[i] = BT_NMSTRT; + else if (UCS2_GET_NAMING(namePages, c >> 8, c & 0xff)) + e->normal.type[i] = BT_NAME; + else + e->normal.type[i] = BT_OTHER; + e->utf8[i][0] = (char)XmlUtf8Encode(c, e->utf8[i] + 1); + e->utf16[i] = c; + } + } + e->userData = userData; + e->convert = convert; + if (convert) { + e->normal.isName2 = unknown_isName; + e->normal.isName3 = unknown_isName; + e->normal.isName4 = unknown_isName; + e->normal.isNmstrt2 = unknown_isNmstrt; + e->normal.isNmstrt3 = unknown_isNmstrt; + e->normal.isNmstrt4 = unknown_isNmstrt; + e->normal.isInvalid2 = unknown_isInvalid; + e->normal.isInvalid3 = unknown_isInvalid; + e->normal.isInvalid4 = unknown_isInvalid; + } + e->normal.enc.utf8Convert = unknown_toUtf8; + e->normal.enc.utf16Convert = unknown_toUtf16; + return &(e->normal.enc); +} + +/* If this enumeration is changed, getEncodingIndex and encodings +must also be changed. */ +enum { + UNKNOWN_ENC = -1, + ISO_8859_1_ENC = 0, + US_ASCII_ENC, + UTF_8_ENC, + UTF_16_ENC, + UTF_16BE_ENC, + UTF_16LE_ENC, + /* must match encodingNames up to here */ + NO_ENC +}; + +static +int getEncodingIndex(const char *name) +{ + static const char *encodingNames[] = { + "ISO-8859-1", + "US-ASCII", + "UTF-8", + "UTF-16", + "UTF-16BE" + "UTF-16LE", + }; + int i; + if (name == 0) + return NO_ENC; + for (i = 0; i < sizeof(encodingNames)/sizeof(encodingNames[0]); i++) + if (streqci(name, encodingNames[i])) + return i; + return UNKNOWN_ENC; +} + +/* For binary compatibility, we store the index of the encoding specified +at initialization in the isUtf16 member. */ + +#define INIT_ENC_INDEX(enc) ((enc)->initEnc.isUtf16) + +/* This is what detects the encoding. +encodingTable maps from encoding indices to encodings; +INIT_ENC_INDEX(enc) is the index of the external (protocol) specified encoding; +state is XML_CONTENT_STATE if we're parsing an external text entity, +and XML_PROLOG_STATE otherwise. +*/ + + +static +int initScan(const ENCODING **encodingTable, + const INIT_ENCODING *enc, + int state, + const char *ptr, + const char *end, + const char **nextTokPtr) +{ + const ENCODING **encPtr; + + if (ptr == end) + return XML_TOK_NONE; + encPtr = enc->encPtr; + if (ptr + 1 == end) { + /* only a single byte available for auto-detection */ + /* a well-formed document entity must have more than one byte */ + if (state != XML_CONTENT_STATE) + return XML_TOK_PARTIAL; + /* so we're parsing an external text entity... */ + /* if UTF-16 was externally specified, then we need at least 2 bytes */ + switch (INIT_ENC_INDEX(enc)) { + case UTF_16_ENC: + case UTF_16LE_ENC: + case UTF_16BE_ENC: + return XML_TOK_PARTIAL; + } + switch ((unsigned char)*ptr) { + case 0xFE: + case 0xFF: + case 0xEF: /* possibly first byte of UTF-8 BOM */ + if (INIT_ENC_INDEX(enc) == ISO_8859_1_ENC + && state == XML_CONTENT_STATE) + break; + /* fall through */ + case 0x00: + case 0x3C: + return XML_TOK_PARTIAL; + } + } + else { + switch (((unsigned char)ptr[0] << 8) | (unsigned char)ptr[1]) { + case 0xFEFF: + if (INIT_ENC_INDEX(enc) == ISO_8859_1_ENC + && state == XML_CONTENT_STATE) + break; + *nextTokPtr = ptr + 2; + *encPtr = encodingTable[UTF_16BE_ENC]; + return XML_TOK_BOM; + /* 00 3C is handled in the default case */ + case 0x3C00: + if ((INIT_ENC_INDEX(enc) == UTF_16BE_ENC + || INIT_ENC_INDEX(enc) == UTF_16_ENC) + && state == XML_CONTENT_STATE) + break; + *encPtr = encodingTable[UTF_16LE_ENC]; + return XmlTok(*encPtr, state, ptr, end, nextTokPtr); + case 0xFFFE: + if (INIT_ENC_INDEX(enc) == ISO_8859_1_ENC + && state == XML_CONTENT_STATE) + break; + *nextTokPtr = ptr + 2; + *encPtr = encodingTable[UTF_16LE_ENC]; + return XML_TOK_BOM; + case 0xEFBB: + /* Maybe a UTF-8 BOM (EF BB BF) */ + /* If there's an explicitly specified (external) encoding + of ISO-8859-1 or some flavour of UTF-16 + and this is an external text entity, + don't look for the BOM, + because it might be a legal data. */ + if (state == XML_CONTENT_STATE) { + int e = INIT_ENC_INDEX(enc); + if (e == ISO_8859_1_ENC || e == UTF_16BE_ENC || e == UTF_16LE_ENC || e == UTF_16_ENC) + break; + } + if (ptr + 2 == end) + return XML_TOK_PARTIAL; + if ((unsigned char)ptr[2] == 0xBF) { + *encPtr = encodingTable[UTF_8_ENC]; + return XML_TOK_BOM; + } + break; + default: + if (ptr[0] == '\0') { + /* 0 isn't a legal data character. Furthermore a document entity can only + start with ASCII characters. So the only way this can fail to be big-endian + UTF-16 if it it's an external parsed general entity that's labelled as + UTF-16LE. */ + if (state == XML_CONTENT_STATE && INIT_ENC_INDEX(enc) == UTF_16LE_ENC) + break; + *encPtr = encodingTable[UTF_16BE_ENC]; + return XmlTok(*encPtr, state, ptr, end, nextTokPtr); + } + else if (ptr[1] == '\0') { + /* We could recover here in the case: + - parsing an external entity + - second byte is 0 + - no externally specified encoding + - no encoding declaration + by assuming UTF-16LE. But we don't, because this would mean when + presented just with a single byte, we couldn't reliably determine + whether we needed further bytes. */ + if (state == XML_CONTENT_STATE) + break; + *encPtr = encodingTable[UTF_16LE_ENC]; + return XmlTok(*encPtr, state, ptr, end, nextTokPtr); + } + break; + } + } + *encPtr = encodingTable[(int)INIT_ENC_INDEX(enc)]; + return XmlTok(*encPtr, state, ptr, end, nextTokPtr); +} + + +#define NS(x) x +#define ns(x) x +#include "xmltok_ns.c" +#undef NS +#undef ns + +#ifdef XML_NS + +#define NS(x) x ## NS +#define ns(x) x ## _ns + +#include "xmltok_ns.c" + +#undef NS +#undef ns + +ENCODING * +XmlInitUnknownEncodingNS(void *mem, + int *table, + int (*convert)(void *userData, const char *p), + void *userData) +{ + ENCODING *enc = XmlInitUnknownEncoding(mem, table, convert, userData); + if (enc) + ((struct normal_encoding *)enc)->type[':'] = BT_COLON; + return enc; +} + +#endif /* XML_NS */ diff --git a/srclib/expat-lite/xmltok.h b/srclib/expat-lite/xmltok.h new file mode 100644 index 0000000000..fd0ed08e34 --- /dev/null +++ b/srclib/expat-lite/xmltok.h @@ -0,0 +1,307 @@ +/* +The contents of this file are subject to the Mozilla Public License +Version 1.1 (the "License"); you may not use this file except in +compliance with the License. You may obtain a copy of the License at +http://www.mozilla.org/MPL/ + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the +License for the specific language governing rights and limitations +under the License. + +The Original Code is expat. + +The Initial Developer of the Original Code is James Clark. +Portions created by James Clark are Copyright (C) 1998, 1999 +James Clark. All Rights Reserved. + +Contributor(s): + +Alternatively, the contents of this file may be used under the terms +of the GNU General Public License (the "GPL"), in which case the +provisions of the GPL are applicable instead of those above. If you +wish to allow use of your version of this file only under the terms of +the GPL and not to allow others to use your version of this file under +the MPL, indicate your decision by deleting the provisions above and +replace them with the notice and other provisions required by the +GPL. If you do not delete the provisions above, a recipient may use +your version of this file under either the MPL or the GPL. +*/ + +#ifndef XmlTok_INCLUDED +#define XmlTok_INCLUDED 1 + +#ifdef __cplusplus +extern "C" { +#endif + +#ifndef XMLTOKAPI +#define XMLTOKAPI /* as nothing */ +#endif + +/* The following token may be returned by XmlContentTok */ +#define XML_TOK_TRAILING_RSQB -5 /* ] or ]] at the end of the scan; might be start of + illegal ]]> sequence */ +/* The following tokens may be returned by both XmlPrologTok and XmlContentTok */ +#define XML_TOK_NONE -4 /* The string to be scanned is empty */ +#define XML_TOK_TRAILING_CR -3 /* A CR at the end of the scan; + might be part of CRLF sequence */ +#define XML_TOK_PARTIAL_CHAR -2 /* only part of a multibyte sequence */ +#define XML_TOK_PARTIAL -1 /* only part of a token */ +#define XML_TOK_INVALID 0 + +/* The following tokens are returned by XmlContentTok; some are also + returned by XmlAttributeValueTok, XmlEntityTok, XmlCdataSectionTok */ + +#define XML_TOK_START_TAG_WITH_ATTS 1 +#define XML_TOK_START_TAG_NO_ATTS 2 +#define XML_TOK_EMPTY_ELEMENT_WITH_ATTS 3 /* empty element tag <e/> */ +#define XML_TOK_EMPTY_ELEMENT_NO_ATTS 4 +#define XML_TOK_END_TAG 5 +#define XML_TOK_DATA_CHARS 6 +#define XML_TOK_DATA_NEWLINE 7 +#define XML_TOK_CDATA_SECT_OPEN 8 +#define XML_TOK_ENTITY_REF 9 +#define XML_TOK_CHAR_REF 10 /* numeric character reference */ + +/* The following tokens may be returned by both XmlPrologTok and XmlContentTok */ +#define XML_TOK_PI 11 /* processing instruction */ +#define XML_TOK_XML_DECL 12 /* XML decl or text decl */ +#define XML_TOK_COMMENT 13 +#define XML_TOK_BOM 14 /* Byte order mark */ + +/* The following tokens are returned only by XmlPrologTok */ +#define XML_TOK_PROLOG_S 15 +#define XML_TOK_DECL_OPEN 16 /* <!foo */ +#define XML_TOK_DECL_CLOSE 17 /* > */ +#define XML_TOK_NAME 18 +#define XML_TOK_NMTOKEN 19 +#define XML_TOK_POUND_NAME 20 /* #name */ +#define XML_TOK_OR 21 /* | */ +#define XML_TOK_PERCENT 22 +#define XML_TOK_OPEN_PAREN 23 +#define XML_TOK_CLOSE_PAREN 24 +#define XML_TOK_OPEN_BRACKET 25 +#define XML_TOK_CLOSE_BRACKET 26 +#define XML_TOK_LITERAL 27 +#define XML_TOK_PARAM_ENTITY_REF 28 +#define XML_TOK_INSTANCE_START 29 + +/* The following occur only in element type declarations */ +#define XML_TOK_NAME_QUESTION 30 /* name? */ +#define XML_TOK_NAME_ASTERISK 31 /* name* */ +#define XML_TOK_NAME_PLUS 32 /* name+ */ +#define XML_TOK_COND_SECT_OPEN 33 /* <![ */ +#define XML_TOK_COND_SECT_CLOSE 34 /* ]]> */ +#define XML_TOK_CLOSE_PAREN_QUESTION 35 /* )? */ +#define XML_TOK_CLOSE_PAREN_ASTERISK 36 /* )* */ +#define XML_TOK_CLOSE_PAREN_PLUS 37 /* )+ */ +#define XML_TOK_COMMA 38 + +/* The following token is returned only by XmlAttributeValueTok */ +#define XML_TOK_ATTRIBUTE_VALUE_S 39 + +/* The following token is returned only by XmlCdataSectionTok */ +#define XML_TOK_CDATA_SECT_CLOSE 40 + +/* With namespace processing this is returned by XmlPrologTok + for a name with a colon. */ +#define XML_TOK_PREFIXED_NAME 41 + +#define XML_N_STATES 3 +#define XML_PROLOG_STATE 0 +#define XML_CONTENT_STATE 1 +#define XML_CDATA_SECTION_STATE 2 + +#define XML_N_LITERAL_TYPES 2 +#define XML_ATTRIBUTE_VALUE_LITERAL 0 +#define XML_ENTITY_VALUE_LITERAL 1 + +/* The size of the buffer passed to XmlUtf8Encode must be at least this. */ +#define XML_UTF8_ENCODE_MAX 4 +/* The size of the buffer passed to XmlUtf16Encode must be at least this. */ +#define XML_UTF16_ENCODE_MAX 2 + +typedef struct position { + /* first line and first column are 0 not 1 */ + unsigned long lineNumber; + unsigned long columnNumber; +} POSITION; + +typedef struct { + const char *name; + const char *valuePtr; + const char *valueEnd; + char normalized; +} ATTRIBUTE; + +struct encoding; +typedef struct encoding ENCODING; + +struct encoding { + int (*scanners[XML_N_STATES])(const ENCODING *, + const char *, + const char *, + const char **); + int (*literalScanners[XML_N_LITERAL_TYPES])(const ENCODING *, + const char *, + const char *, + const char **); + int (*sameName)(const ENCODING *, + const char *, const char *); + int (*nameMatchesAscii)(const ENCODING *, + const char *, const char *); + int (*nameLength)(const ENCODING *, const char *); + const char *(*skipS)(const ENCODING *, const char *); + int (*getAtts)(const ENCODING *enc, const char *ptr, + int attsMax, ATTRIBUTE *atts); + int (*charRefNumber)(const ENCODING *enc, const char *ptr); + int (*predefinedEntityName)(const ENCODING *, const char *, const char *); + void (*updatePosition)(const ENCODING *, + const char *ptr, + const char *end, + POSITION *); + int (*isPublicId)(const ENCODING *enc, const char *ptr, const char *end, + const char **badPtr); + void (*utf8Convert)(const ENCODING *enc, + const char **fromP, + const char *fromLim, + char **toP, + const char *toLim); + void (*utf16Convert)(const ENCODING *enc, + const char **fromP, + const char *fromLim, + unsigned short **toP, + const unsigned short *toLim); + int minBytesPerChar; + char isUtf8; + char isUtf16; +}; + +/* +Scan the string starting at ptr until the end of the next complete token, +but do not scan past eptr. Return an integer giving the type of token. + +Return XML_TOK_NONE when ptr == eptr; nextTokPtr will not be set. + +Return XML_TOK_PARTIAL when the string does not contain a complete token; +nextTokPtr will not be set. + +Return XML_TOK_INVALID when the string does not start a valid token; nextTokPtr +will be set to point to the character which made the token invalid. + +Otherwise the string starts with a valid token; nextTokPtr will be set to point +to the character following the end of that token. + +Each data character counts as a single token, but adjacent data characters +may be returned together. Similarly for characters in the prolog outside +literals, comments and processing instructions. +*/ + + +#define XmlTok(enc, state, ptr, end, nextTokPtr) \ + (((enc)->scanners[state])(enc, ptr, end, nextTokPtr)) + +#define XmlPrologTok(enc, ptr, end, nextTokPtr) \ + XmlTok(enc, XML_PROLOG_STATE, ptr, end, nextTokPtr) + +#define XmlContentTok(enc, ptr, end, nextTokPtr) \ + XmlTok(enc, XML_CONTENT_STATE, ptr, end, nextTokPtr) + +#define XmlCdataSectionTok(enc, ptr, end, nextTokPtr) \ + XmlTok(enc, XML_CDATA_SECTION_STATE, ptr, end, nextTokPtr) + +/* This is used for performing a 2nd-level tokenization on +the content of a literal that has already been returned by XmlTok. */ + +#define XmlLiteralTok(enc, literalType, ptr, end, nextTokPtr) \ + (((enc)->literalScanners[literalType])(enc, ptr, end, nextTokPtr)) + +#define XmlAttributeValueTok(enc, ptr, end, nextTokPtr) \ + XmlLiteralTok(enc, XML_ATTRIBUTE_VALUE_LITERAL, ptr, end, nextTokPtr) + +#define XmlEntityValueTok(enc, ptr, end, nextTokPtr) \ + XmlLiteralTok(enc, XML_ENTITY_VALUE_LITERAL, ptr, end, nextTokPtr) + +#define XmlSameName(enc, ptr1, ptr2) (((enc)->sameName)(enc, ptr1, ptr2)) + +#define XmlNameMatchesAscii(enc, ptr1, ptr2) \ + (((enc)->nameMatchesAscii)(enc, ptr1, ptr2)) + +#define XmlNameLength(enc, ptr) \ + (((enc)->nameLength)(enc, ptr)) + +#define XmlSkipS(enc, ptr) \ + (((enc)->skipS)(enc, ptr)) + +#define XmlGetAttributes(enc, ptr, attsMax, atts) \ + (((enc)->getAtts)(enc, ptr, attsMax, atts)) + +#define XmlCharRefNumber(enc, ptr) \ + (((enc)->charRefNumber)(enc, ptr)) + +#define XmlPredefinedEntityName(enc, ptr, end) \ + (((enc)->predefinedEntityName)(enc, ptr, end)) + +#define XmlUpdatePosition(enc, ptr, end, pos) \ + (((enc)->updatePosition)(enc, ptr, end, pos)) + +#define XmlIsPublicId(enc, ptr, end, badPtr) \ + (((enc)->isPublicId)(enc, ptr, end, badPtr)) + +#define XmlUtf8Convert(enc, fromP, fromLim, toP, toLim) \ + (((enc)->utf8Convert)(enc, fromP, fromLim, toP, toLim)) + +#define XmlUtf16Convert(enc, fromP, fromLim, toP, toLim) \ + (((enc)->utf16Convert)(enc, fromP, fromLim, toP, toLim)) + +typedef struct { + ENCODING initEnc; + const ENCODING **encPtr; +} INIT_ENCODING; + +int XMLTOKAPI XmlParseXmlDecl(int isGeneralTextEntity, + const ENCODING *enc, + const char *ptr, + const char *end, + const char **badPtr, + const char **versionPtr, + const char **encodingNamePtr, + const ENCODING **namedEncodingPtr, + int *standalonePtr); + +int XMLTOKAPI XmlInitEncoding(INIT_ENCODING *, const ENCODING **, const char *name); +const ENCODING XMLTOKAPI *XmlGetUtf8InternalEncoding(void); +const ENCODING XMLTOKAPI *XmlGetUtf16InternalEncoding(void); +int XMLTOKAPI XmlUtf8Encode(int charNumber, char *buf); +int XMLTOKAPI XmlUtf16Encode(int charNumber, unsigned short *buf); + +int XMLTOKAPI XmlSizeOfUnknownEncoding(void); +ENCODING XMLTOKAPI * +XmlInitUnknownEncoding(void *mem, + int *table, + int (*conv)(void *userData, const char *p), + void *userData); + +int XMLTOKAPI XmlParseXmlDeclNS(int isGeneralTextEntity, + const ENCODING *enc, + const char *ptr, + const char *end, + const char **badPtr, + const char **versionPtr, + const char **encodingNamePtr, + const ENCODING **namedEncodingPtr, + int *standalonePtr); +int XMLTOKAPI XmlInitEncodingNS(INIT_ENCODING *, const ENCODING **, const char *name); +const ENCODING XMLTOKAPI *XmlGetUtf8InternalEncodingNS(void); +const ENCODING XMLTOKAPI *XmlGetUtf16InternalEncodingNS(void); +ENCODING XMLTOKAPI * +XmlInitUnknownEncodingNS(void *mem, + int *table, + int (*conv)(void *userData, const char *p), + void *userData); +#ifdef __cplusplus +} +#endif + +#endif /* not XmlTok_INCLUDED */ diff --git a/srclib/expat-lite/xmltok_impl.c b/srclib/expat-lite/xmltok_impl.c new file mode 100644 index 0000000000..c52539be8a --- /dev/null +++ b/srclib/expat-lite/xmltok_impl.c @@ -0,0 +1,1746 @@ +/* +The contents of this file are subject to the Mozilla Public License +Version 1.1 (the "License"); you may not use this file except in +compliance with the License. You may obtain a copy of the License at +http://www.mozilla.org/MPL/ + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the +License for the specific language governing rights and limitations +under the License. + +The Original Code is expat. + +The Initial Developer of the Original Code is James Clark. +Portions created by James Clark are Copyright (C) 1998, 1999 +James Clark. All Rights Reserved. + +Contributor(s): + +Alternatively, the contents of this file may be used under the terms +of the GNU General Public License (the "GPL"), in which case the +provisions of the GPL are applicable instead of those above. If you +wish to allow use of your version of this file only under the terms of +the GPL and not to allow others to use your version of this file under +the MPL, indicate your decision by deleting the provisions above and +replace them with the notice and other provisions required by the +GPL. If you do not delete the provisions above, a recipient may use +your version of this file under either the MPL or the GPL. +*/ + +#ifndef IS_INVALID_CHAR +#define IS_INVALID_CHAR(enc, ptr, n) (0) +#endif + +#define INVALID_LEAD_CASE(n, ptr, nextTokPtr) \ + case BT_LEAD ## n: \ + if (end - ptr < n) \ + return XML_TOK_PARTIAL_CHAR; \ + if (IS_INVALID_CHAR(enc, ptr, n)) { \ + *(nextTokPtr) = (ptr); \ + return XML_TOK_INVALID; \ + } \ + ptr += n; \ + break; + +#define INVALID_CASES(ptr, nextTokPtr) \ + INVALID_LEAD_CASE(2, ptr, nextTokPtr) \ + INVALID_LEAD_CASE(3, ptr, nextTokPtr) \ + INVALID_LEAD_CASE(4, ptr, nextTokPtr) \ + case BT_NONXML: \ + case BT_MALFORM: \ + case BT_TRAIL: \ + *(nextTokPtr) = (ptr); \ + return XML_TOK_INVALID; + +#define CHECK_NAME_CASE(n, enc, ptr, end, nextTokPtr) \ + case BT_LEAD ## n: \ + if (end - ptr < n) \ + return XML_TOK_PARTIAL_CHAR; \ + if (!IS_NAME_CHAR(enc, ptr, n)) { \ + *nextTokPtr = ptr; \ + return XML_TOK_INVALID; \ + } \ + ptr += n; \ + break; + +#define CHECK_NAME_CASES(enc, ptr, end, nextTokPtr) \ + case BT_NONASCII: \ + if (!IS_NAME_CHAR_MINBPC(enc, ptr)) { \ + *nextTokPtr = ptr; \ + return XML_TOK_INVALID; \ + } \ + case BT_NMSTRT: \ + case BT_HEX: \ + case BT_DIGIT: \ + case BT_NAME: \ + case BT_MINUS: \ + ptr += MINBPC(enc); \ + break; \ + CHECK_NAME_CASE(2, enc, ptr, end, nextTokPtr) \ + CHECK_NAME_CASE(3, enc, ptr, end, nextTokPtr) \ + CHECK_NAME_CASE(4, enc, ptr, end, nextTokPtr) + +#define CHECK_NMSTRT_CASE(n, enc, ptr, end, nextTokPtr) \ + case BT_LEAD ## n: \ + if (end - ptr < n) \ + return XML_TOK_PARTIAL_CHAR; \ + if (!IS_NMSTRT_CHAR(enc, ptr, n)) { \ + *nextTokPtr = ptr; \ + return XML_TOK_INVALID; \ + } \ + ptr += n; \ + break; + +#define CHECK_NMSTRT_CASES(enc, ptr, end, nextTokPtr) \ + case BT_NONASCII: \ + if (!IS_NMSTRT_CHAR_MINBPC(enc, ptr)) { \ + *nextTokPtr = ptr; \ + return XML_TOK_INVALID; \ + } \ + case BT_NMSTRT: \ + case BT_HEX: \ + ptr += MINBPC(enc); \ + break; \ + CHECK_NMSTRT_CASE(2, enc, ptr, end, nextTokPtr) \ + CHECK_NMSTRT_CASE(3, enc, ptr, end, nextTokPtr) \ + CHECK_NMSTRT_CASE(4, enc, ptr, end, nextTokPtr) + +#ifndef PREFIX +#define PREFIX(ident) ident +#endif + +/* ptr points to character following "<!-" */ + +static +int PREFIX(scanComment)(const ENCODING *enc, const char *ptr, const char *end, + const char **nextTokPtr) +{ + if (ptr != end) { + if (!CHAR_MATCHES(enc, ptr, '-')) { + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + ptr += MINBPC(enc); + while (ptr != end) { + switch (BYTE_TYPE(enc, ptr)) { + INVALID_CASES(ptr, nextTokPtr) + case BT_MINUS: + if ((ptr += MINBPC(enc)) == end) + return XML_TOK_PARTIAL; + if (CHAR_MATCHES(enc, ptr, '-')) { + if ((ptr += MINBPC(enc)) == end) + return XML_TOK_PARTIAL; + if (!CHAR_MATCHES(enc, ptr, '>')) { + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + *nextTokPtr = ptr + MINBPC(enc); + return XML_TOK_COMMENT; + } + break; + default: + ptr += MINBPC(enc); + break; + } + } + } + return XML_TOK_PARTIAL; +} + +/* ptr points to character following "<!" */ + +static +int PREFIX(scanDecl)(const ENCODING *enc, const char *ptr, const char *end, + const char **nextTokPtr) +{ + if (ptr == end) + return XML_TOK_PARTIAL; + switch (BYTE_TYPE(enc, ptr)) { + case BT_MINUS: + return PREFIX(scanComment)(enc, ptr + MINBPC(enc), end, nextTokPtr); + case BT_LSQB: + *nextTokPtr = ptr + MINBPC(enc); + return XML_TOK_COND_SECT_OPEN; + case BT_NMSTRT: + case BT_HEX: + ptr += MINBPC(enc); + break; + default: + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + while (ptr != end) { + switch (BYTE_TYPE(enc, ptr)) { + case BT_PERCNT: + if (ptr + MINBPC(enc) == end) + return XML_TOK_PARTIAL; + /* don't allow <!ENTITY% foo "whatever"> */ + switch (BYTE_TYPE(enc, ptr + MINBPC(enc))) { + case BT_S: case BT_CR: case BT_LF: case BT_PERCNT: + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + /* fall through */ + case BT_S: case BT_CR: case BT_LF: + *nextTokPtr = ptr; + return XML_TOK_DECL_OPEN; + case BT_NMSTRT: + case BT_HEX: + ptr += MINBPC(enc); + break; + default: + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + } + return XML_TOK_PARTIAL; +} + +static +int PREFIX(checkPiTarget)(const ENCODING *enc, const char *ptr, const char *end, int *tokPtr) +{ + int upper = 0; + *tokPtr = XML_TOK_PI; + if (end - ptr != MINBPC(enc)*3) + return 1; + switch (BYTE_TO_ASCII(enc, ptr)) { + case 'x': + break; + case 'X': + upper = 1; + break; + default: + return 1; + } + ptr += MINBPC(enc); + switch (BYTE_TO_ASCII(enc, ptr)) { + case 'm': + break; + case 'M': + upper = 1; + break; + default: + return 1; + } + ptr += MINBPC(enc); + switch (BYTE_TO_ASCII(enc, ptr)) { + case 'l': + break; + case 'L': + upper = 1; + break; + default: + return 1; + } + if (upper) + return 0; + *tokPtr = XML_TOK_XML_DECL; + return 1; +} + +/* ptr points to character following "<?" */ + +static +int PREFIX(scanPi)(const ENCODING *enc, const char *ptr, const char *end, + const char **nextTokPtr) +{ + int tok; + const char *target = ptr; + if (ptr == end) + return XML_TOK_PARTIAL; + switch (BYTE_TYPE(enc, ptr)) { + CHECK_NMSTRT_CASES(enc, ptr, end, nextTokPtr) + default: + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + while (ptr != end) { + switch (BYTE_TYPE(enc, ptr)) { + CHECK_NAME_CASES(enc, ptr, end, nextTokPtr) + case BT_S: case BT_CR: case BT_LF: + if (!PREFIX(checkPiTarget)(enc, target, ptr, &tok)) { + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + ptr += MINBPC(enc); + while (ptr != end) { + switch (BYTE_TYPE(enc, ptr)) { + INVALID_CASES(ptr, nextTokPtr) + case BT_QUEST: + ptr += MINBPC(enc); + if (ptr == end) + return XML_TOK_PARTIAL; + if (CHAR_MATCHES(enc, ptr, '>')) { + *nextTokPtr = ptr + MINBPC(enc); + return tok; + } + break; + default: + ptr += MINBPC(enc); + break; + } + } + return XML_TOK_PARTIAL; + case BT_QUEST: + if (!PREFIX(checkPiTarget)(enc, target, ptr, &tok)) { + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + ptr += MINBPC(enc); + if (ptr == end) + return XML_TOK_PARTIAL; + if (CHAR_MATCHES(enc, ptr, '>')) { + *nextTokPtr = ptr + MINBPC(enc); + return tok; + } + /* fall through */ + default: + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + } + return XML_TOK_PARTIAL; +} + + +static +int PREFIX(scanCdataSection)(const ENCODING *enc, const char *ptr, const char *end, + const char **nextTokPtr) +{ + int i; + /* CDATA[ */ + if (end - ptr < 6 * MINBPC(enc)) + return XML_TOK_PARTIAL; + for (i = 0; i < 6; i++, ptr += MINBPC(enc)) { + if (!CHAR_MATCHES(enc, ptr, "CDATA["[i])) { + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + } + *nextTokPtr = ptr; + return XML_TOK_CDATA_SECT_OPEN; +} + +static +int PREFIX(cdataSectionTok)(const ENCODING *enc, const char *ptr, const char *end, + const char **nextTokPtr) +{ + if (ptr == end) + return XML_TOK_NONE; + if (MINBPC(enc) > 1) { + size_t n = end - ptr; + if (n & (MINBPC(enc) - 1)) { + n &= ~(MINBPC(enc) - 1); + if (n == 0) + return XML_TOK_PARTIAL; + end = ptr + n; + } + } + switch (BYTE_TYPE(enc, ptr)) { + case BT_RSQB: + ptr += MINBPC(enc); + if (ptr == end) + return XML_TOK_PARTIAL; + if (!CHAR_MATCHES(enc, ptr, ']')) + break; + ptr += MINBPC(enc); + if (ptr == end) + return XML_TOK_PARTIAL; + if (!CHAR_MATCHES(enc, ptr, '>')) { + ptr -= MINBPC(enc); + break; + } + *nextTokPtr = ptr + MINBPC(enc); + return XML_TOK_CDATA_SECT_CLOSE; + case BT_CR: + ptr += MINBPC(enc); + if (ptr == end) + return XML_TOK_PARTIAL; + if (BYTE_TYPE(enc, ptr) == BT_LF) + ptr += MINBPC(enc); + *nextTokPtr = ptr; + return XML_TOK_DATA_NEWLINE; + case BT_LF: + *nextTokPtr = ptr + MINBPC(enc); + return XML_TOK_DATA_NEWLINE; + INVALID_CASES(ptr, nextTokPtr) + default: + ptr += MINBPC(enc); + break; + } + while (ptr != end) { + switch (BYTE_TYPE(enc, ptr)) { +#define LEAD_CASE(n) \ + case BT_LEAD ## n: \ + if (end - ptr < n || IS_INVALID_CHAR(enc, ptr, n)) { \ + *nextTokPtr = ptr; \ + return XML_TOK_DATA_CHARS; \ + } \ + ptr += n; \ + break; + LEAD_CASE(2) LEAD_CASE(3) LEAD_CASE(4) +#undef LEAD_CASE + case BT_NONXML: + case BT_MALFORM: + case BT_TRAIL: + case BT_CR: + case BT_LF: + case BT_RSQB: + *nextTokPtr = ptr; + return XML_TOK_DATA_CHARS; + default: + ptr += MINBPC(enc); + break; + } + } + *nextTokPtr = ptr; + return XML_TOK_DATA_CHARS; +} + +/* ptr points to character following "</" */ + +static +int PREFIX(scanEndTag)(const ENCODING *enc, const char *ptr, const char *end, + const char **nextTokPtr) +{ + if (ptr == end) + return XML_TOK_PARTIAL; + switch (BYTE_TYPE(enc, ptr)) { + CHECK_NMSTRT_CASES(enc, ptr, end, nextTokPtr) + default: + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + while (ptr != end) { + switch (BYTE_TYPE(enc, ptr)) { + CHECK_NAME_CASES(enc, ptr, end, nextTokPtr) + case BT_S: case BT_CR: case BT_LF: + for (ptr += MINBPC(enc); ptr != end; ptr += MINBPC(enc)) { + switch (BYTE_TYPE(enc, ptr)) { + case BT_S: case BT_CR: case BT_LF: + break; + case BT_GT: + *nextTokPtr = ptr + MINBPC(enc); + return XML_TOK_END_TAG; + default: + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + } + return XML_TOK_PARTIAL; +#ifdef XML_NS + case BT_COLON: + /* no need to check qname syntax here, since end-tag must match exactly */ + ptr += MINBPC(enc); + break; +#endif + case BT_GT: + *nextTokPtr = ptr + MINBPC(enc); + return XML_TOK_END_TAG; + default: + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + } + return XML_TOK_PARTIAL; +} + +/* ptr points to character following "&#X" */ + +static +int PREFIX(scanHexCharRef)(const ENCODING *enc, const char *ptr, const char *end, + const char **nextTokPtr) +{ + if (ptr != end) { + switch (BYTE_TYPE(enc, ptr)) { + case BT_DIGIT: + case BT_HEX: + break; + default: + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + for (ptr += MINBPC(enc); ptr != end; ptr += MINBPC(enc)) { + switch (BYTE_TYPE(enc, ptr)) { + case BT_DIGIT: + case BT_HEX: + break; + case BT_SEMI: + *nextTokPtr = ptr + MINBPC(enc); + return XML_TOK_CHAR_REF; + default: + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + } + } + return XML_TOK_PARTIAL; +} + +/* ptr points to character following "&#" */ + +static +int PREFIX(scanCharRef)(const ENCODING *enc, const char *ptr, const char *end, + const char **nextTokPtr) +{ + if (ptr != end) { + if (CHAR_MATCHES(enc, ptr, 'x')) + return PREFIX(scanHexCharRef)(enc, ptr + MINBPC(enc), end, nextTokPtr); + switch (BYTE_TYPE(enc, ptr)) { + case BT_DIGIT: + break; + default: + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + for (ptr += MINBPC(enc); ptr != end; ptr += MINBPC(enc)) { + switch (BYTE_TYPE(enc, ptr)) { + case BT_DIGIT: + break; + case BT_SEMI: + *nextTokPtr = ptr + MINBPC(enc); + return XML_TOK_CHAR_REF; + default: + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + } + } + return XML_TOK_PARTIAL; +} + +/* ptr points to character following "&" */ + +static +int PREFIX(scanRef)(const ENCODING *enc, const char *ptr, const char *end, + const char **nextTokPtr) +{ + if (ptr == end) + return XML_TOK_PARTIAL; + switch (BYTE_TYPE(enc, ptr)) { + CHECK_NMSTRT_CASES(enc, ptr, end, nextTokPtr) + case BT_NUM: + return PREFIX(scanCharRef)(enc, ptr + MINBPC(enc), end, nextTokPtr); + default: + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + while (ptr != end) { + switch (BYTE_TYPE(enc, ptr)) { + CHECK_NAME_CASES(enc, ptr, end, nextTokPtr) + case BT_SEMI: + *nextTokPtr = ptr + MINBPC(enc); + return XML_TOK_ENTITY_REF; + default: + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + } + return XML_TOK_PARTIAL; +} + +/* ptr points to character following first character of attribute name */ + +static +int PREFIX(scanAtts)(const ENCODING *enc, const char *ptr, const char *end, + const char **nextTokPtr) +{ +#ifdef XML_NS + int hadColon = 0; +#endif + while (ptr != end) { + switch (BYTE_TYPE(enc, ptr)) { + CHECK_NAME_CASES(enc, ptr, end, nextTokPtr) +#ifdef XML_NS + case BT_COLON: + if (hadColon) { + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + hadColon = 1; + ptr += MINBPC(enc); + if (ptr == end) + return XML_TOK_PARTIAL; + switch (BYTE_TYPE(enc, ptr)) { + CHECK_NMSTRT_CASES(enc, ptr, end, nextTokPtr) + default: + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + break; +#endif + case BT_S: case BT_CR: case BT_LF: + for (;;) { + int t; + + ptr += MINBPC(enc); + if (ptr == end) + return XML_TOK_PARTIAL; + t = BYTE_TYPE(enc, ptr); + if (t == BT_EQUALS) + break; + switch (t) { + case BT_S: + case BT_LF: + case BT_CR: + break; + default: + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + } + /* fall through */ + case BT_EQUALS: + { + int open; +#ifdef XML_NS + hadColon = 0; +#endif + for (;;) { + + ptr += MINBPC(enc); + if (ptr == end) + return XML_TOK_PARTIAL; + open = BYTE_TYPE(enc, ptr); + if (open == BT_QUOT || open == BT_APOS) + break; + switch (open) { + case BT_S: + case BT_LF: + case BT_CR: + break; + default: + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + } + ptr += MINBPC(enc); + /* in attribute value */ + for (;;) { + int t; + if (ptr == end) + return XML_TOK_PARTIAL; + t = BYTE_TYPE(enc, ptr); + if (t == open) + break; + switch (t) { + INVALID_CASES(ptr, nextTokPtr) + case BT_AMP: + { + int tok = PREFIX(scanRef)(enc, ptr + MINBPC(enc), end, &ptr); + if (tok <= 0) { + if (tok == XML_TOK_INVALID) + *nextTokPtr = ptr; + return tok; + } + break; + } + case BT_LT: + *nextTokPtr = ptr; + return XML_TOK_INVALID; + default: + ptr += MINBPC(enc); + break; + } + } + ptr += MINBPC(enc); + if (ptr == end) + return XML_TOK_PARTIAL; + switch (BYTE_TYPE(enc, ptr)) { + case BT_S: + case BT_CR: + case BT_LF: + break; + case BT_SOL: + goto sol; + case BT_GT: + goto gt; + default: + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + /* ptr points to closing quote */ + for (;;) { + ptr += MINBPC(enc); + if (ptr == end) + return XML_TOK_PARTIAL; + switch (BYTE_TYPE(enc, ptr)) { + CHECK_NMSTRT_CASES(enc, ptr, end, nextTokPtr) + case BT_S: case BT_CR: case BT_LF: + continue; + case BT_GT: + gt: + *nextTokPtr = ptr + MINBPC(enc); + return XML_TOK_START_TAG_WITH_ATTS; + case BT_SOL: + sol: + ptr += MINBPC(enc); + if (ptr == end) + return XML_TOK_PARTIAL; + if (!CHAR_MATCHES(enc, ptr, '>')) { + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + *nextTokPtr = ptr + MINBPC(enc); + return XML_TOK_EMPTY_ELEMENT_WITH_ATTS; + default: + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + break; + } + break; + } + default: + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + } + return XML_TOK_PARTIAL; +} + +/* ptr points to character following "<" */ + +static +int PREFIX(scanLt)(const ENCODING *enc, const char *ptr, const char *end, + const char **nextTokPtr) +{ +#ifdef XML_NS + int hadColon; +#endif + if (ptr == end) + return XML_TOK_PARTIAL; + switch (BYTE_TYPE(enc, ptr)) { + CHECK_NMSTRT_CASES(enc, ptr, end, nextTokPtr) + case BT_EXCL: + if ((ptr += MINBPC(enc)) == end) + return XML_TOK_PARTIAL; + switch (BYTE_TYPE(enc, ptr)) { + case BT_MINUS: + return PREFIX(scanComment)(enc, ptr + MINBPC(enc), end, nextTokPtr); + case BT_LSQB: + return PREFIX(scanCdataSection)(enc, ptr + MINBPC(enc), end, nextTokPtr); + } + *nextTokPtr = ptr; + return XML_TOK_INVALID; + case BT_QUEST: + return PREFIX(scanPi)(enc, ptr + MINBPC(enc), end, nextTokPtr); + case BT_SOL: + return PREFIX(scanEndTag)(enc, ptr + MINBPC(enc), end, nextTokPtr); + default: + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } +#ifdef XML_NS + hadColon = 0; +#endif + /* we have a start-tag */ + while (ptr != end) { + switch (BYTE_TYPE(enc, ptr)) { + CHECK_NAME_CASES(enc, ptr, end, nextTokPtr) +#ifdef XML_NS + case BT_COLON: + if (hadColon) { + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + hadColon = 1; + ptr += MINBPC(enc); + if (ptr == end) + return XML_TOK_PARTIAL; + switch (BYTE_TYPE(enc, ptr)) { + CHECK_NMSTRT_CASES(enc, ptr, end, nextTokPtr) + default: + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + break; +#endif + case BT_S: case BT_CR: case BT_LF: + { + ptr += MINBPC(enc); + while (ptr != end) { + switch (BYTE_TYPE(enc, ptr)) { + CHECK_NMSTRT_CASES(enc, ptr, end, nextTokPtr) + case BT_GT: + goto gt; + case BT_SOL: + goto sol; + case BT_S: case BT_CR: case BT_LF: + ptr += MINBPC(enc); + continue; + default: + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + return PREFIX(scanAtts)(enc, ptr, end, nextTokPtr); + } + return XML_TOK_PARTIAL; + } + case BT_GT: + gt: + *nextTokPtr = ptr + MINBPC(enc); + return XML_TOK_START_TAG_NO_ATTS; + case BT_SOL: + sol: + ptr += MINBPC(enc); + if (ptr == end) + return XML_TOK_PARTIAL; + if (!CHAR_MATCHES(enc, ptr, '>')) { + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + *nextTokPtr = ptr + MINBPC(enc); + return XML_TOK_EMPTY_ELEMENT_NO_ATTS; + default: + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + } + return XML_TOK_PARTIAL; +} + +static +int PREFIX(contentTok)(const ENCODING *enc, const char *ptr, const char *end, + const char **nextTokPtr) +{ + if (ptr == end) + return XML_TOK_NONE; + if (MINBPC(enc) > 1) { + size_t n = end - ptr; + if (n & (MINBPC(enc) - 1)) { + n &= ~(MINBPC(enc) - 1); + if (n == 0) + return XML_TOK_PARTIAL; + end = ptr + n; + } + } + switch (BYTE_TYPE(enc, ptr)) { + case BT_LT: + return PREFIX(scanLt)(enc, ptr + MINBPC(enc), end, nextTokPtr); + case BT_AMP: + return PREFIX(scanRef)(enc, ptr + MINBPC(enc), end, nextTokPtr); + case BT_CR: + ptr += MINBPC(enc); + if (ptr == end) + return XML_TOK_TRAILING_CR; + if (BYTE_TYPE(enc, ptr) == BT_LF) + ptr += MINBPC(enc); + *nextTokPtr = ptr; + return XML_TOK_DATA_NEWLINE; + case BT_LF: + *nextTokPtr = ptr + MINBPC(enc); + return XML_TOK_DATA_NEWLINE; + case BT_RSQB: + ptr += MINBPC(enc); + if (ptr == end) + return XML_TOK_TRAILING_RSQB; + if (!CHAR_MATCHES(enc, ptr, ']')) + break; + ptr += MINBPC(enc); + if (ptr == end) + return XML_TOK_TRAILING_RSQB; + if (!CHAR_MATCHES(enc, ptr, '>')) { + ptr -= MINBPC(enc); + break; + } + *nextTokPtr = ptr; + return XML_TOK_INVALID; + INVALID_CASES(ptr, nextTokPtr) + default: + ptr += MINBPC(enc); + break; + } + while (ptr != end) { + switch (BYTE_TYPE(enc, ptr)) { +#define LEAD_CASE(n) \ + case BT_LEAD ## n: \ + if (end - ptr < n || IS_INVALID_CHAR(enc, ptr, n)) { \ + *nextTokPtr = ptr; \ + return XML_TOK_DATA_CHARS; \ + } \ + ptr += n; \ + break; + LEAD_CASE(2) LEAD_CASE(3) LEAD_CASE(4) +#undef LEAD_CASE + case BT_RSQB: + if (ptr + MINBPC(enc) != end) { + if (!CHAR_MATCHES(enc, ptr + MINBPC(enc), ']')) { + ptr += MINBPC(enc); + break; + } + if (ptr + 2*MINBPC(enc) != end) { + if (!CHAR_MATCHES(enc, ptr + 2*MINBPC(enc), '>')) { + ptr += MINBPC(enc); + break; + } + *nextTokPtr = ptr + 2*MINBPC(enc); + return XML_TOK_INVALID; + } + } + /* fall through */ + case BT_AMP: + case BT_LT: + case BT_NONXML: + case BT_MALFORM: + case BT_TRAIL: + case BT_CR: + case BT_LF: + *nextTokPtr = ptr; + return XML_TOK_DATA_CHARS; + default: + ptr += MINBPC(enc); + break; + } + } + *nextTokPtr = ptr; + return XML_TOK_DATA_CHARS; +} + +/* ptr points to character following "%" */ + +static +int PREFIX(scanPercent)(const ENCODING *enc, const char *ptr, const char *end, + const char **nextTokPtr) +{ + if (ptr == end) + return XML_TOK_PARTIAL; + switch (BYTE_TYPE(enc, ptr)) { + CHECK_NMSTRT_CASES(enc, ptr, end, nextTokPtr) + case BT_S: case BT_LF: case BT_CR: case BT_PERCNT: + *nextTokPtr = ptr; + return XML_TOK_PERCENT; + default: + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + while (ptr != end) { + switch (BYTE_TYPE(enc, ptr)) { + CHECK_NAME_CASES(enc, ptr, end, nextTokPtr) + case BT_SEMI: + *nextTokPtr = ptr + MINBPC(enc); + return XML_TOK_PARAM_ENTITY_REF; + default: + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + } + return XML_TOK_PARTIAL; +} + +static +int PREFIX(scanPoundName)(const ENCODING *enc, const char *ptr, const char *end, + const char **nextTokPtr) +{ + if (ptr == end) + return XML_TOK_PARTIAL; + switch (BYTE_TYPE(enc, ptr)) { + CHECK_NMSTRT_CASES(enc, ptr, end, nextTokPtr) + default: + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + while (ptr != end) { + switch (BYTE_TYPE(enc, ptr)) { + CHECK_NAME_CASES(enc, ptr, end, nextTokPtr) + case BT_CR: case BT_LF: case BT_S: + case BT_RPAR: case BT_GT: case BT_PERCNT: case BT_VERBAR: + *nextTokPtr = ptr; + return XML_TOK_POUND_NAME; + default: + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + } + return XML_TOK_PARTIAL; +} + +static +int PREFIX(scanLit)(int open, const ENCODING *enc, + const char *ptr, const char *end, + const char **nextTokPtr) +{ + while (ptr != end) { + int t = BYTE_TYPE(enc, ptr); + switch (t) { + INVALID_CASES(ptr, nextTokPtr) + case BT_QUOT: + case BT_APOS: + ptr += MINBPC(enc); + if (t != open) + break; + if (ptr == end) + return XML_TOK_PARTIAL; + *nextTokPtr = ptr; + switch (BYTE_TYPE(enc, ptr)) { + case BT_S: case BT_CR: case BT_LF: + case BT_GT: case BT_PERCNT: case BT_LSQB: + return XML_TOK_LITERAL; + default: + return XML_TOK_INVALID; + } + default: + ptr += MINBPC(enc); + break; + } + } + return XML_TOK_PARTIAL; +} + +static +int PREFIX(prologTok)(const ENCODING *enc, const char *ptr, const char *end, + const char **nextTokPtr) +{ + int tok; + if (ptr == end) + return XML_TOK_NONE; + if (MINBPC(enc) > 1) { + size_t n = end - ptr; + if (n & (MINBPC(enc) - 1)) { + n &= ~(MINBPC(enc) - 1); + if (n == 0) + return XML_TOK_PARTIAL; + end = ptr + n; + } + } + switch (BYTE_TYPE(enc, ptr)) { + case BT_QUOT: + return PREFIX(scanLit)(BT_QUOT, enc, ptr + MINBPC(enc), end, nextTokPtr); + case BT_APOS: + return PREFIX(scanLit)(BT_APOS, enc, ptr + MINBPC(enc), end, nextTokPtr); + case BT_LT: + { + ptr += MINBPC(enc); + if (ptr == end) + return XML_TOK_PARTIAL; + switch (BYTE_TYPE(enc, ptr)) { + case BT_EXCL: + return PREFIX(scanDecl)(enc, ptr + MINBPC(enc), end, nextTokPtr); + case BT_QUEST: + return PREFIX(scanPi)(enc, ptr + MINBPC(enc), end, nextTokPtr); + case BT_NMSTRT: + case BT_HEX: + case BT_NONASCII: + case BT_LEAD2: + case BT_LEAD3: + case BT_LEAD4: + *nextTokPtr = ptr - MINBPC(enc); + return XML_TOK_INSTANCE_START; + } + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + case BT_CR: + if (ptr + MINBPC(enc) == end) + return XML_TOK_TRAILING_CR; + /* fall through */ + case BT_S: case BT_LF: + for (;;) { + ptr += MINBPC(enc); + if (ptr == end) + break; + switch (BYTE_TYPE(enc, ptr)) { + case BT_S: case BT_LF: + break; + case BT_CR: + /* don't split CR/LF pair */ + if (ptr + MINBPC(enc) != end) + break; + /* fall through */ + default: + *nextTokPtr = ptr; + return XML_TOK_PROLOG_S; + } + } + *nextTokPtr = ptr; + return XML_TOK_PROLOG_S; + case BT_PERCNT: + return PREFIX(scanPercent)(enc, ptr + MINBPC(enc), end, nextTokPtr); + case BT_COMMA: + *nextTokPtr = ptr + MINBPC(enc); + return XML_TOK_COMMA; + case BT_LSQB: + *nextTokPtr = ptr + MINBPC(enc); + return XML_TOK_OPEN_BRACKET; + case BT_RSQB: + ptr += MINBPC(enc); + if (ptr == end) + return XML_TOK_PARTIAL; + if (CHAR_MATCHES(enc, ptr, ']')) { + if (ptr + MINBPC(enc) == end) + return XML_TOK_PARTIAL; + if (CHAR_MATCHES(enc, ptr + MINBPC(enc), '>')) { + *nextTokPtr = ptr + 2*MINBPC(enc); + return XML_TOK_COND_SECT_CLOSE; + } + } + *nextTokPtr = ptr; + return XML_TOK_CLOSE_BRACKET; + case BT_LPAR: + *nextTokPtr = ptr + MINBPC(enc); + return XML_TOK_OPEN_PAREN; + case BT_RPAR: + ptr += MINBPC(enc); + if (ptr == end) + return XML_TOK_PARTIAL; + switch (BYTE_TYPE(enc, ptr)) { + case BT_AST: + *nextTokPtr = ptr + MINBPC(enc); + return XML_TOK_CLOSE_PAREN_ASTERISK; + case BT_QUEST: + *nextTokPtr = ptr + MINBPC(enc); + return XML_TOK_CLOSE_PAREN_QUESTION; + case BT_PLUS: + *nextTokPtr = ptr + MINBPC(enc); + return XML_TOK_CLOSE_PAREN_PLUS; + case BT_CR: case BT_LF: case BT_S: + case BT_GT: case BT_COMMA: case BT_VERBAR: + case BT_RPAR: + *nextTokPtr = ptr; + return XML_TOK_CLOSE_PAREN; + } + *nextTokPtr = ptr; + return XML_TOK_INVALID; + case BT_VERBAR: + *nextTokPtr = ptr + MINBPC(enc); + return XML_TOK_OR; + case BT_GT: + *nextTokPtr = ptr + MINBPC(enc); + return XML_TOK_DECL_CLOSE; + case BT_NUM: + return PREFIX(scanPoundName)(enc, ptr + MINBPC(enc), end, nextTokPtr); +#define LEAD_CASE(n) \ + case BT_LEAD ## n: \ + if (end - ptr < n) \ + return XML_TOK_PARTIAL_CHAR; \ + if (IS_NMSTRT_CHAR(enc, ptr, n)) { \ + ptr += n; \ + tok = XML_TOK_NAME; \ + break; \ + } \ + if (IS_NAME_CHAR(enc, ptr, n)) { \ + ptr += n; \ + tok = XML_TOK_NMTOKEN; \ + break; \ + } \ + *nextTokPtr = ptr; \ + return XML_TOK_INVALID; + LEAD_CASE(2) LEAD_CASE(3) LEAD_CASE(4) +#undef LEAD_CASE + case BT_NMSTRT: + case BT_HEX: + tok = XML_TOK_NAME; + ptr += MINBPC(enc); + break; + case BT_DIGIT: + case BT_NAME: + case BT_MINUS: +#ifdef XML_NS + case BT_COLON: +#endif + tok = XML_TOK_NMTOKEN; + ptr += MINBPC(enc); + break; + case BT_NONASCII: + if (IS_NMSTRT_CHAR_MINBPC(enc, ptr)) { + ptr += MINBPC(enc); + tok = XML_TOK_NAME; + break; + } + if (IS_NAME_CHAR_MINBPC(enc, ptr)) { + ptr += MINBPC(enc); + tok = XML_TOK_NMTOKEN; + break; + } + /* fall through */ + default: + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + while (ptr != end) { + switch (BYTE_TYPE(enc, ptr)) { + CHECK_NAME_CASES(enc, ptr, end, nextTokPtr) + case BT_GT: case BT_RPAR: case BT_COMMA: + case BT_VERBAR: case BT_LSQB: case BT_PERCNT: + case BT_S: case BT_CR: case BT_LF: + *nextTokPtr = ptr; + return tok; +#ifdef XML_NS + case BT_COLON: + ptr += MINBPC(enc); + switch (tok) { + case XML_TOK_NAME: + if (ptr == end) + return XML_TOK_PARTIAL; + tok = XML_TOK_PREFIXED_NAME; + switch (BYTE_TYPE(enc, ptr)) { + CHECK_NAME_CASES(enc, ptr, end, nextTokPtr) + default: + tok = XML_TOK_NMTOKEN; + break; + } + break; + case XML_TOK_PREFIXED_NAME: + tok = XML_TOK_NMTOKEN; + break; + } + break; +#endif + case BT_PLUS: + if (tok == XML_TOK_NMTOKEN) { + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + *nextTokPtr = ptr + MINBPC(enc); + return XML_TOK_NAME_PLUS; + case BT_AST: + if (tok == XML_TOK_NMTOKEN) { + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + *nextTokPtr = ptr + MINBPC(enc); + return XML_TOK_NAME_ASTERISK; + case BT_QUEST: + if (tok == XML_TOK_NMTOKEN) { + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + *nextTokPtr = ptr + MINBPC(enc); + return XML_TOK_NAME_QUESTION; + default: + *nextTokPtr = ptr; + return XML_TOK_INVALID; + } + } + return XML_TOK_PARTIAL; +} + +static +int PREFIX(attributeValueTok)(const ENCODING *enc, const char *ptr, const char *end, + const char **nextTokPtr) +{ + const char *start; + if (ptr == end) + return XML_TOK_NONE; + start = ptr; + while (ptr != end) { + switch (BYTE_TYPE(enc, ptr)) { +#define LEAD_CASE(n) \ + case BT_LEAD ## n: ptr += n; break; + LEAD_CASE(2) LEAD_CASE(3) LEAD_CASE(4) +#undef LEAD_CASE + case BT_AMP: + if (ptr == start) + return PREFIX(scanRef)(enc, ptr + MINBPC(enc), end, nextTokPtr); + *nextTokPtr = ptr; + return XML_TOK_DATA_CHARS; + case BT_LT: + /* this is for inside entity references */ + *nextTokPtr = ptr; + return XML_TOK_INVALID; + case BT_LF: + if (ptr == start) { + *nextTokPtr = ptr + MINBPC(enc); + return XML_TOK_DATA_NEWLINE; + } + *nextTokPtr = ptr; + return XML_TOK_DATA_CHARS; + case BT_CR: + if (ptr == start) { + ptr += MINBPC(enc); + if (ptr == end) + return XML_TOK_TRAILING_CR; + if (BYTE_TYPE(enc, ptr) == BT_LF) + ptr += MINBPC(enc); + *nextTokPtr = ptr; + return XML_TOK_DATA_NEWLINE; + } + *nextTokPtr = ptr; + return XML_TOK_DATA_CHARS; + case BT_S: + if (ptr == start) { + *nextTokPtr = ptr + MINBPC(enc); + return XML_TOK_ATTRIBUTE_VALUE_S; + } + *nextTokPtr = ptr; + return XML_TOK_DATA_CHARS; + default: + ptr += MINBPC(enc); + break; + } + } + *nextTokPtr = ptr; + return XML_TOK_DATA_CHARS; +} + +static +int PREFIX(entityValueTok)(const ENCODING *enc, const char *ptr, const char *end, + const char **nextTokPtr) +{ + const char *start; + if (ptr == end) + return XML_TOK_NONE; + start = ptr; + while (ptr != end) { + switch (BYTE_TYPE(enc, ptr)) { +#define LEAD_CASE(n) \ + case BT_LEAD ## n: ptr += n; break; + LEAD_CASE(2) LEAD_CASE(3) LEAD_CASE(4) +#undef LEAD_CASE + case BT_AMP: + if (ptr == start) + return PREFIX(scanRef)(enc, ptr + MINBPC(enc), end, nextTokPtr); + *nextTokPtr = ptr; + return XML_TOK_DATA_CHARS; + case BT_PERCNT: + if (ptr == start) + return PREFIX(scanPercent)(enc, ptr + MINBPC(enc), end, nextTokPtr); + *nextTokPtr = ptr; + return XML_TOK_DATA_CHARS; + case BT_LF: + if (ptr == start) { + *nextTokPtr = ptr + MINBPC(enc); + return XML_TOK_DATA_NEWLINE; + } + *nextTokPtr = ptr; + return XML_TOK_DATA_CHARS; + case BT_CR: + if (ptr == start) { + ptr += MINBPC(enc); + if (ptr == end) + return XML_TOK_TRAILING_CR; + if (BYTE_TYPE(enc, ptr) == BT_LF) + ptr += MINBPC(enc); + *nextTokPtr = ptr; + return XML_TOK_DATA_NEWLINE; + } + *nextTokPtr = ptr; + return XML_TOK_DATA_CHARS; + default: + ptr += MINBPC(enc); + break; + } + } + *nextTokPtr = ptr; + return XML_TOK_DATA_CHARS; +} + +static +int PREFIX(isPublicId)(const ENCODING *enc, const char *ptr, const char *end, + const char **badPtr) +{ + ptr += MINBPC(enc); + end -= MINBPC(enc); + for (; ptr != end; ptr += MINBPC(enc)) { + switch (BYTE_TYPE(enc, ptr)) { + case BT_DIGIT: + case BT_HEX: + case BT_MINUS: + case BT_APOS: + case BT_LPAR: + case BT_RPAR: + case BT_PLUS: + case BT_COMMA: + case BT_SOL: + case BT_EQUALS: + case BT_QUEST: + case BT_CR: + case BT_LF: + case BT_SEMI: + case BT_EXCL: + case BT_AST: + case BT_PERCNT: + case BT_NUM: +#ifdef XML_NS + case BT_COLON: +#endif + break; + case BT_S: + if (CHAR_MATCHES(enc, ptr, '\t')) { + *badPtr = ptr; + return 0; + } + break; + case BT_NAME: + case BT_NMSTRT: + if (!(BYTE_TO_ASCII(enc, ptr) & ~0x7f)) + break; + default: + switch (BYTE_TO_ASCII(enc, ptr)) { + case 0x24: /* $ */ + case 0x40: /* @ */ + break; + default: + *badPtr = ptr; + return 0; + } + break; + } + } + return 1; +} + +/* This must only be called for a well-formed start-tag or empty element tag. +Returns the number of attributes. Pointers to the first attsMax attributes +are stored in atts. */ + +static +int PREFIX(getAtts)(const ENCODING *enc, const char *ptr, + int attsMax, ATTRIBUTE *atts) +{ + enum { other, inName, inValue } state = inName; + int nAtts = 0; + int open = 0; + + for (ptr += MINBPC(enc);; ptr += MINBPC(enc)) { + switch (BYTE_TYPE(enc, ptr)) { +#define START_NAME \ + if (state == other) { \ + if (nAtts < attsMax) { \ + atts[nAtts].name = ptr; \ + atts[nAtts].normalized = 1; \ + } \ + state = inName; \ + } +#define LEAD_CASE(n) \ + case BT_LEAD ## n: START_NAME ptr += (n - MINBPC(enc)); break; + LEAD_CASE(2) LEAD_CASE(3) LEAD_CASE(4) +#undef LEAD_CASE + case BT_NONASCII: + case BT_NMSTRT: + case BT_HEX: + START_NAME + break; +#undef START_NAME + case BT_QUOT: + if (state != inValue) { + if (nAtts < attsMax) + atts[nAtts].valuePtr = ptr + MINBPC(enc); + state = inValue; + open = BT_QUOT; + } + else if (open == BT_QUOT) { + state = other; + if (nAtts < attsMax) + atts[nAtts].valueEnd = ptr; + nAtts++; + } + break; + case BT_APOS: + if (state != inValue) { + if (nAtts < attsMax) + atts[nAtts].valuePtr = ptr + MINBPC(enc); + state = inValue; + open = BT_APOS; + } + else if (open == BT_APOS) { + state = other; + if (nAtts < attsMax) + atts[nAtts].valueEnd = ptr; + nAtts++; + } + break; + case BT_AMP: + if (nAtts < attsMax) + atts[nAtts].normalized = 0; + break; + case BT_S: + if (state == inName) + state = other; + else if (state == inValue + && nAtts < attsMax + && atts[nAtts].normalized + && (ptr == atts[nAtts].valuePtr + || BYTE_TO_ASCII(enc, ptr) != ' ' + || BYTE_TO_ASCII(enc, ptr + MINBPC(enc)) == ' ' + || BYTE_TYPE(enc, ptr + MINBPC(enc)) == open)) + atts[nAtts].normalized = 0; + break; + case BT_CR: case BT_LF: + /* This case ensures that the first attribute name is counted + Apart from that we could just change state on the quote. */ + if (state == inName) + state = other; + else if (state == inValue && nAtts < attsMax) + atts[nAtts].normalized = 0; + break; + case BT_GT: + case BT_SOL: + if (state != inValue) + return nAtts; + break; + default: + break; + } + } + /* not reached */ +} + +static +int PREFIX(charRefNumber)(const ENCODING *enc, const char *ptr) +{ + int result = 0; + /* skip &# */ + ptr += 2*MINBPC(enc); + if (CHAR_MATCHES(enc, ptr, 'x')) { + for (ptr += MINBPC(enc); !CHAR_MATCHES(enc, ptr, ';'); ptr += MINBPC(enc)) { + int c = BYTE_TO_ASCII(enc, ptr); + switch (c) { + case '0': case '1': case '2': case '3': case '4': + case '5': case '6': case '7': case '8': case '9': + result <<= 4; + result |= (c - '0'); + break; + case 'A': case 'B': case 'C': case 'D': case 'E': case 'F': + result <<= 4; + result += 10 + (c - 'A'); + break; + case 'a': case 'b': case 'c': case 'd': case 'e': case 'f': + result <<= 4; + result += 10 + (c - 'a'); + break; + } + if (result >= 0x110000) + return -1; + } + } + else { + for (; !CHAR_MATCHES(enc, ptr, ';'); ptr += MINBPC(enc)) { + int c = BYTE_TO_ASCII(enc, ptr); + result *= 10; + result += (c - '0'); + if (result >= 0x110000) + return -1; + } + } + return checkCharRefNumber(result); +} + +static +int PREFIX(predefinedEntityName)(const ENCODING *enc, const char *ptr, const char *end) +{ + switch ((end - ptr)/MINBPC(enc)) { + case 2: + if (CHAR_MATCHES(enc, ptr + MINBPC(enc), 't')) { + switch (BYTE_TO_ASCII(enc, ptr)) { + case 'l': + return '<'; + case 'g': + return '>'; + } + } + break; + case 3: + if (CHAR_MATCHES(enc, ptr, 'a')) { + ptr += MINBPC(enc); + if (CHAR_MATCHES(enc, ptr, 'm')) { + ptr += MINBPC(enc); + if (CHAR_MATCHES(enc, ptr, 'p')) + return '&'; + } + } + break; + case 4: + switch (BYTE_TO_ASCII(enc, ptr)) { + case 'q': + ptr += MINBPC(enc); + if (CHAR_MATCHES(enc, ptr, 'u')) { + ptr += MINBPC(enc); + if (CHAR_MATCHES(enc, ptr, 'o')) { + ptr += MINBPC(enc); + if (CHAR_MATCHES(enc, ptr, 't')) + return '"'; + } + } + break; + case 'a': + ptr += MINBPC(enc); + if (CHAR_MATCHES(enc, ptr, 'p')) { + ptr += MINBPC(enc); + if (CHAR_MATCHES(enc, ptr, 'o')) { + ptr += MINBPC(enc); + if (CHAR_MATCHES(enc, ptr, 's')) + return '\''; + } + } + break; + } + } + return 0; +} + +static +int PREFIX(sameName)(const ENCODING *enc, const char *ptr1, const char *ptr2) +{ + for (;;) { + switch (BYTE_TYPE(enc, ptr1)) { +#define LEAD_CASE(n) \ + case BT_LEAD ## n: \ + if (*ptr1++ != *ptr2++) \ + return 0; + LEAD_CASE(4) LEAD_CASE(3) LEAD_CASE(2) +#undef LEAD_CASE + /* fall through */ + if (*ptr1++ != *ptr2++) + return 0; + break; + case BT_NONASCII: + case BT_NMSTRT: +#ifdef XML_NS + case BT_COLON: +#endif + case BT_HEX: + case BT_DIGIT: + case BT_NAME: + case BT_MINUS: + if (*ptr2++ != *ptr1++) + return 0; + if (MINBPC(enc) > 1) { + if (*ptr2++ != *ptr1++) + return 0; + if (MINBPC(enc) > 2) { + if (*ptr2++ != *ptr1++) + return 0; + if (MINBPC(enc) > 3) { + if (*ptr2++ != *ptr1++) + return 0; + } + } + } + break; + default: + if (MINBPC(enc) == 1 && *ptr1 == *ptr2) + return 1; + switch (BYTE_TYPE(enc, ptr2)) { + case BT_LEAD2: + case BT_LEAD3: + case BT_LEAD4: + case BT_NONASCII: + case BT_NMSTRT: +#ifdef XML_NS + case BT_COLON: +#endif + case BT_HEX: + case BT_DIGIT: + case BT_NAME: + case BT_MINUS: + return 0; + default: + return 1; + } + } + } + /* not reached */ +} + +static +int PREFIX(nameMatchesAscii)(const ENCODING *enc, const char *ptr1, const char *ptr2) +{ + for (; *ptr2; ptr1 += MINBPC(enc), ptr2++) { + if (!CHAR_MATCHES(enc, ptr1, *ptr2)) + return 0; + } + switch (BYTE_TYPE(enc, ptr1)) { + case BT_LEAD2: + case BT_LEAD3: + case BT_LEAD4: + case BT_NONASCII: + case BT_NMSTRT: +#ifdef XML_NS + case BT_COLON: +#endif + case BT_HEX: + case BT_DIGIT: + case BT_NAME: + case BT_MINUS: + return 0; + default: + return 1; + } +} + +static +int PREFIX(nameLength)(const ENCODING *enc, const char *ptr) +{ + const char *start = ptr; + for (;;) { + switch (BYTE_TYPE(enc, ptr)) { +#define LEAD_CASE(n) \ + case BT_LEAD ## n: ptr += n; break; + LEAD_CASE(2) LEAD_CASE(3) LEAD_CASE(4) +#undef LEAD_CASE + case BT_NONASCII: + case BT_NMSTRT: +#ifdef XML_NS + case BT_COLON: +#endif + case BT_HEX: + case BT_DIGIT: + case BT_NAME: + case BT_MINUS: + ptr += MINBPC(enc); + break; + default: + return ptr - start; + } + } +} + +static +const char *PREFIX(skipS)(const ENCODING *enc, const char *ptr) +{ + for (;;) { + switch (BYTE_TYPE(enc, ptr)) { + case BT_LF: + case BT_CR: + case BT_S: + ptr += MINBPC(enc); + break; + default: + return ptr; + } + } +} + +static +void PREFIX(updatePosition)(const ENCODING *enc, + const char *ptr, + const char *end, + POSITION *pos) +{ + while (ptr != end) { + switch (BYTE_TYPE(enc, ptr)) { +#define LEAD_CASE(n) \ + case BT_LEAD ## n: \ + ptr += n; \ + break; + LEAD_CASE(2) LEAD_CASE(3) LEAD_CASE(4) +#undef LEAD_CASE + case BT_LF: + pos->columnNumber = (unsigned)-1; + pos->lineNumber++; + ptr += MINBPC(enc); + break; + case BT_CR: + pos->lineNumber++; + ptr += MINBPC(enc); + if (ptr != end && BYTE_TYPE(enc, ptr) == BT_LF) + ptr += MINBPC(enc); + pos->columnNumber = (unsigned)-1; + break; + default: + ptr += MINBPC(enc); + break; + } + pos->columnNumber++; + } +} + +#undef DO_LEAD_CASE +#undef MULTIBYTE_CASES +#undef INVALID_CASES +#undef CHECK_NAME_CASE +#undef CHECK_NAME_CASES +#undef CHECK_NMSTRT_CASE +#undef CHECK_NMSTRT_CASES diff --git a/srclib/expat-lite/xmltok_impl.h b/srclib/expat-lite/xmltok_impl.h new file mode 100644 index 0000000000..e72b225c83 --- /dev/null +++ b/srclib/expat-lite/xmltok_impl.h @@ -0,0 +1,71 @@ +/* +The contents of this file are subject to the Mozilla Public License +Version 1.1 (the "License"); you may not use this file except in +compliance with the License. You may obtain a copy of the License at +http://www.mozilla.org/MPL/ + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the +License for the specific language governing rights and limitations +under the License. + +The Original Code is expat. + +The Initial Developer of the Original Code is James Clark. +Portions created by James Clark are Copyright (C) 1998, 1999 +James Clark. All Rights Reserved. + +Contributor(s): + +Alternatively, the contents of this file may be used under the terms +of the GNU General Public License (the "GPL"), in which case the +provisions of the GPL are applicable instead of those above. If you +wish to allow use of your version of this file only under the terms of +the GPL and not to allow others to use your version of this file under +the MPL, indicate your decision by deleting the provisions above and +replace them with the notice and other provisions required by the +GPL. If you do not delete the provisions above, a recipient may use +your version of this file under either the MPL or the GPL. +*/ + +enum { + BT_NONXML, + BT_MALFORM, + BT_LT, + BT_AMP, + BT_RSQB, + BT_LEAD2, + BT_LEAD3, + BT_LEAD4, + BT_TRAIL, + BT_CR, + BT_LF, + BT_GT, + BT_QUOT, + BT_APOS, + BT_EQUALS, + BT_QUEST, + BT_EXCL, + BT_SOL, + BT_SEMI, + BT_NUM, + BT_LSQB, + BT_S, + BT_NMSTRT, + BT_COLON, + BT_HEX, + BT_DIGIT, + BT_NAME, + BT_MINUS, + BT_OTHER, /* known not to be a name or name start character */ + BT_NONASCII, /* might be a name or name start character */ + BT_PERCNT, + BT_LPAR, + BT_RPAR, + BT_AST, + BT_PLUS, + BT_COMMA, + BT_VERBAR +}; + +#include <stddef.h> diff --git a/srclib/expat-lite/xmltok_ns.c b/srclib/expat-lite/xmltok_ns.c new file mode 100644 index 0000000000..a32c577458 --- /dev/null +++ b/srclib/expat-lite/xmltok_ns.c @@ -0,0 +1,96 @@ +const ENCODING *NS(XmlGetUtf8InternalEncoding)(void) +{ + return &ns(internal_utf8_encoding).enc; +} + +const ENCODING *NS(XmlGetUtf16InternalEncoding)(void) +{ +#if XML_BYTE_ORDER == 12 + return &ns(internal_little2_encoding).enc; +#elif XML_BYTE_ORDER == 21 + return &ns(internal_big2_encoding).enc; +#else + const short n = 1; + return *(const char *)&n ? &ns(internal_little2_encoding).enc : &ns(internal_big2_encoding).enc; +#endif +} + +static +const ENCODING *NS(encodings)[] = { + &ns(latin1_encoding).enc, + &ns(ascii_encoding).enc, + &ns(utf8_encoding).enc, + &ns(big2_encoding).enc, + &ns(big2_encoding).enc, + &ns(little2_encoding).enc, + &ns(utf8_encoding).enc /* NO_ENC */ +}; + +static +int NS(initScanProlog)(const ENCODING *enc, const char *ptr, const char *end, + const char **nextTokPtr) +{ + return initScan(NS(encodings), (const INIT_ENCODING *)enc, XML_PROLOG_STATE, ptr, end, nextTokPtr); +} + +static +int NS(initScanContent)(const ENCODING *enc, const char *ptr, const char *end, + const char **nextTokPtr) +{ + return initScan(NS(encodings), (const INIT_ENCODING *)enc, XML_CONTENT_STATE, ptr, end, nextTokPtr); +} + +int NS(XmlInitEncoding)(INIT_ENCODING *p, const ENCODING **encPtr, const char *name) +{ + int i = getEncodingIndex(name); + if (i == UNKNOWN_ENC) + return 0; + INIT_ENC_INDEX(p) = (char)i; + p->initEnc.scanners[XML_PROLOG_STATE] = NS(initScanProlog); + p->initEnc.scanners[XML_CONTENT_STATE] = NS(initScanContent); + p->initEnc.updatePosition = initUpdatePosition; + p->encPtr = encPtr; + *encPtr = &(p->initEnc); + return 1; +} + +static +const ENCODING *NS(findEncoding)(const ENCODING *enc, const char *ptr, const char *end) +{ +#define ENCODING_MAX 128 + char buf[ENCODING_MAX]; + char *p = buf; + int i; + XmlUtf8Convert(enc, &ptr, end, &p, p + ENCODING_MAX - 1); + if (ptr != end) + return 0; + *p = 0; + if (streqci(buf, "UTF-16") && enc->minBytesPerChar == 2) + return enc; + i = getEncodingIndex(buf); + if (i == UNKNOWN_ENC) + return 0; + return NS(encodings)[i]; +} + +int NS(XmlParseXmlDecl)(int isGeneralTextEntity, + const ENCODING *enc, + const char *ptr, + const char *end, + const char **badPtr, + const char **versionPtr, + const char **encodingName, + const ENCODING **encoding, + int *standalone) +{ + return doParseXmlDecl(NS(findEncoding), + isGeneralTextEntity, + enc, + ptr, + end, + badPtr, + versionPtr, + encodingName, + encoding, + standalone); +} |
