You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by co...@apache.org on 2001/11/03 12:47:14 UTC
cvs commit: httpd-docs-1.3/apidoc ap-dict.dtd api.xml
coar 01/11/03 03:47:14
Modified: apidoc ap-dict.dtd api.xml
Log:
Start importing the HTML files, and fix DTD to allow some of the markup
Revision Changes Path
1.3 +67 -3 httpd-docs-1.3/apidoc/ap-dict.dtd
Index: ap-dict.dtd
===================================================================
RCS file: /home/cvs/httpd-docs-1.3/apidoc/ap-dict.dtd,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -u -r1.2 -r1.3
--- ap-dict.dtd 2001/10/30 10:20:10 1.2
+++ ap-dict.dtd 2001/11/03 11:47:13 1.3
@@ -22,6 +22,15 @@
<!ENTITY % content.comment
"(#PCDATA)*">
+<!ENTITY % elements.dd
+ "b
+ |i
+ |literal
+ |ref">
+<!ENTITY % content.dd
+ "(#PCDATA
+ |%elements.dd;)*">
+
<!ENTITY % elements.declaration
"b
|comment
@@ -58,10 +67,27 @@
<!ENTITY % elements.description
"comment
- |para">
+ |dl
+ |note
+ |para
+ |ul">
<!ENTITY % content.description
"(%elements.description;)*">
+<!ENTITY % elements.dl
+ "dd
+ |dt">
+<!ENTITY % content.dl
+ "(%elements.dl;)*">
+
+<!ENTITY % elements.dt
+ "b
+ |i
+ |literal
+ |ref">
+<!ENTITY % content.dt
+ "(%elements.dt;)*">
+
<!ENTITY % elements.example
"comment
|text">
@@ -104,8 +130,18 @@
<!ENTITY % content.lexicon
"(%elements.lexicon;)*">
+<!ENTITY % elements.li
+ "b
+ |i
+ |literal
+ |ref">
+<!ENTITY % content.li
+ "(#PCDATA
+ |%elements.li;)*">
<!ENTITY % elements.literal
- "comment
+ "b
+ |comment
+ |i
|ref
|var">
<!ENTITY % content.literal
@@ -121,8 +157,21 @@
"(#PCDATA
|%elements.name;)*">
+<!ENTITY % elements.note
+ "b
+ |comment
+ |i
+ |literal
+ |ref
+ |var">
+<!ENTITY % content.note
+ "(#PCDATA
+ |%elements.note;)*">
+
<!ENTITY % elements.para
- "comment
+ "b
+ |comment
+ |i
|literal
|ref
|var">
@@ -185,6 +234,11 @@
"(#PCDATA
|%elements.type;)*">
+<!ENTITY % elements.ul
+ "li">
+<!ENTITY % content.ul
+ "(%elements.ul;)*">
+
<!ENTITY % elements.used-by
"comment
|literal
@@ -216,6 +270,7 @@
-->
<!ELEMENT action %content.action;>
+<!ELEMENT b %content.b;>
<!ELEMENT comment %content.comment;>
<!ELEMENT declaration %content.declaration;>
<!ELEMENT defined-by %content.defined-by;>
@@ -225,9 +280,15 @@
<!ELEMENT description %content.description;>
<!ATTLIST description
href CDATA #IMPLIED>
+<!ELEMENT dd %content.dd;>
+<!ELEMENT dl %content.dl;>
+<!ATTLIST dl
+ compact (compact) #IMPLIED>
+<!ELEMENT dt %content.dt;>
<!ELEMENT example %content.example;>
<!ELEMENT flag %content.flag;>
<!ELEMENT flags %content.flags;>
+<!ELEMENT i %content.i;>
<!ELEMENT item %content.item;>
<!ATTLIST item
id ID #IMPLIED
@@ -235,8 +296,10 @@
<!ELEMENT lexicon %content.lexicon;>
<!ATTLIST lexicon
name CDATA #IMPLIED> <!-- Identifying name for the dictionary -->
+<!ELEMENT li %content.li;>
<!ELEMENT literal %content.literal;>
<!ELEMENT name %content.name;>
+<!ELEMENT note %content.note;>
<!ELEMENT para %content.para;>
<!ELEMENT ref %content.ref;>
<!ATTLIST ref
@@ -248,6 +311,7 @@
<!ELEMENT text %content.text;>
<!ELEMENT title %content.title;>
<!ELEMENT type %content.type;>
+<!ELEMENT ul %content.ul;>
<!ELEMENT used-by %content.used-by;>
<!ELEMENT var %content.var;>
<!ELEMENT version %content.version;>
1.4 +894 -123 httpd-docs-1.3/apidoc/api.xml
Index: api.xml
===================================================================
RCS file: /home/cvs/httpd-docs-1.3/apidoc/api.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -u -r1.3 -r1.4
--- api.xml 2001/10/30 10:20:10 1.3
+++ api.xml 2001/11/03 11:47:13 1.4
@@ -217,7 +217,16 @@
<name>AP_MODULE_MAGIC_AT_LEAST</name>
<definition>
<declaration>#include "ap_mmn.h"</declaration>
- <description href="dict-AP_MODULE_MAGIC_AT_LEAST.html" />
+ <description>
+ <para>
+ The <literal>AP_MODULE_MAGIC_AT_LEAST</literal> macro is used to test
+ the feature level of the base Apache server against which a module
+ is being built. This allows the module to use <literal>#if</literal>
+ preprocessor blocks to take advantage of recent API enhancements
+ without losing the ability to compile successfully against older
+ versions of the server.
+ </para>
+ </description>
<example>
<text> request_rec *r;
char *x;
@@ -239,7 +248,26 @@
<name>BIG_SECURITY_HOLE</name>
<definition>
<declaration>Compile-time definition</declaration>
- <description href="dict-BIG_SECURITY_HOLE.html" />
+ <description>
+ <para>
+ Ordinarily the Apache server is started as the <literal>root</literal>
+ superuser, and then switches to an unprivileged user identity as soon
+ as possible. If you try to have Apache continue its normal operations
+ as <literal>root</literal> (with a "<literal>User root</literal>" directive),
+ it will display an error message and exit.
+ If you <i>really</i> want the server to start as <literal>root</literal> and
+ not switch identities, you need to rebuild the server with this compile-time
+ definition.
+ </para>
+ <dl compact="compact">
+ <dt><b>Note:</b></dt>
+ <dd>Having the Web server perform its normal operations as the
+ superuser <literal>root</literal> is very dangerous, and not recommended.</dd>
+ </dl>
+ <para>
+ This is not an issue on the Windows platform.
+ </para>
+ </description>
<example>
<text>env CFLAGS="-Wall -DBIG_SECURITY_HOLE" ./configure</text>
</example>
@@ -397,7 +425,15 @@
<name>B_SFIO</name>
<definition>
<declaration>env CFLAGS="-Wall -DB_SFIO" ./configure</declaration>
- <description href="dict-B_SFIO.html" />
+ <description>
+ <para>
+ If this name is defined, Apache's buffering routines will use
+ the <literal>sfwrite</literal> and <literal>sfread</literal>. However,
+ this name is never defined by default or by any of Apache's
+ build configuration script; the builder must define it
+ explicitly as shown in the example.
+ </para>
+ </description>
<seealso>
<ref>SA-BUFF</ref>
</seealso>
@@ -437,7 +473,15 @@
<name>CR</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-CR.html" />
+ <description>
+ <para>
+ The <literal>CR</literal> macro defines a name for the carriage-return
+ character's value. This value is different depending upon whether
+ the <literal>CHARSET_ECDIC</literal> macro is defined. <literal>CR</literal>
+ is primarily intended to be used in string searching and
+ construction.
+ </para>
+ </description>
<example>
<text>eol = strchr(string, CR);</text>
</example>
@@ -450,7 +494,21 @@
<name>CRLF</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-CRLF.html" />
+ <description>
+ <para>
+ The <literal>CRLF</literal> macro expands to a string consisting of
+ the carriage-return (<literal>CR</literal>) character followed by a
+ line-feed (<literal>LF</literal>) character. Unlike the <literal>CR</literal>
+ and <literal>LF</literal> macros, <literal>CRLF</literal> is a <i>string</i>,
+ not a byte.
+ </para>
+ <para>
+ The binary value of <literal>CRLF</literal> is different depending upon whether
+ the <literal>CHARSET_ECDIC</literal> macro is defined. <literal>CRLF</literal>
+ is primarily intended to be used in string searching and
+ construction.
+ </para>
+ </description>
<example>
<text>entity = strstr(request, CRLF CRLF) + (2 * strlen(CRLF));</text>
</example>
@@ -463,7 +521,21 @@
<name>DECLINED</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-DECLINED.html" />
+ <description>
+ <para>
+ This value is returned by modules during request phase processing.
+ It signifies that the module is declining to take responsibility for
+ the current phase, and that the core server should continue invoking
+ other modules.
+ </para>
+ <para>
+ It's possible for a module to actually take action on the request
+ when invoked, and then return <literal>DECLINED</literal> in order to let
+ subsequent modules have a chance at it during the current phase.
+ Though possible, this practice is strongly discouraged, and may
+ not be supported in future versions of the server.
+ </para>
+ </description>
<example>
<text>request_rec *r;
if (is_HTTP_ERROR(r->status)) {
@@ -494,7 +566,7 @@
<item type="Constant">
<name>DEFAULT_ADMIN</name>
<definition>
- <declaration>Compile-time definition; default defined by <code>#include "httpd.h"</code></declaration>
+ <declaration>Compile-time definition; default defined by <code>#include "httpd.h"</declaration>
<description />
<example>
<text>env CFLAGS="-Wall -DDEFAULT_ADMIN=\"/usr/httpd/htdocs\"" ./configure</text>
@@ -507,7 +579,7 @@
<item type="Constant">
<name>DEFAULT_CONTENT_TYPE</name>
<definition>
- <declaration>Compile-time definition; default defined by <code>#include "httpd.h"</code></declaration>
+ <declaration>Compile-time definition; default defined by <code>#include "httpd.h"</declaration>
<description />
<example>
<text>env CFLAGS="-Wall -DDEFAULT_CONTENT_TYPE=\"application/octet-stream\"" ./configurez </text>
@@ -534,8 +606,21 @@
<item type="Constant">
<name>DEFAULT_INDEX</name>
<definition>
- <declaration>Compile-time definition; default defined by <code>#include "httpd.h"</code></declaration>
- <description href="dict-DEFAULT_INDEX.html" />
+ <declaration>Compile-time definition; default defined by
+ '#include "httpd.h"'</declaration>
+ <description>
+ <para>
+ The value of the <literal>DEFAULT_INDEX</literal> definition is used by the
+ <literal>mod_dir</literal> module when no <literal>DirectoryIndex</literal>
+ directive is in effect. For more information, refer to the
+ <literal>mod_dir</literal> documentation.
+ </para>
+ <para>
+ The default value is "<literal>index.html</literal>". Note that, unlike the
+ <literal>DirectoryIndex</literal> directive, this definition can only refer
+ to a single document name, not a list of them.
+ </para>
+ </description>
<example>
<text>env CFLAGS="-Wall -DDEFAULT_INDEX=\"default.html\"" ./configure</text>
</example>
@@ -547,7 +632,7 @@
<item type="Constant">
<name>DEFAULT_KEEPALIVE</name>
<definition>
- <declaration>Compile-time definition; default set by <code>#include "httpd.h"</code></declaration>
+ <declaration>Compile-time definition; default set by #include "httpd.h"</declaration>
<description />
<example>
<text>env CFLAGS="-Wall -DDEFAULT_KEEPALIVE=50" ./configure</text>
@@ -560,7 +645,7 @@
<item type="Constant">
<name>DEFAULT_KEEPALIVE_TIMEOUT</name>
<definition>
- <declaration>Compile-time definition; default set by <code>#include "httpd.h"</code></declaration>
+ <declaration>Compile-time definition; default set by #include "httpd.h"</declaration>
<description />
<example>
<text>env CFLAGS="-Wall -DDEFAULT_KEEPALIVE_TIMEOUT=20" ./configure</text>
@@ -573,7 +658,7 @@
<item type="Constant">
<name>DEFAULT_PATH</name>
<definition>
- <declaration>Compile-time definition default set by <code>#include "httpd.h"</code></declaration>
+ <declaration>Compile-time definition default set by #include "httpd.h"</declaration>
<description />
<example>
<text>env CFLAGS="-Wall -DDEFAULT_PATH=\"/usr/local/bin:/bin:/usr/bin\"" ./configure</text>
@@ -586,7 +671,7 @@
<item type="Constant">
<name>DEFAULT_TIMEOUT</name>
<definition>
- <declaration>Compile-time definition; default set by <code>#include "httpd.h"</code></declaration>
+ <declaration>Compile-time definition; default set by #include "httpd.h"</declaration>
<description />
<example>
<text>env CFLAGS="-Wall -DDEFAULT_TIMEOUT=600" ./configure</text>
@@ -599,8 +684,29 @@
<item type="Constant">
<name>DOCUMENT_LOCATION</name>
<definition>
- <declaration>Compile-time definition; default set by <code>#include "httpd.h"</code></declaration>
- <description href="dict-DOCUMENT_LOCATION.html" />
+ <declaration>Compile-time definition; default set by #include "httpd.h"</declaration>
+ <description>
+ <para>
+ This constant is the hard-coded default for the <literal>DocumentRoot</literal>
+ directive. Like the <literal>HTTPD_ROOT</literal> definition, its value differs
+ from operating system to operating system:
+ </para>
+ <dl>
+ <dt><b>OS/2:</b></dt>
+ <dd><literal>{HTTPD_ROOT}/docs</literal></dd>
+ <dt><b>Everything else:</b></dt>
+ <dd><literal>{HTTPD_ROOT}/htdocs</literal></dd>
+ </dl>
+ <para>
+ The default value is based on the definition of the <literal>HTTPD_ROOT</literal>
+ compile-time definition (<i>q.v.</i>).
+ </para>
+ <para>
+ You should use the <literal>ap_document_root()</literal> (<i>q.v.</i>) routine
+ instead to obtain the value of the DocumentRoot for the server handling a
+ request.
+</para>
+</description>
<example>
<text>env CFLAGS="-Wall -DDOCUMENT_LOCATION=\"/usr/httpd/htdocs\"" ./configure</text>
</example>
@@ -614,7 +720,14 @@
<name>DONE</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-DONE.html" />
+ <description>
+ <para>
+ Module phase handlers return this status when they have completely
+ satisfied the request. It short-circuits the remainder of the phase
+ and content processing, and only the logging phase will still be
+ invoked.
+ </para>
+ </description>
<example>
<text>request_rec *r;
if (!is_HTTP_ERROR(r->status)) {
@@ -629,8 +742,13 @@
<item type="Constant">
<name>DYNAMIC_MODULE_LIMIT</name>
<definition>
- <declaration>Compile-time definition; default set by <code>#include "httpd.h"</code></declaration>
- <description href="dict-DYNAMIC_MODULE_LIMIT.html" />
+ <declaration>Compile-time definition; default set by #include "httpd.h"</declaration>
+ <description>
+ <para>
+ This constant defines the maximum number of modules that can be dynamically
+ loaded. The default value is 64, which is usually sufficient.
+ </para>
+ </description>
<example>
<text>env CFLAGS="-Wall -DDYNAMIC_MODULE_LIMIT=64" ./configure</text>
</example>
@@ -643,7 +761,7 @@
<name>FLAG</name>
<definition>
<declaration>#include "httpd.h"
- <i>see</i> <ref>cmd_how<ref>.</declaration>
+ <i>see</i> <ref>cmd_how</ref>.</declaration>
<description>
<para>
This value indicates that the directive in whose definition it appears
@@ -732,14 +850,39 @@
<name>HANDLE</name>
<definition>
<declaration>Opaque data structure defined by Windows.</declaration>
- <description href="dict-HANDLE.html" />
+ <description>
+ <para>
+ Because the concept of file pointers, descriptors, and handles
+ differs from platform to platform, some API routines and
+ structures on Windows use the Windows <literal>HANDLE</literal>
+ type instead of, or perhaps in addition to, the more
+ widespread Unix types.
+ </para>
+ <para>
+ Where a <literal>HANDLE</literal> type appears, the Windows
+ semantics for its use apply.
+ </para>
+ </description>
</definition>
</item>
<item type="Constant">
<name>HARD_SERVER_LIMIT</name>
<definition>
- <declaration>Compile-time definition; default set by <code>#include "httpd.h"</code></declaration>
- <description href="dict-HARD_SERVER_LIMIT.html" />
+ <declaration>Compile-time definition; default set by #include "httpd.h"</declaration>
+ <description>
+ <para>
+ This compile-time constant defines the maximum possible number of server
+ processes. It places a ceiling on the number of concurrent requests
+ the server can handle. It is used to size several static data structures
+ and therefore requires a recompilation in order to change the value.
+ </para>
+ <para>
+ The default value for Windows is 1024, because on that platform
+ it refers to threads rather than processes. For all other
+ platforms the default value (which <i>does</i> refer to actual
+ child processes) is 256.
+ </para>
+ </description>
<example>
<text>env CFLAGS="-Wall -DHARD_SERVER_LIMIT=1024" ./configure
@@ -755,8 +898,30 @@
<item type="Constant">
<name>HTTPD_ROOT</name>
<definition>
- <declaration>Compile-time definition; default set by <code>#include "httpd.h"</code></declaration>
- <description href="dict-HTTPD_ROOT.html" />
+ <declaration>Compile-time definition; default set by #include "httpd.h"</declaration>
+ <description>
+ <para>
+ This constant is the hard-coded default for the <literal>ServerRoot</literal>
+ directive. Its value differs from operating system to operating
+ system:
+ </para>
+ <dl>
+ <dt><b>OS/2:</b></dt>
+ <dd><literal>/os2httpd</literal></dd>
+ <dt><b>Windows:</b></dt>
+ <dd><literal>/apache</literal></dd>
+ <dt><b>BeOS:</b></dt>
+ <dd><literal>/boot/home/apache</literal></dd>
+ <dt><b>NetWare:</b></dt>
+ <dd><literal>sys:/apache</literal></dd>
+ <dt><b>Everything else:</b></dt>
+ <dd><literal>/usr/local/apache</literal></dd>
+ </dl>
+ <para>
+ This default value is typically overridden at compile-time by
+ the build script.
+ </para>
+ </description>
<example>
<text>env CFLAGS="-Wall -DHTTPD_ROOT=\"/usr/httpd\"" ./configure</text>
</example>
@@ -769,7 +934,12 @@
<name>HTTP_ACCEPTED</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_ACCEPTED.html" />
+ <description>
+ <para>
+ Constant denoting HTTP Accepted status. Indicates the request has been
+ accepted for processing, but the processing has not been completed.
+ </para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_ACCEPTED) {
@@ -785,7 +955,13 @@
<name>HTTP_BAD_GATEWAY</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_BAD_GATEWAY.html" />
+ <description>
+ <para>
+ Constant denoting HTTP Bad Gateway status. The server, while acting as a
+ gateway or proxy, received an invalid response from the upstream server
+ it accessed in attempting to fulfill the request.
+ </para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_BAD_GATEWAY) {
@@ -801,7 +977,12 @@
<name>HTTP_BAD_REQUEST</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_BAD_REQUEST.html" />
+ <description>
+ <para>
+ Constant denoting HTTP Bad Request status. The request could not be
+ understood by the server due to malformed syntax.
+ </para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_BAD_REQUEST) {
@@ -817,7 +998,12 @@
<name>HTTP_CONFLICT</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_CONFLICT.html" />
+ <description>
+ <para>
+ Constant denoting HTTP Conflict status. The request could not be
+ completed due to a conflict with the current state of the resource.
+ </para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_CONFLICT) {
@@ -833,7 +1019,12 @@
<name>HTTP_CONTINUE</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_CONTINUE.html" />
+ <description>
+ <para>
+ Constant denoting HTTP Continue status. The client may continue with
+ its request.
+ </para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_CONTINUE) {
@@ -849,7 +1040,12 @@
<name>HTTP_CREATED</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_CREATED.html" />
+ <description>
+ <para>
+ Constant denoting HTTP Created status. The request has been fulfilled
+ and resulted in a new resource being created.
+ </para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_CREATED) {
@@ -897,7 +1093,12 @@
<name>HTTP_FORBIDDEN</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_FORBIDDEN.html" />
+ <description>
+ <para>
+ Constant denoting HTTP Forbidden status. The server understood the
+ request, but is refusing to fulfill it.
+ </para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_FORBIDDEN) {
@@ -913,7 +1114,13 @@
<name>HTTP_GATEWAY_TIME_OUT</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_GATEWAY_TIME_OUT.html" />
+ <description>
+ <para>
+ Constant denoting HTTP Gateway Time Out status. The server, while acting
+ as a gateway or proxy, did not receive a timely response from the upstream
+ server it accessed in attempting to complete the request.
+ </para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_GATEWAY_TIME_OUT) {
@@ -929,7 +1136,12 @@
<name>HTTP_GONE</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_GONE.html" />
+ <description>
+ <para>
+ Constant denoting HTTP Gone status. The requested resource is no longer
+ available at the server and no forwarding address is known.
+ </para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_GONE) {
@@ -961,7 +1173,12 @@
<name>HTTP_INTERNAL_SERVER_ERROR</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_INTERNAL_SERVER_ERROR.html" />
+ <description>
+ <para>
+ Constant denoting HTTP Internal Server Error status. The server encountered
+ an unexpected condition which prevented it from fulfilling the request.
+ </para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_INTERNAL_SERVER_ERROR) {
@@ -977,7 +1194,12 @@
<name>HTTP_LENGTH_REQUIRED</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_LENGTH_REQUIRED.html" />
+ <description>
+ <para>
+ Constant denoting HTTP Length Required status. The server refuses to
+ accept the request without a defined Content-Length.
+ </para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_LENGTH_REQUIRED) {
@@ -1009,7 +1231,13 @@
<name>HTTP_METHOD_NOT_ALLOWED</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_METHOD_NOT_ALLOWED.html" />
+ <description>
+ <para>
+ Constant denoting HTTP Method Not Allowed status. The method specified
+ in the Request-Line is not allowed for the resource identified by the
+ Request-URI.
+ </para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_METHOD_NOT_ALLOWED) {
@@ -1025,7 +1253,13 @@
<name>HTTP_MOVED_PERMANENTLY</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_MOVED_PERMANENTLY.html" />
+ <description>
+ <para>
+ Constant denoting HTTP Moved Permanently status. The requested resource
+ has been assigned a new permanent URI and any future references to this
+ resource SHOULD be done using one of the returned URIs.
+ </para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_MOVED_PERMANENTLY) {
@@ -1041,7 +1275,12 @@
<name>HTTP_MOVED_TEMPORARILY</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_MOVED_TEMPORARILY.html" />
+ <description>
+ <para>
+ Constant denoting HTTP Moved Temporarily status. The requested
+ resource resides temporarily under a different URI.
+ </para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_MOVED_TEMPORARILY) {
@@ -1057,7 +1296,15 @@
<name>HTTP_MULTIPLE_CHOICES</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_MULTIPLE_CHOICES.html" />
+ <description>
+ <para>
+ Constant denoting HTTP Multiple Choice status. The requested resource
+ corresponds to any one of a set of representations, each with its own
+ specific location, and agent-driven negotiation information is being
+ provided so that the user (or user agent) can select a preferred
+ representation and redirect its request to that location.
+ </para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_MULTIPLE_CHOICES) {
@@ -1073,7 +1320,13 @@
<name>HTTP_NON_AUTHORITATIVE</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_NON_AUTHORITATIVE.html" />
+ <description>
+ <para>
+ Constant denoting HTTP Non Authoritative response status. The returned
+ metainformation in the entity-header is not the definitive set as available
+ from the origin server, but is gathered from a local or a third-party copy.
+ </para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_NON_AUTHORITATIVE) {
@@ -1089,7 +1342,14 @@
<name>HTTP_NOT_ACCEPTABLE</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_NOT_ACCEPTABLE.html" />
+ <description>
+ <para>
+ Constant denoting HTTP Not Acceptable status. The resource identified by
+ the request is only capable of generating response entities which have
+ content characteristics not acceptable according to the accept headers
+ sent in the request.
+ </para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_NOT_ACCEPTABLE) {
@@ -1121,7 +1381,12 @@
<name>HTTP_NOT_FOUND</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_NOT_FOUND.html" />
+ <description>
+ <para>
+ Constant denoting HTTP Not Found status. The server has not found anything
+ matching the Request-URI.
+ </para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_NOT_FOUND) {
@@ -1137,7 +1402,12 @@
<name>HTTP_NOT_IMPLEMENTED</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_NOT_IMPLEMENTED.html" />
+ <description>
+ <para>
+ Constant denoting HTTP Not Implemented status. The server does not support
+ the functionality required to fulfill the request.
+ </para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_NOT_IMPLEMENTED) {
@@ -1153,7 +1423,13 @@
<name>HTTP_NOT_MODIFIED</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_NOT_MODIFIED.html" />
+ <description>
+ <para>
+ Constant denoting HTTP Not Modified status. If the client has performed
+ a conditional GET request and access is allowed, but the document has
+ not been modified, the server SHOULD respond with this status code.
+ </para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_NOT_MODIFIED) {
@@ -1169,7 +1445,12 @@
<name>HTTP_NO_CONTENT</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_NO_CONTENT.html" />
+ <description>
+ <para>
+ Constant denoting HTTP No Content status. The server has fulfilled the
+ request but there is no new information to send back.
+ </para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_NO_CONTENT) {
@@ -1185,7 +1466,11 @@
<name>HTTP_OK</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_OK.html" />
+ <description>
+ <para>
+ Constant denoting HTTP OK status. The request has succeeded.
+ </para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_OK) {
@@ -1201,7 +1486,12 @@
<name>HTTP_PARTIAL_CONTENT</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_PARTIAL_CONTENT.html" />
+ <description>
+ <para>
+ Constant denoting HTTP Partial Content status. The server has
+ fulfilled the partial GET request for the resource.
+ </para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_PARTIAL_CONTENT) {
@@ -1217,7 +1507,12 @@
<name>HTTP_PAYMENT_REQUIRED</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_PAYMENT_REQUIRED.html" />
+ <description>
+ <para>
+ Constant denoting HTTP Payment Required status. This code is reserved
+ for future use.
+ </para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_PAYMENT_REQUIRED) {
@@ -1233,7 +1528,13 @@
<name>HTTP_PRECONDITION_FAILED</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_PRECONDITION_FAILED.html" />
+ <description>
+<para>
+Constant denoting HTTP Precondition Failed status. The precondition
+given in one or more of the request-header fields evaluated to false
+when it was tested on the server.
+</para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_PRECONDITION_FAILED) {
@@ -1265,7 +1566,13 @@
<name>HTTP_PROXY_AUTHENTICATION_REQUIRED</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_PROXY_AUTHENTICATION_REQUIRED.html" />
+ <description>
+<para>
+Constant denoting HTTP Proxy Authentication Required status. This code
+is similar to Unauthorized, but indicates that the client MUST first
+authenticate itself with the proxy.
+</para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_PROXY_AUTHENTICATION_REQUIRED) {
@@ -1297,7 +1604,13 @@
<name>HTTP_REQUEST_ENTITY_TOO_LARGE</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_REQUEST_ENTITY_TOO_LARGE.html" />
+ <description>
+<para>
+Constant denoting HTTP Request Entity Too Large status. The server is
+refusing to process a request because the request entity is larger than
+the server is willing or able to process.
+</para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_REQUEST_ENTITY_TOO_LARGE) {
@@ -1313,7 +1626,12 @@
<name>HTTP_REQUEST_TIME_OUT</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_REQUEST_TIME_OUT.html" />
+ <description>
+<para>
+Constant denoting HTTP Request Time Out status. The client did not produce
+a request within the time that the server was prepared to wait.
+</para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_REQUEST_TIME_OUT) {
@@ -1329,7 +1647,13 @@
<name>HTTP_REQUEST_URI_TOO_LARGE</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_REQUEST_URI_TOO_LARGE.html" />
+ <description>
+<para>
+Constant denoting HTTP Request URI Too Long status. The server is refusing
+to service the request because the Request-URI is longer than the server
+is willing to interpret.
+</para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_REQUEST_URI_TOO_LARGE) {
@@ -1345,7 +1669,13 @@
<name>HTTP_RESET_CONTENT</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_RESET_CONTENT.html" />
+ <description>
+<para>
+Constant denoting HTTP Reset Content status. The server has fulfilled
+the request and the user agent SHOULD reset the document view which
+caused the request to be sent.
+</para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_RESET_CONTENT) {
@@ -1361,7 +1691,13 @@
<name>HTTP_SEE_OTHER</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_SEE_OTHER.html" />
+ <description>
+<para>
+Constant denoting HTTP See Other status. The response to the request can
+be found under a different URI and SHOULD be retrieved using a GET method
+on that resource.
+</para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_SEE_OTHER) {
@@ -1377,7 +1713,13 @@
<name>HTTP_SERVICE_UNAVAILABLE</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_SERVICE_UNAVAILABLE.html" />
+ <description>
+<para>
+Constant denoting HTTP Service Unavailable status. The server is currently
+unable to handle the request due to a temporary overloading or maintenance
+of the server.
+</para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_SERVICE_UNAVAILABLE) {
@@ -1393,7 +1735,14 @@
<name>HTTP_SWITCHING_PROTOCOLS</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_SWITCHING_PROTOCOLS.html" />
+ <description>
+<para>
+Constant denoting HTTP Switching Protocols status. The server understands
+and is willing to comply with the client's request, via the Upgrade message
+header field, for a change in the application protocol being used on this
+connection.
+</para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_SWITCHING_PROTOCOLS) {
@@ -1409,7 +1758,12 @@
<name>HTTP_UNAUTHORIZED</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_UNAUTHORIZED.html" />
+ <description>
+<para>
+Constant denoting HTTP Unauthorized status. The request requires user
+authentication.
+</para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_UNAUTHORIZED) {
@@ -1441,7 +1795,13 @@
<name>HTTP_UNSUPPORTED_MEDIA_TYPE</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_UNSUPPORTED_MEDIA_TYPE.html" />
+ <description>
+<para>
+Constant denoting HTTP Unsupported Media Type status. The server is
+refusing to service the request because the entity of the request is
+in a format not supported by the requested resource for the requested method.
+</para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_UNSUPPORTED_MEDIA_TYPE) {
@@ -1457,7 +1817,12 @@
<name>HTTP_USE_PROXY</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_USE_PROXY.html" />
+ <description>
+<para>
+Constant denoting HTTP Use Proxy status. The requested resource MUST
+be accessed through the proxy given by the Location field.
+</para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_USE_PROXY) {
@@ -1473,7 +1838,12 @@
<name>HTTP_VARIANT_ALSO_VARIES</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_VARIANT_ALSO_VARIES.html" />
+ <description>
+<para>
+Constant denoting HTTP Variant Also Varies status. This status is not
+yet defined.
+</para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_VARIANT_ALSO_VARIES) {
@@ -1530,7 +1900,13 @@
<name>HTTP_VERSION_NOT_SUPPORTED</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HTTP_VERSION_NOT_SUPPORTED.html" />
+ <description>
+<para>
+Constant denoting HTTP Version Not Supported status. The server does not
+support, or refuses to support, the HTTP protocol version that was used
+in the request message.
+</para>
+ </description>
<example>
<text>request_rec *r;
if (r->status == HTTP_VERSION_NOT_SUPPORTED) {
@@ -1546,7 +1922,14 @@
<name>HUGE_STRING_LEN</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-HUGE_STRING_LEN.html" />
+ <description>
+<para>
+This constant defines the largest static string buffer Apache supports.
+The default setting is 8192 bytes, and changing it requires editing
+the <literal>httpd.conf</literal> file -- this setting <i>cannot</i> be
+overridden by a <literal>-D</literal> flag on the compiler command line.
+</para>
+ </description>
<example>
<text>char random_string[HUGE_STRING_LEN];</text>
</example>
@@ -1560,7 +1943,11 @@
<definition>
<declaration>#include "httpd.h"
<i>see</i> cmd_how.</declaration>
- <description href="dict-ITERATE.html" />
+ <description>
+<para>
+Command takes one argument, which may occur more than once.
+</para>
+ </description>
<example>
<text>static const command_rec module_cmds[] =
{
@@ -1581,7 +1968,12 @@
<definition>
<declaration>#include "httpd.h"
<i>see</i> cmd_how.</declaration>
- <description href="dict-ITERATE2.html" />
+ <description>
+<para>
+Command takes one argument, the second of which which may occur more
+than once.
+</para>
+ </description>
<example>
<text>static const command_rec module_cmds[] =
{
@@ -1601,7 +1993,15 @@
<name>LF</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-LF.html" />
+ <description>
+<para>
+The <literal>LF</literal> macro defines a name for the line-feed
+character's value. This value is different depending upon whether
+the <literal>CHARSET_ECDIC</literal> macro is defined. <literal>LF</literal>
+is primarily intended to be used in string searching and
+construction.
+</para>
+ </description>
<example>
<text>*++string = LF;</text>
</example>
@@ -1614,7 +2014,12 @@
<name>MAX_STRING_LEN</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-MAX_STRING_LEN.html" />
+ <description>
+<para>
+This is another name for the <literal>HUGE_STRING_LEN</literal> constant
+(<i>q.v.</i>).
+</para>
+ </description>
<example>
<text>char random_string[MAX_STRING_LEN];</text>
</example>
@@ -1627,7 +2032,20 @@
<name>MODULE_MAGIC_AT_LEAST</name>
<definition>
<declaration><i>Obsolete</i></declaration>
- <description href="dict-MODULE_MAGIC_AT_LEAST.html" />
+ <description>
+<para>
+This macro has been replaced by the <literal>AP_MODULE_MAGIC_AT_LEAST</literal>
+macro, which both has namespace protection (<i>via</i> the <literal>AP_</literal>
+prefix) and works correctly -- which the <literal>MODULE_MAGIC_AT_LEAST</literal>
+macro did not.
+</para>
+<para>
+<literal>MODULE_MAGIC_AT_LEAST</literal> is listed here solely for completeness,
+as it might be encountered in older modules. It should <i>not</i>
+be used; the <literal>AP_MODULE_MAGIC_AT_LEAST</literal> macro should always
+be used instead in new modules.
+</para>
+ </description>
<seealso>
<ref>SA-MMN</ref>
</seealso>
@@ -1652,7 +2070,21 @@
<name>MODULE_MAGIC_NUMBER</name>
<definition>
<declaration>#include "ap_mmn.h"</declaration>
- <description href="dict-MODULE_MAGIC_NUMBER.html" />
+ <description>
+<para>
+In versions of Apache prior to 1.3.3,
+this constant represented an Apache server module API version. Modules should
+have a version member of their internal module structure which matches the
+<literal>MODULE_MAGIC_NUMBER</literal> of the Apache source base with which they'll
+run.
+</para>
+<para>
+This constant was obsoleted in Apache 1.3.3 by the
+<literal>MODULE_MAGIC_NUMBER_MAJOR</literal> and
+<literal>MODULE_MAGIC_NUMBER_MINOR</literal> constants and the
+<literal>AP_MODULE_MAGIC_AT_LEAST</literal> macro (<i>q.q.v.</i>).
+</para>
+ </description>
<example>
<text>module *m;
if (m->version != MODULE_MAGIC_NUMBER)
@@ -1694,7 +2126,11 @@
<name>MULTI_ERR</name>
<definition>
<declaration>#include "multithread.h"</declaration>
- <description href="dict-MULTI_ERR.html" />
+ <description>
+<para>
+Constant used for thread error return value.
+</para>
+ </description>
<example>
<text>static int
map_rv(int rv)
@@ -1725,7 +2161,11 @@
<name>MULTI_OK</name>
<definition>
<declaration>#include "multithread.h"</declaration>
- <description href="dict-MULTI_OK.html" />
+ <description>
+<para>
+Constant used for thread success return value.
+</para>
+ </description>
<example>
<text>static int
map_rv(int rv)
@@ -1756,7 +2196,11 @@
<name>MULTI_TIMEOUT</name>
<definition>
<declaration>#include "multithread.h"</declaration>
- <description href="dict-MULTI_TIMEOUT.html" />
+ <description>
+<para>
+Constant used for thread timeout return value.
+</para>
+ </description>
<example>
<text>static int
map_rv(int rv)
@@ -1787,7 +2231,11 @@
<name>M_CONNECT</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-M_CONNECT.html" />
+ <description>
+<para>
+Constant representing the HTTP CONNECT method.
+</para>
+ </description>
<example>
<text>request_rec *r;
if (r->method_number == M_CONNECT) {
@@ -1819,7 +2267,11 @@
<name>M_DELETE</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-M_DELETE.html" />
+ <description>
+<para>
+Constant representing the HTTP DELETE method.
+</para>
+ </description>
<example>
<text>request_rec *r;
if (r->method_number == M_DELETE) {
@@ -1835,7 +2287,11 @@
<name>M_GET</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-M_GET.html" />
+ <description>
+<para>
+Constant representing the HTTP GET method.
+</para>
+ </description>
<example>
<text>request_rec *r;
if (r->method_number == M_GET) {
@@ -1851,7 +2307,11 @@
<name>M_INVALID</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-M_INVALID.html" />
+ <description>
+<para>
+Constant representing the HTTP INVALID method.
+</para>
+ </description>
<example>
<text>request_rec *r;
if (r->method_number == M_INVALID) {
@@ -1915,7 +2375,11 @@
<name>M_OPTIONS</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-M_OPTIONS.html" />
+ <description>
+<para>
+Constant representing the HTTP OPTIONS method.
+</para>
+ </description>
<example>
<text>request_rec *r;
if (r->method_number == M_OPTIONS) {
@@ -1947,7 +2411,11 @@
<name>M_POST</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-M_POST.html" />
+ <description>
+<para>
+Constant representing the HTTP POST method.
+</para>
+ </description>
<example>
<text>request_rec *r;
if (r->method_number == M_POST) {
@@ -1979,7 +2447,11 @@
<name>M_PUT</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-M_PUT.html" />
+ <description>
+<para>
+Constant representing the HTTP PUT method.
+</para>
+ </description>
<example>
<text>request_rec *r;
if (r->method_number == M_PUT) {
@@ -1995,7 +2467,11 @@
<name>M_TRACE</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-M_TRACE.html" />
+ <description>
+<para>
+Constant representing the HTTP TRACE method.
+</para>
+ </description>
<example>
<text>request_rec *r;
if (r->method_number == M_TRACE) {
@@ -2088,7 +2564,11 @@
<definition>
<declaration>#include "httpd.h"
<i>see</i> cmd_how.</declaration>
- <description href="dict-NO_ARGS.html" />
+ <description>
+<para>
+Command takes no arguments.
+</para>
+ </description>
<example>
<text>static const command_rec module_cmds[] =
{
@@ -2108,7 +2588,11 @@
<name>OK</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-OK.html" />
+ <description>
+<para>
+The module has handled this stage of request processing.
+</para>
+ </description>
<example>
<text>request_rec *r;
if (!is_HTTP_ERROR(r->status)) {
@@ -2292,7 +2776,7 @@
inside <Directory> or <Location> containers, and in
<literal>.htaccess</literal>
files when the scope is covered by an
- <literal>AllowOverride AuthConfig</literal>
+ <literal>AllowOverride AuthConfig</literal>
keyword.
</para>
</description>
@@ -2315,7 +2799,20 @@
<name>OR_FILEINFO</name>
<definition>
<declaration>#include "http_config.h"</declaration>
- <description href="dict-OR_FILEINFO.html" />
+ <description>
+<para>
+Allowed locations for a configuration directive are the union of
+those indicated by each set bit in the <literal>req_override</literal> mask in the
+<literal>command_rec</literal> structure.
+</para>
+<para>
+A directive with the <literal>OR_FILEINFO</literal> bit set may appear
+anywhere in the server-wide configuration files (<i>e.g.</i>,
+<literal>httpd.conf</literal>), and in
+<literal>.htaccess</literal> files when the scope is covered by an
+<literal>AllowOverride FileInfo</literal> keyword.
+</para>
+ </description>
<example>
<text>static const command_rec module_cmds[] =
{
@@ -2335,7 +2832,20 @@
<name>OR_INDEXES</name>
<definition>
<declaration>#include "http_config.h"</declaration>
- <description href="dict-OR_INDEXES.html" />
+ <description>
+<para>
+Allowed locations for a configuration directive are the union of
+those indicated by each set bit in the <literal>req_override</literal> mask in the
+<literal>command_rec</literal> structure.
+</para>
+<para>
+A directive with the <literal>OR_FILEINFO</literal> bit set may appear
+anywhere in the server-wide configuration files (<i>e.g.</i>,
+<literal>httpd.conf</literal>), and in
+<literal>.htaccess</literal> files when the scope is covered by an
+<literal>AllowOverride Indexes</literal> keyword.
+</para>
+ </description>
<example>
<text>static const command_rec module_cmds[] =
{
@@ -2355,7 +2865,20 @@
<name>OR_LIMIT</name>
<definition>
<declaration>#include "http_config.h"</declaration>
- <description href="dict-OR_LIMIT.html" />
+ <description>
+<para>
+Allowed locations for a configuration directive are the union of
+those indicated by each set bit in the <literal>req_override</literal> mask in the
+<literal>command_rec</literal> structure.
+</para>
+<para>
+A directive with the <literal>OR_LIMIT</literal> bit set may appear
+in the server-wide configuration files (<i>e.g.</i>, <literal>httpd.conf</literal>)
+inside <Directory> or <Location> containers, and in
+<literal>.htaccess</literal> files when the scope is covered by an
+<literal>AllowOverride Limit</literal> keyword.
+</para>
+ </description>
<example>
<text>static const command_rec module_cmds[] =
{
@@ -2375,7 +2898,20 @@
<name>OR_OPTIONS</name>
<definition>
<declaration>#include "http_config.h"</declaration>
- <description href="dict-OR_OPTIONS.html" />
+ <description>
+<para>
+Allowed locations for a configuration directive are the union of
+those indicated by each set bit in the <literal>req_override</literal> mask in the
+<literal>command_rec</literal> structure.
+</para>
+<para>
+A directive with the <literal>OR_LIMIT</literal> bit set may appear
+anywhere in the server-wide configuration files (<i>e.g.</i>,
+<literal>httpd.conf</literal>), and in
+<literal>.htaccess</literal> files when the scope is covered by an
+<literal>AllowOverride Options</literal> keyword.
+</para>
+ </description>
<example>
<text>static const command_rec module_cmds[] =
{
@@ -2415,7 +2951,12 @@
<definition>
<declaration>#include "httpd.h"
<i>see</i> cmd_how.</declaration>
- <description href="dict-RAW_ARGS.html" />
+ <description>
+<para>
+Command function (in cmd_func) parses the command itself. Pstrdup() is
+usually used to copy arguments into local storage.
+</para>
+ </description>
<example>
<text>static const command_rec module_cmds[] =
{
@@ -2701,7 +3242,30 @@
<name>SECURITY_HOLE_PASS_AUTHORIZATION</name>
<definition>
<declaration>Compile-time definition</declaration>
- <description href="dict-SECURITY_HOLE_PASS_AUTHORIZATION.html" />
+ <description>
+<para>
+When user authentication is required to obtain access to a document,
+the user credentials (username and password) are available to the
+server. Ordinarily Apache only makes the username available to
+<literal>mod_include</literal> and CGI scripts, keeping the password
+secret. It can be configured to make the complete credential
+details available (in the <literal>HTTP_AUTHORIZATION</literal> or
+<literal>HTTP_PROXY_AUTHORIZATION</literal> environment variables),
+but only by completely rebuilding the server with this
+compile-time definition added (as shown in the example).
+</para>
+<para>
+<b>Warning:</b> Enabling this feature is considered a security
+risk, as scripts and documents can capture all aspects of the
+user credentials. For example, your configuration may include
+an authentication database that is accessible only by the server,
+and not directly available to users. With this feature enabled,
+any script that is flagged as needing authentication checks against
+that database, even a user script, will be able to capture the
+credentials. In the case of <literal>Basic</literal> authentication,
+the password is available in cleartext.
+</para>
+ </description>
<example>
<text>env CFLAGS="-Wall -DSECURITY_HOLE_PASS_AUTHORIZATION" ./configure</text>
</example>
@@ -2714,7 +3278,11 @@
<name>SERVER_BUSY_DNS</name>
<definition>
<declaration>#include "scoreboard.h"</declaration>
- <description href="dict-SERVER_BUSY_DNS.html" />
+ <description>
+<para>
+Scoreboard state constant indicating the server is performing a DNS lookup.
+</para>
+ </description>
<example>
<text>switch (score_record.status) {
case SERVER_BUSY_DNS:
@@ -2731,7 +3299,12 @@
<name>SERVER_BUSY_KEEPALIVE</name>
<definition>
<declaration>#include "scoreboard.h"</declaration>
- <description href="dict-SERVER_BUSY_KEEPALIVE.html" />
+ <description>
+<para>
+Scoreboard state constant indicating the server is servicing a
+keepalive (persistent HTTP) request
+</para>
+ </description>
<example>
<text>switch (score_record.status) {
case SERVER_BUSY_KEEPALIVE:
@@ -2748,7 +3321,11 @@
<name>SERVER_BUSY_LOG</name>
<definition>
<declaration>#include "scoreboard.h"</declaration>
- <description href="dict-SERVER_BUSY_LOG.html" />
+ <description>
+<para>
+Scoreboard state constant indicating the server is writing to a log file.
+</para>
+ </description>
<example>
<text>switch (score_record.status) {
case SERVER_BUSY_LOG:
@@ -2765,7 +3342,12 @@
<name>SERVER_BUSY_READ</name>
<definition>
<declaration>#include "scoreboard.h"</declaration>
- <description href="dict-SERVER_BUSY_READ.html" />
+ <description>
+<para>
+Scoreboard state constant indicating the server is reading data from
+a client (browser).
+</para>
+ </description>
<example>
<text>switch (score_record.status) {
case SERVER_BUSY_READ:
@@ -2782,7 +3364,12 @@
<name>SERVER_BUSY_WRITE</name>
<definition>
<declaration>#include "scoreboard.h"</declaration>
- <description href="dict-SERVER_BUSY_WRITE.html" />
+ <description>
+<para>
+Scoreboard state constant indicating the server is writing data to a
+client (browser).
+</para>
+ </description>
<example>
<text>switch (score_record.status) {
case SERVER_BUSY_WRITE:
@@ -2799,7 +3386,11 @@
<name>SERVER_DEAD</name>
<definition>
<declaration>#include "scoreboard.h"</declaration>
- <description href="dict-SERVER_DEAD.html" />
+ <description>
+<para>
+Scoreboard state constant indicating the server is down.
+</para>
+ </description>
<example>
<text>switch (score_record.status) {
case SERVER_DEAD:
@@ -2816,7 +3407,12 @@
<name>SERVER_GRACEFUL</name>
<definition>
<declaration>#include "scoreboard.h"</declaration>
- <description href="dict-SERVER_GRACEFUL.html" />
+ <description>
+<para>
+Scoreboard state constant indicating the server is performing a
+graceful restart (without dropping all pending connects).
+</para>
+ </description>
<example>
<text>switch (score_record.status) {
case SERVER_GRACEFUL:
@@ -2833,7 +3429,12 @@
<name>SERVER_NUM_STATUS</name>
<definition>
<declaration>#include "scoreboard.h"</declaration>
- <description href="dict-SERVER_NUM_STATUS.html" />
+ <description>
+<para>
+Scoreboard constant indicating the number of state variables, for
+range checking.
+</para>
+ </description>
<example>
<text>if (score_record.status < SERVER_NUM_STATUS) {
return OK;
@@ -2848,7 +3449,12 @@
<name>SERVER_READY</name>
<definition>
<declaration>#include "scoreboard.h"</declaration>
- <description href="dict-SERVER_READY.html" />
+ <description>
+<para>
+Scoreboard state constant indicating the server is ready and waiting for a
+connection.
+</para>
+ </description>
<example>
<text>switch (score_record.status) {
case SERVER_READY:
@@ -2865,7 +3471,11 @@
<name>SERVER_STARTING</name>
<definition>
<declaration>#include "scoreboard.h"</declaration>
- <description href="dict-SERVER_STARTING.html" />
+ <description>
+<para>
+Scoreboard state constant indicating the server is spawning.
+</para>
+ </description>
<example>
<text>switch (score_record.status) {
case SERVER_STARTING:
@@ -2881,8 +3491,14 @@
<item type="Constant">
<name>SERVER_SUPPORT</name>
<definition>
- <declaration>Compile-time definition; default set by <code>#include "httpd.h"</code></declaration>
- <description href="dict-SERVER_SUPPORT.html" />
+ <declaration>Compile-time definition; default set by #include "httpd.h"</declaration>
+ <description>
+<para>
+This is the location at which to seek support for the server. Third parties
+should change this *only* if they intend to provide support
+for their release of Apache.
+</para>
+ </description>
<example>
<text>ap_snprintf(buf, sizeof(buf), "For further assistance, go to SERVER_SUPPORT");</text>
</example>
@@ -2892,7 +3508,11 @@
<name>SERVER_VERSION</name>
<definition>
<declaration>#include "httpd.h"</declaration>
- <description href="dict-SERVER_VERSION.html" />
+ <description>
+<para>
+String containing the Apache server version; a legacy.
+</para>
+ </description>
<example>
<text>Deprecated; use ap_get_server_version() instead.</text>
</example>
@@ -2912,7 +3532,12 @@
<name>START_PREQUEST</name>
<definition>
<declaration>#include "scoreboard.h"</declaration>
- <description href="dict-START_PREQUEST.html" />
+ <description>
+<para>
+This constant is used to indicate a request's processing is started.
+Useful for timing purposes.
+</para>
+ </description>
<example>
<text>if (status == START_PREQUEST) {
...deal with request start time...
@@ -2927,7 +3552,12 @@
<name>STOP_PREQUEST</name>
<definition>
<declaration>#include "scoreboard.h"</declaration>
- <description href="dict-STOP_PREQUEST.html" />
+ <description>
+<para>
+This constant is used to indicate a request's processing is stopped (not
+necessarily completed). Useful for timing purposes.
+</para>
+ </description>
<example>
<text>if (status == STOP_PREQUEST) {
...deal with request stop time...
@@ -2943,7 +3573,11 @@
<definition>
<declaration>#include "httpd.h"
<i>see</i> cmd_how.</declaration>
- <description href="dict-TAKE1.html" />
+ <description>
+<para>
+Command will take one argument only.
+</para>
+ </description>
<example>
<text>static const command_rec module_cmds[] =
{
@@ -2964,7 +3598,11 @@
<definition>
<declaration>#include "httpd.h"
<i>see</i> cmd_how.</declaration>
- <description href="dict-TAKE12.html" />
+ <description>
+<para>
+Command will take one or two arguments.
+</para>
+ </description>
<example>
<text>static const command_rec module_cmds[] =
{
@@ -2985,7 +3623,11 @@
<definition>
<declaration>#include "httpd.h"
<i>see</i> cmd_how.</declaration>
- <description href="dict-TAKE123.html" />
+ <description>
+<para>
+Command will take one, two, or three arguments.
+</para>
+ </description>
<example>
<text>static const command_rec module_cmds[] =
{
@@ -3006,7 +3648,11 @@
<definition>
<declaration>#include "httpd.h"
<i>see</i> cmd_how.</declaration>
- <description href="dict-TAKE13.html" />
+ <description>
+<para>
+Command will take one or three arguments only.
+</para>
+ </description>
<example>
<text>static const command_rec module_cmds[] =
{
@@ -3027,7 +3673,11 @@
<definition>
<declaration>#include "httpd.h"
<i>see</i> cmd_how.</declaration>
- <description href="dict-TAKE2.html" />
+ <description>
+<para>
+Command will take one or two arguments.
+</para>
+ </description>
<example>
<text>static const command_rec module_cmds[] =
{
@@ -3048,7 +3698,11 @@
<definition>
<declaration>#include "httpd.h"
<i>see</i> cmd_how.</declaration>
- <description href="dict-TAKE23.html" />
+ <description>
+<para>
+Command will take two or three arguments.
+</para>
+ </description>
<example>
<text>static const command_rec module_cmds[] =
{
@@ -3069,7 +3723,11 @@
<definition>
<declaration>#include "httpd.h"
<i>see</i> cmd_how.</declaration>
- <description href="dict-TAKE3.html" />
+ <description>
+<para>
+Command will take three arguments only.
+</para>
+ </description>
<example>
<text>static const command_rec module_cmds[] =
{
@@ -3088,8 +3746,19 @@
<item type="Constant">
<name>TARGET</name>
<definition>
- <declaration>Compile-time definition; default set by <code>#include "httpd.h"</code></declaration>
- <description href="dict-TARGET.html" />
+ <declaration>Compile-time definition; default set by #include "httpd.h"</declaration>
+ <description>
+<para>
+The <literal>TARGET</literal> macro is used to determine the name of
+the main Apache executable file, and locate the shared core library.
+By default its value is set to "<literal>httpd</literal>".
+</para>
+<para>
+You should <b>NOT</b> change this definition unless you have a
+a definite need, or have been advised by someone on the core Apache
+development team to do so.
+</para>
+ </description>
<example>
<text>env CFLAGS="-Wall -DTARGET=\"apache\"" ./configure</text>
</example>
@@ -3167,7 +3836,15 @@
<name>ap_acquire_mutex</name>
<definition>
<declaration>int ap_acquire_mutex(mutex *mutex_id);</declaration>
- <description href="dict-ap_acquire_mutex.html" />
+ <description>
+<para>
+Acquires a mutex. Only actually does anything on
+multithreaded platforms.
+</para>
+<para>
+Returns MULTI_OK, MULTI_ERR or MULTI_TIMEOUT.
+</para>
+ </description>
<example>
<text>static mutex *alloc_mutex = NULL;
(void) ap_acquire_mutex(alloc_mutex);</text>
@@ -3182,7 +3859,24 @@
<name>ap_add_cgi_vars</name>
<definition>
<declaration>void ap_add_cgi_vars(request_rec *r);</declaration>
- <description href="dict-ap_add_cgi_vars.html" />
+ <description>
+<para>
+Sets CGI script related variables in the subprocess (child) environment
+by setting them in the request_rec's <literal>subprocess_env</literal>
+table. Variables set are:
+</para>
+<ul>
+ <li><literal>GATEWAY_INTERFACE</literal></li>
+ <li><literal>PATH_INFO</literal> (added if and only if there is path-info in
+ the request URI)</li>
+ <li><literal>PATH_TRANSLATED</literal></li>
+ <li><literal>QUERY_STRING</literal></li>
+ <li><literal>REQUEST_METHOD</literal></li>
+ <li><literal>REQUEST_URI</literal></li>
+ <li><literal>SCRIPT_NAME</literal></li>
+ <li><literal>SERVER_PROTOCOL</literal></li>
+</ul>
+ </description>
<example>
<text>request_rec *r;
ap_add_cgi_vars(r);</text>
@@ -3193,7 +3887,46 @@
<name>ap_add_common_vars</name>
<definition>
<declaration>void ap_add_common_vars(request_rec *r);</declaration>
- <description href="dict-ap_add_common_vars.html" />
+ <description>
+<para>
+Adds common variables to the subprocess (child) environment by
+inserting them into a request_rec's <literal>subprocess_env</literal> table.
+Variables placed there are:
+</para>
+<ul>
+ <li>CGI variables (see <literal>ap_add_cgi_vars</literal>)</li>
+ <li><literal>CONTENT_TYPE</literal></li>
+ <li><literal>CONTENT_LENGTH</literal></li>
+ <li><literal>PATH</literal></li>
+ <li><literal>SERVER_NAME</literal></li>
+ <li><literal>SERVER_PORT</literal></li>
+ <li><literal>REMOTE_HOST</literal></li>
+ <li><literal>REMOTE_ADDR</literal></li>
+ <li><literal>DOCUMENT_ROOT</literal></li>
+ <li><literal>SERVER_ADMIN</literal></li>
+ <li><literal>SCRIPT_FILENAME</literal></li>
+ <li><literal>REMOTE_PORT</literal></li>
+ <li><literal>REMOTE_USER</literal></li>
+ <li><literal>REMOTE_IDENT</literal></li>
+</ul>
+<para>
+If the request is the result of an error redirect, the following
+will also be set:
+</para>
+<ul>
+ <li><literal>REDIRECT_QUERY_STRING</literal></li>
+ <li><literal>REDIRECT_URL</literal></li>
+</ul>
+<para>
+The following are also added in when Apache is running in a Windows
+environment:
+</para>
+<ul>
+ <li><literal>SystemRoot</literal></li>
+ <li><literal>COMSPEC</literal></li>
+ <li><literal>WINDIR</literal></li>
+</ul>
+ </description>
<example>
<text>request_rec *r;
ap_add_common_vars(r);</text>
@@ -3204,7 +3937,19 @@
<name>ap_add_loaded_module</name>
<definition>
<declaration>void ap_add_loaded_module(module *m);</declaration>
- <description href="dict-ap_add_loaded_module.html" />
+ <description>
+<para>
+This routine links the specified module record into the core
+server's list of available modules. The module in question must
+already have been loaded into memory, either as a DSO or by
+being statically linked into the server.
+</para>
+<note>
+ This routine should not be called unless you are <i>very</i>
+ sure you know what you're doing, as it can render the server
+ unstable if not used correctly.
+</note>
+ </description>
<example>
<text>module mod;
ap_add_loaded_module(mod);</text>
@@ -3247,7 +3992,15 @@
<name>ap_add_per_dir_conf</name>
<definition>
<declaration>void ap_add_per_dir_conf(server_rec *s, void *dir_config);</declaration>
- <description href="dict-ap_add_per_dir_conf.html" />
+ <description>
+<para>
+Add per-directory configuration entry (for <Directory> section);
+these are part of the core server config.
+</para>
+<para>
+Returns a core_server_config structure.
+</para>
+ </description>
<example>
<text><i>Private to the Apache core server; not for module use.</i></text>
</example>
@@ -3269,7 +4022,22 @@
<name>ap_add_version_component</name>
<definition>
<declaration>void ap_add_version_component(const char *component);</declaration>
- <description href="dict-ap_add_version_component.html" />
+ <description>
+ <para>
+ This routine adds the specified component identification to
+ the string used as the value of the <literal>Server:</literal> response
+ header field. It may only be called during the module init phase, and
+ the value must either be a valid component version string (<i>i.e.</i>,
+ <literal>"<i>component-name</i>/<i>n</i>.<i>n</i>"</literal>) or a
+ parenthesis-enclosed comment (<i>e.g.</i>, <literal>"(comment)"</literal>).
+ </para>
+ <para>
+ Whether this additional server identification information is actually
+ included in the response header field depends upon the setting of the
+ <literal><ref href="http://www.apache.org/docs/mod/core.html#servertokens"
+ >ServerTokens</ref></literal> configuration directive (<i>q.v.</i>).
+ </para>
+ </description>
<example>
<text>/*
* Called during modules-init phase
@@ -3285,7 +4053,8 @@
<name>ap_allow_options</name>
<definition>
<declaration>int ap_allow_options(request_rec *r);</declaration>
- <description href="dict-ap_allow_options.html" />
+ <description href="dict-ap_allow_options.html">
+ </description>
<example>
<text>request_rec *r;
int result;
@@ -3318,7 +4087,8 @@
<name>ap_append_arrays</name>
<definition>
<declaration>array_header *ap_append_arrays(pool *p, const array_header *a, const array_header *b);</declaration>
- <description href="dict-ap_append_arrays.html" />
+ <description href="dict-ap_append_arrays.html">
+ </description>
<example>
<text>new->hdr_list = ap_append_arrays(p, add->hdr_list, base->hdr_list);</text>
</example>
@@ -3331,7 +4101,8 @@
<name>ap_array_cat</name>
<definition>
<declaration>void ap_array_cat(array_header *dst, const array_header *src);</declaration>
- <description href="dict-ap_array_cat.html" />
+ <description href="dict-ap_array_cat.html">
+ </description>
<example>
<text>ap_array_cat(&res->a, &base->second);</text>
</example>