Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

This commit was manufactured by cvs2svn to create tag

'APACHE_BIG_SYMBOL_RENAME_PRE'.

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/tags/APACHE_BIG_SYMBOL_RENAME_PRE@80863 13f79535-47bb-0310-9956-ffa450edef68
  • Loading branch information...
commit 3dea7bf0bcf5f50f3bbdcfd9414944b328902982 1 parent 407f332
authored April 11, 1998
BIN  docs/docroot/apache_pb.gif
132  docs/manual/bind.html.en
... ...
@@ -1,132 +0,0 @@
1  
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2  
-<HTML><HEAD>
3  
-<TITLE>Setting which addresses and ports Apache uses</TITLE>
4  
-</HEAD>
5  
-
6  
-<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
7  
-<BODY
8  
- BGCOLOR="#FFFFFF"
9  
- TEXT="#000000"
10  
- LINK="#0000FF"
11  
- VLINK="#000080"
12  
- ALINK="#FF0000"
13  
->
14  
-<!--#include virtual="header.html" -->
15  
-<H1 ALIGN="CENTER">Setting which addresses and ports Apache uses</H1>
16  
-
17  
-<HR>
18  
-
19  
-When Apache starts, it connects to some port and address on the
20  
-local machine and waits for incoming requests. By default, it
21  
-listens to all addresses on the machine, and to the port
22  
-as specified by the <TT>Port</TT> directive in the server configuration.
23  
-However, it can be told to listen to more the one port, or to listen
24  
-to only selected addresses, or a combination. This is often combined
25  
-with the Virtual Host feature which determines how Apache
26  
-responds to different IP addresses, hostnames and ports.<P>
27  
-
28  
-There are two directives used to restrict or specify which addresses
29  
-and ports Apache listens to.
30  
-
31  
-<UL>
32  
-<LI><A HREF="#bindaddress">BindAddress</A> is used to restrict the server to listening to
33  
-  a single address, and can be used to permit multiple Apache servers
34  
-  on the same machine listening to different IP addresses.
35  
-<LI><A HREF="#listen">Listen</A> can be used to make a single Apache server listen
36  
-  to more than one address and/or port.
37  
-</UL>
38  
-
39  
-<H3><A name="bindaddress">BindAddress</A></H3>
40  
-<A
41  
- HREF="mod/directive-dict.html#Syntax"
42  
- REL="Help"
43  
-><STRONG>Syntax:</STRONG></A> BindAddress <EM>[ * | IP-address | hostname ]</EM><BR>
44  
-<A
45  
- HREF="mod/directive-dict.html#Default"
46  
- REL="Help"
47  
-><STRONG>Default:</STRONG></A> <CODE>BindAddress *</CODE><BR>
48  
-<A
49  
- HREF="mod/directive-dict.html#Context"
50  
- REL="Help"
51  
-><STRONG>Context:</STRONG></A> server config<BR>
52  
-<A
53  
- HREF="mod/directive-dict.html#Status"
54  
- REL="Help"
55  
-><STRONG>Status:</STRONG></A> Core<P>
56  
-
57  
-Makes the server listen to just the specified address. If the argument
58  
-is *, the server listens to all addresses. The port listened to
59  
-is set with the <TT>Port</TT> directive. Only one BindAddress
60  
-should be used.
61  
-
62  
-<H3><A name="listen">Listen</A></H3>
63  
-<A
64  
- HREF="mod/directive-dict.html#Syntax"
65  
- REL="Help"
66  
-><STRONG>Syntax:</STRONG></A> Listen <EM>[ port | IP-address:port ]</EM><BR>
67  
-<A
68  
- HREF="mod/directive-dict.html#Default"
69  
- REL="Help"
70  
-><STRONG>Default:</STRONG></A> <CODE>none</CODE><BR>
71  
-<A
72  
- HREF="mod/directive-dict.html#Context"
73  
- REL="Help"
74  
-><STRONG>Context:</STRONG></A> server config<BR>
75  
-<A
76  
- HREF="mod/directive-dict.html#Status"
77  
- REL="Help"
78  
-><STRONG>Status:</STRONG></A> Core<P>
79  
-
80  
-<TT>Listen</TT> can be used instead of <TT>BindAddress</TT> and
81  
-<TT>Port</TT>. It tells the server to accept incoming requests on the
82  
-specified port or address-and-port combination. If the first format is
83  
-used, with a port number only, the server listens to the given port on
84  
-all interfaces, instead of the port given by the <TT>Port</TT>
85  
-directive. If an IP address is given as well as a port, the server
86  
-will listen on the given port and interface.  <P> Multiple Listen
87  
-directives may be used to specify a number of addresses and ports to
88  
-listen to. The server will respond to requests from any of the listed
89  
-addresses and ports.<P>
90  
-
91  
-For example, to make the server accept connections on both port
92  
-80 and port 8000, use:
93  
-<PRE>
94  
-   Listen 80
95  
-   Listen 8000
96  
-</PRE>
97  
-
98  
-To make the server accept connections on two specified
99  
-interfaces and port numbers, use
100  
-<PRE>
101  
-   Listen 192.170.2.1:80
102  
-   Listen 192.170.2.5:8000
103  
-</PRE>
104  
-
105  
-<H2>How this works with Virtual Hosts</H2>
106  
-
107  
-BindAddress and Listen do not implement Virtual Hosts. They tell the
108  
-main server what addresses and ports to listen to.  If no
109  
-&lt;VirtualHost&gt; directives are used, the server will behave the
110  
-same for all accepted requests. However, &lt;VirtualHost&gt; can be
111  
-used to specify a different behavior for one or more of the addresses
112  
-and ports. To implement a VirtualHost, the server must first be told
113  
-to listen to the address and port to be used. Then a
114  
-&lt;VirtualHost&gt; section should be created for a specified address
115  
-and port to set the behavior of this virtual host. Note that if the
116  
-&lt;VirtualHost&gt; is set for an address and port that the server is
117  
-not listening to, it cannot be accessed.
118  
-
119  
-<H2>See also</H2>
120  
-
121  
-See also the documentation on
122  
-<A HREF="vhosts/index.html">Virtual Hosts</A>,
123  
-<A HREF="mod/core.html#bindaddress">BindAddress directive</A>,
124  
-<A HREF="mod/core.html#port">Port directive</A>,
125  
-<A HREF="dns-caveats.html">DNS Issues</A>
126  
-and
127  
-<A HREF="mod/core.html#virtualhost">&lt;VirtualHost&gt; section</A>.
128  
-
129  
-<!--#include virtual="footer.html" -->
130  
-</BODY>
131  
-</HTML>
132  
-
93  docs/manual/cgi_path.html.en
... ...
@@ -1,93 +0,0 @@
1  
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2  
-<HTML><HEAD>
3  
-<TITLE>PATH_INFO Changes in the CGI Environment</TITLE>
4  
-</HEAD>
5  
-
6  
-<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
7  
-<BODY
8  
- BGCOLOR="#FFFFFF"
9  
- TEXT="#000000"
10  
- LINK="#0000FF"
11  
- VLINK="#000080"
12  
- ALINK="#FF0000"
13  
->
14  
-<!--#include virtual="header.html" -->
15  
-<H1 ALIGN="CENTER">PATH_INFO Changes in the CGI Environment</H1>
16  
-
17  
-<HR>
18  
-
19  
-<H2><A name="over">Overview</A></H2>
20  
-
21  
-<P>As implemented in Apache 1.1.1 and earlier versions, the method
22  
-Apache used to create PATH_INFO in the CGI environment was
23  
-counterintuitive, and could result in crashes in certain cases. In
24  
-Apache 1.2 and beyond, this behavior has changed. Although this
25  
-results in some compatibility problems with certain legacy CGI
26  
-applications, the Apache 1.2 behavior is still compatible with the
27  
-CGI/1.1 specification, and CGI scripts can be easily modified (<A
28  
-HREF="#compat">see below</A>).
29  
-
30  
-<H2><A name="prob">The Problem</A></H2>
31  
-
32  
-<P>Apache 1.1.1 and earlier implemented the PATH_INFO and SCRIPT_NAME
33  
-environment variables by looking at the filename, not the URL. While
34  
-this resulted in the correct values in many cases, when the filesystem
35  
-path was overloaded to contain path information, it could result in
36  
-errant behavior. For example, if the following appeared in a config
37  
-file:
38  
-<PRE>
39  
-     Alias /cgi-ralph /usr/local/httpd/cgi-bin/user.cgi/ralph
40  
-</PRE>
41  
-<P>In this case, <CODE>user.cgi</CODE> is the CGI script, the "/ralph"
42  
-is information to be passed onto the CGI. If this configuration was in
43  
-place, and a request came for "<CODE>/cgi-ralph/script/</CODE>", the
44  
-code would set PATH_INFO to "<CODE>/ralph/script</CODE>", and
45  
-SCRIPT_NAME to "<CODE>/cgi-</CODE>". Obviously, the latter is
46  
-incorrect. In certain cases, this could even cause the server to
47  
-crash.</P>
48  
-
49  
-<H2><A name="solution">The Solution</A></H2>
50  
-
51  
-<P>Apache 1.2 and later now determine SCRIPT_NAME and PATH_INFO by
52  
-looking directly at the URL, and determining how much of the URL is
53  
-client-modifiable, and setting PATH_INFO to it. To use the above
54  
-example, PATH_INFO would be set to "<CODE>/script</CODE>", and
55  
-SCRIPT_NAME to "<CODE>/cgi-ralph</CODE>". This makes sense and results
56  
-in no server behavior problems. It also permits the script to be
57  
-guaranteed that
58  
-"<CODE>http://$SERVER_NAME:$SERVER_PORT$SCRIPT_NAME$PATH_INFO</CODE>"
59  
-will always be an accessible URL that points to the current script,
60  
-something which was not necessarily true with previous versions of
61  
-Apache.
62  
-
63  
-<P>However, the "<CODE>/ralph</CODE>"
64  
-information from the <CODE>Alias</CODE> directive is lost. This is
65  
-unfortunate, but we feel that using the filesystem to pass along this
66  
-sort of information is not a recommended method, and a script making
67  
-use of it "deserves" not to work. Apache 1.2b3 and later, however, do
68  
-provide <A HREF="#compat">a workaround.</A>
69  
-
70  
-<H2><A name="compat">Compatibility with Previous Servers</A></H2>
71  
-
72  
-<P>It may be necessary for a script that was designed for earlier
73  
-versions of Apache or other servers to need the information that the
74  
-old PATH_INFO variable provided. For this purpose, Apache 1.2 (1.2b3
75  
-and later) sets an additional variable, FILEPATH_INFO. This
76  
-environment variable contains the value that PATH_INFO would have had
77  
-with Apache 1.1.1.</P>
78  
-
79  
-<P>A script that wishes to work with both Apache 1.2 and earlier
80  
-versions can simply test for the existence of FILEPATH_INFO, and use
81  
-it if available. Otherwise, it can use PATH_INFO. For example, in
82  
-Perl, one might use:
83  
-<PRE>
84  
-    $path_info = $ENV{'FILEPATH_INFO'} || $ENV{'PATH_INFO'};
85  
-</PRE>
86  
-
87  
-<P>By doing this, a script can work with all servers supporting the
88  
-CGI/1.1 specification, including all versions of Apache.</P>
89  
-
90  
-<!--#include virtual="footer.html" -->
91  
-</BODY>
92  
-</HTML>
93  
-
525  docs/manual/content-negotiation.html.en
... ...
@@ -1,525 +0,0 @@
1  
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2  
-<HTML>
3  
-<HEAD>
4  
-<TITLE>Apache Content Negotiation</TITLE>
5  
-</HEAD>
6  
-
7  
-<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
8  
-<BODY
9  
- BGCOLOR="#FFFFFF"
10  
- TEXT="#000000"
11  
- LINK="#0000FF"
12  
- VLINK="#000080"
13  
- ALINK="#FF0000"
14  
->
15  
-<!--#include virtual="header.html" -->
16  
-<H1 ALIGN="CENTER">Content Negotiation</H1>
17  
-
18  
-<P>
19  
-Apache's support for content negotiation has been updated to meet the
20  
-HTTP/1.1 specification. It can choose the best representation of a
21  
-resource based on the browser-supplied preferences for media type,
22  
-languages, character set and encoding.  It is also implements a
23  
-couple of features to give more intelligent handling of requests from
24  
-browsers which send incomplete negotiation information.  <P>
25  
-
26  
-Content negotiation is provided by the
27  
-<A HREF="mod/mod_negotiation.html">mod_negotiation</A> module,
28  
-which is compiled in by default.
29  
-
30  
-<HR>
31  
-
32  
-<H2>About Content Negotiation</H2>
33  
-
34  
-<P>
35  
-A resource may be available in several different representations. For
36  
-example, it might be available in different languages or different
37  
-media types, or a combination.  One way of selecting the most
38  
-appropriate choice is to give the user an index page, and let them
39  
-select. However it is often possible for the server to choose
40  
-automatically. This works because browsers can send as part of each
41  
-request information about what representations they prefer. For
42  
-example, a browser could indicate that it would like to see
43  
-information in French, if possible, else English will do. Browsers
44  
-indicate their preferences by headers in the request. To request only
45  
-French representations, the browser would send
46  
-
47  
-<PRE>
48  
-  Accept-Language: fr
49  
-</PRE>
50  
-
51  
-<P>
52  
-Note that this preference will only be applied when there is a choice
53  
-of representations and they vary by language.
54  
-<P>
55  
-
56  
-As an example of a more complex request, this browser has been
57  
-configured to accept French and English, but prefer French, and to
58  
-accept various media types, preferring HTML over plain text or other
59  
-text types, and preferring GIF or JPEG over other media types, but also
60  
-allowing any other media type as a last resort:
61  
-
62  
-<PRE>
63  
-  Accept-Language: fr; q=1.0, en; q=0.5
64  
-  Accept: text/html; q=1.0, text/*; q=0.8, image/gif; q=0.6,
65  
-        image/jpeg; q=0.6, image/*; q=0.5, */*; q=0.1
66  
-</PRE>
67  
-
68  
-Apache 1.2 supports 'server driven' content negotiation, as defined in
69  
-the HTTP/1.1 specification. It fully supports the Accept,
70  
-Accept-Language, Accept-Charset and Accept-Encoding request headers.
71  
-<P>
72  
-
73  
-The terms used in content negotiation are: a <STRONG>resource</STRONG> is an
74  
-item which can be requested of a server, which might be selected as
75  
-the result of a content negotiation algorithm. If a resource is
76  
-available in several formats, these are called <STRONG>representations</STRONG>
77  
-or <STRONG>variants</STRONG>. The ways in which the variants for a particular
78  
-resource vary are called the <STRONG>dimensions</STRONG> of negotiation.
79  
-
80  
-<H2>Negotiation in Apache</H2>
81  
-
82  
-<P>
83  
-In order to negotiate a resource, the server needs to be given
84  
-information about each of the variants. This is done in one of two
85  
-ways:
86  
-
87  
-<UL>
88  
-  <LI> Using a type map (i.e., a <CODE>*.var</CODE> file) which
89  
-       names the files containing the variants explicitly
90  
-  <LI> Or using a 'MultiViews' search, where the server does an implicit
91  
-       filename pattern match, and chooses from among the results.
92  
-</UL>
93  
-
94  
-<H3>Using a type-map file</H3>
95  
-
96  
-<P>
97  
-A type map is a document which is associated with the handler
98  
-named <CODE>type-map</CODE> (or, for backwards-compatibility with
99  
-older Apache configurations, the mime type
100  
-<CODE>application/x-type-map</CODE>).  Note that to use this feature,
101  
-you've got to have a <CODE>SetHandler</CODE> some place which defines a
102  
-file suffix as <CODE>type-map</CODE>; this is best done with a
103  
-<PRE>
104  
-
105  
-  AddHandler type-map var
106  
-
107  
-</PRE>
108  
-in <CODE>srm.conf</CODE>.  See comments in the sample config files for
109  
-details. <P>
110  
-
111  
-Type map files have an entry for each available variant; these entries
112  
-consist of contiguous RFC822-format header lines.  Entries for
113  
-different variants are separated by blank lines.  Blank lines are
114  
-illegal within an entry.  It is conventional to begin a map file with
115  
-an entry for the combined entity as a whole (although this
116  
-is not required, and if present will be ignored). An example
117  
-map file is:
118  
-<PRE>
119  
-
120  
-  URI: foo
121  
-
122  
-  URI: foo.en.html
123  
-  Content-type: text/html
124  
-  Content-language: en
125  
-
126  
-  URI: foo.fr.de.html
127  
-  Content-type: text/html; charset=iso-8859-2
128  
-  Content-language: fr, de
129  
-</PRE>
130  
-
131  
-If the variants have different source qualities, that may be indicated
132  
-by the "qs" parameter to the media type, as in this picture (available
133  
-as jpeg, gif, or ASCII-art):
134  
-<PRE>
135  
-  URI: foo
136  
-
137  
-  URI: foo.jpeg
138  
-  Content-type: image/jpeg; qs=0.8
139  
-
140  
-  URI: foo.gif
141  
-  Content-type: image/gif; qs=0.5
142  
-
143  
-  URI: foo.txt
144  
-  Content-type: text/plain; qs=0.01
145  
-
146  
-</PRE>
147  
-<P>
148  
-
149  
-qs values can vary between 0.000 and 1.000. Note that any variant with
150  
-a qs value of 0.000 will never be chosen. Variants with no 'qs'
151  
-parameter value are given a qs factor of 1.0.  <P>
152  
-
153  
-The full list of headers recognized is:
154  
-
155  
-<DL>
156  
-  <DT> <CODE>URI:</CODE>
157  
-  <DD> uri of the file containing the variant (of the given media
158  
-       type, encoded with the given content encoding).  These are
159  
-       interpreted as URLs relative to the map file; they must be on
160  
-       the same server (!), and they must refer to files to which the
161  
-       client would be granted access if they were to be requested
162  
-       directly.
163  
-  <DT> <CODE>Content-type:</CODE>
164  
-  <DD> media type --- charset, level and "qs" parameters may be given.  These
165  
-       are often referred to as MIME types; typical media types are
166  
-       <CODE>image/gif</CODE>, <CODE>text/plain</CODE>, or
167  
-       <CODE>text/html;&nbsp;level=3</CODE>.
168  
-  <DT> <CODE>Content-language:</CODE>
169  
-  <DD> The languages of the variant, specified as an Internet standard
170  
-       language code (e.g., <CODE>en</CODE> for English,
171  
-       <CODE>kr</CODE> for Korean, etc.).
172  
-  <DT> <CODE>Content-encoding:</CODE>
173  
-  <DD> If the file is compressed, or otherwise encoded, rather than
174  
-       containing the actual raw data, this says how that was done.
175  
-       For compressed files (the only case where this generally comes
176  
-       up), content encoding should be
177  
-       <CODE>x-compress</CODE>, or <CODE>x-gzip</CODE>, as appropriate.
178  
-  <DT> <CODE>Content-length:</CODE>
179  
-  <DD> The size of the file.  Clients can ask to receive a given media
180  
-       type only if the variant isn't too big; specifying a content
181  
-       length in the map allows the server to compare against these
182  
-       thresholds without checking the actual file.
183  
-</DL>
184  
-
185  
-<H3>Multiviews</H3>
186  
-
187  
-<P>
188  
-This is a per-directory option, meaning it can be set with an
189  
-<CODE>Options</CODE> directive within a <CODE>&lt;Directory&gt;</CODE>,
190  
-<CODE>&lt;Location&gt;</CODE> or <CODE>&lt;Files&gt;</CODE>
191  
-section in <CODE>access.conf</CODE>, or (if <CODE>AllowOverride</CODE>
192  
-is properly set) in <CODE>.htaccess</CODE> files.  Note that
193  
-<CODE>Options All</CODE> does not set <CODE>MultiViews</CODE>; you
194  
-have to ask for it by name.  (Fixing this is a one-line change to
195  
-<CODE>http_core.h</CODE>).
196  
-
197  
-<P>
198  
-
199  
-The effect of <CODE>MultiViews</CODE> is as follows: if the server
200  
-receives a request for <CODE>/some/dir/foo</CODE>, if
201  
-<CODE>/some/dir</CODE> has <CODE>MultiViews</CODE> enabled, and
202  
-<CODE>/some/dir/foo</CODE> does <EM>not</EM> exist, then the server reads the
203  
-directory looking for files named foo.*, and effectively fakes up a
204  
-type map which names all those files, assigning them the same media
205  
-types and content-encodings it would have if the client had asked for
206  
-one of them by name.  It then chooses the best match to the client's
207  
-requirements, and forwards them along.
208  
-
209  
-<P>
210  
-
211  
-This applies to searches for the file named by the
212  
-<CODE>DirectoryIndex</CODE> directive, if the server is trying to
213  
-index a directory; if the configuration files specify
214  
-<PRE>
215  
-
216  
-  DirectoryIndex index
217  
-
218  
-</PRE> then the server will arbitrate between <CODE>index.html</CODE>
219  
-and <CODE>index.html3</CODE> if both are present.  If neither are
220  
-present, and <CODE>index.cgi</CODE> is there, the server will run it.
221  
-
222  
-<P>
223  
-
224  
-If one of the files found when reading the directive is a CGI script,
225  
-it's not obvious what should happen.  The code gives that case
226  
-special treatment --- if the request was a POST, or a GET with
227  
-QUERY_ARGS or PATH_INFO, the script is given an extremely high quality
228  
-rating, and generally invoked; otherwise it is given an extremely low
229  
-quality rating, which generally causes one of the other views (if any)
230  
-to be retrieved.
231  
-
232  
-<H2>The Negotiation Algorithm</H2>
233  
-
234  
-After Apache has obtained a list of the variants for a given resource,
235  
-either from a type-map file or from the filenames in the directory, it
236  
-applies a algorithm to decide on the 'best' variant to return, if
237  
-any. To do this it calculates a quality value for each variant in each
238  
-of the dimensions of variance. It is not necessary to know any of the
239  
-details of how negotiation actually takes place in order to use Apache's
240  
-content negotiation features. However the rest of this document
241  
-explains in detail the algorithm used for those interested.  <P>
242  
-
243  
-In some circumstances, Apache can 'fiddle' the quality factor of a
244  
-particular dimension to achieve a better result. The ways Apache can
245  
-fiddle quality factors is explained in more detail below.
246  
-
247  
-<H3>Dimensions of Negotiation</H3>
248  
-
249  
-<TABLE>
250  
-<TR><TH>Dimension
251  
-<TH>Notes
252  
-<TR><TD>Media Type
253  
-<TD>Browser indicates preferences on Accept: header. Each item
254  
-can have an associated quality factor. Variant description can also
255  
-have a quality factor.
256  
-<TR><TD>Language
257  
-<TD>Browser indicates preferences on Accept-Language: header. Each
258  
-item
259  
-can have a quality factor. Variants can be associated with none, one
260  
-or more languages.
261  
-<TR><TD>Encoding
262  
-<TD>Browser indicates preference with Accept-Encoding: header.
263  
-<TR><TD>Charset
264  
-<TD>Browser indicates preference with Accept-Charset: header. Variants
265  
-can indicate a charset as a parameter of the media type.
266  
-</TABLE>
267  
-
268  
-<H3>Apache Negotiation Algorithm</H3>
269  
-
270  
-<P>
271  
-Apache uses an algorithm to select the 'best' variant (if any) to
272  
-return to the browser. This algorithm is not configurable. It operates
273  
-like this:
274  
-
275  
-<OL>
276  
-<LI>
277  
-Firstly, for each dimension of the negotiation, the appropriate
278  
-Accept header is checked and a quality assigned to this each
279  
-variant. If the Accept header for any dimension means that this
280  
-variant is not acceptable, eliminate it. If no variants remain, go
281  
-to step 4.
282  
-
283  
-<LI>Select the 'best' variant by a process of elimination. Each of
284  
-the following tests is applied in order. Any variants not selected at
285  
-each stage are eliminated. After each test, if only one variant
286  
-remains, it is selected as the best match. If more than one variant
287  
-remains, move onto the next test.
288  
-
289  
-<OL>
290  
-<LI>Multiply the quality factor from the Accept header with the
291  
-  quality-of-source factor for this variant's media type, and select
292  
-  the variants with the highest value
293  
-
294  
-<LI>Select the variants with the highest language quality factor
295  
-
296  
-<LI>Select the variants with the best language match, using either the
297  
-  order of languages on the <CODE>LanguagePriority</CODE> directive (if present),
298  
-  else the order of languages on the Accept-Language header.
299  
-
300  
-<LI>Select the variants with the highest 'level' media parameter
301  
-  (used to give the version of text/html media types).
302  
-
303  
-<LI>Select only unencoded variants, if there is a mix of encoded
304  
-  and non-encoded variants. If either all variants are encoded
305  
-  or all variants are not encoded, select all.
306  
-
307  
-<LI>Select only variants with acceptable charset media parameters,
308  
-  as given on the Accept-Charset header line. Charset ISO-8859-1
309  
-  is always acceptable. Variants not associated with a particular
310  
-  charset are assumed to be in ISO-8859-1.
311  
-
312  
-<LI>Select the variants with the smallest content length
313  
-
314  
-<LI>Select the first variant of those remaining (this will be either the
315  
-first listed in the type-map file, or the first read from the directory)
316  
-and go to stage 3.
317  
-
318  
-</OL>
319  
-
320  
-<LI>The algorithm has now selected one 'best' variant, so return
321  
-  it as the response. The HTTP response header Vary is set to indicate the
322  
-  dimensions of negotiation (browsers and caches can use this
323  
-  information when caching the resource). End.
324  
-
325  
-<LI>To get here means no variant was selected (because non are acceptable
326  
-  to the browser). Return a 406 status (meaning "No acceptable representation")
327  
-  with a response body consisting of an HTML document listing the
328  
-  available variants. Also set the HTTP Vary header to indicate the
329  
-  dimensions of variance.
330  
-
331  
-</OL>
332  
-
333  
-<H2><A name="better">Fiddling with Quality Values</A></H2>
334  
-
335  
-<P>
336  
-Apache sometimes changes the quality values from what would be
337  
-expected by a strict interpretation of the algorithm above. This is to
338  
-get a better result from the algorithm for browsers which do not send
339  
-full or accurate information. Some of the most popular browsers send
340  
-Accept header information which would otherwise result in the
341  
-selection of the wrong variant in many cases. If a browser
342  
-sends full and correct information these fiddles will not
343  
-be applied.
344  
-<P>
345  
-
346  
-<H3>Media Types and Wildcards</H3>
347  
-
348  
-<P>
349  
-The Accept: request header indicates preferences for media types. It
350  
-can also include 'wildcard' media types, such as "image/*" or "*/*"
351  
-where the * matches any string. So a request including:
352  
-<PRE>
353  
-  Accept: image/*, */*
354  
-</PRE>
355  
-
356  
-would indicate that any type starting "image/" is acceptable,
357  
-as is any other type (so the first "image/*" is redundant). Some
358  
-browsers routinely send wildcards in addition to explicit types they
359  
-can handle. For example:
360  
-<PRE>
361  
-  Accept: text/html, text/plain, image/gif, image/jpeg, */*
362  
-</PRE>
363  
-
364  
-The intention of this is to indicate that the explicitly
365  
-listed types are preferred, but if a different representation is
366  
-available, that is ok too. However under the basic algorithm, as given
367  
-above, the */* wildcard has exactly equal preference to all the other
368  
-types, so they are not being preferred. The browser should really have
369  
-sent a request with a lower quality (preference) value for *.*, such
370  
-as:
371  
-<PRE>
372  
-  Accept: text/html, text/plain, image/gif, image/jpeg, */*; q=0.01
373  
-</PRE>
374  
-
375  
-The explicit types have no quality factor, so they default to a
376  
-preference of 1.0 (the highest). The wildcard */* is given
377  
-a low preference of 0.01, so other types will only be returned if
378  
-no variant matches an explicitly listed type.
379  
-<P>
380  
-
381  
-If the Accept: header contains <EM>no</EM> q factors at all, Apache sets
382  
-the q value of "*/*", if present, to 0.01 to emulate the desired
383  
-behavior. It also sets the q value of wildcards of the format
384  
-"type/*" to 0.02 (so these are preferred over matches against
385  
-"*/*". If any media type on the Accept: header contains a q factor,
386  
-these special values are <EM>not</EM> applied, so requests from browsers
387  
-which send the correct information to start with work as expected.
388  
-
389  
-<H3>Variants with no Language</H3>
390  
-
391  
-<P>
392  
-If some of the variants for a particular resource have a language
393  
-attribute, and some do not, those variants with no language
394  
-are given a very low language quality factor of 0.001.<P>
395  
-
396  
-The reason for setting this language quality factor for
397  
-variant with no language to a very low value is to allow
398  
-for a default variant which can be supplied if none of the
399  
-other variants match the browser's language preferences.
400  
-
401  
-For example, consider the situation with three variants:
402  
-
403  
-<UL>
404  
-<LI>foo.en.html, language en
405  
-<LI>foo.fr.html, language en
406  
-<LI>foo.html, no language
407  
-</UL>
408  
-
409  
-<P>
410  
-The meaning of a variant with no language is that it is
411  
-always acceptable to the browser. If the request Accept-Language
412  
-header includes either en or fr (or both) one of foo.en.html
413  
-or foo.fr.html will be returned. If the browser does not list
414  
-either en or fr as acceptable, foo.html will be returned instead.
415  
-
416  
-<H2>Note on hyperlinks and naming conventions</H2>
417  
-
418  
-<P>
419  
-If you are using language negotiation you can choose between
420  
-different naming conventions, because files can have more than one
421  
-extension, and the order of the extensions is normally irrelevant
422  
-(see <A HREF="mod/mod_mime.html">mod_mime</A> documentation for details).
423  
-<P>
424  
-A typical file has a mime-type extension (e.g. <SAMP>html</SAMP>),
425  
-maybe an encoding extension (e.g. <SAMP>gz</SAMP> and of course a
426  
-language extension (e.g. <SAMP>en</SAMP>) when we have different
427  
-language variants of this file.
428  
-
429  
-<P>
430  
-Examples:
431  
-<UL>
432  
-<LI>foo.en.html
433  
-<LI>foo.html.en
434  
-<LI>foo.en.html.gz
435  
-</UL>
436  
-
437  
-<P>
438  
-Here some more examples of filenames together with valid and invalid hyperlinks:
439  
-</P>
440  
-
441  
-<table border=1 cellpadding=8 cellspacing=0>
442  
-<TR>
443  
- <TH>Filename</TH>
444  
- <TH>Valid hyperlink</TH>
445  
- <TH>Invalid hyperlink</TH>
446  
-</TR>
447  
-<TR>
448  
- <TD><EM>foo.html.en</EM></TD>
449  
- <TD>foo<BR>
450  
-     foo.html</TD>
451  
- <TD>-</TD>
452  
-</TR>
453  
-<TR>
454  
- <TD><EM>foo.en.html</EM></TD>
455  
- <TD>foo</TD>
456  
- <TD>foo.html</TD>
457  
-</TR>
458  
-<TR>
459  
- <TD><EM>foo.html.en.gz</EM></TD>
460  
- <TD>foo<BR>
461  
-     foo.html</TD>
462  
- <TD>foo.gz<BR>
463  
-     foo.html.gz</TD>
464  
-</TR>
465  
-<TR>
466  
- <TD><EM>foo.en.html.gz</EM></TD>
467  
- <TD>foo</TD>
468  
- <TD>foo.html<BR>
469  
-     foo.html.gz<BR>
470  
-     foo.gz</TD>
471  
-</TR>
472  
-<TR>
473  
- <TD><EM>foo.gz.html.en</EM></TD>
474  
- <TD>foo<BR>
475  
-     foo.gz<BR>
476  
-     foo.gz.html</TD>
477  
- <TD>foo.html</TD>
478  
-</TR>
479  
-<TR>
480  
- <TD><EM>foo.html.gz.en</EM></TD>
481  
- <TD>foo<BR>
482  
-     foo.html<BR>
483  
-     foo.html.gz</TD>
484  
- <TD>foo.gz</TD>
485  
-</TR>
486  
-</TABLE>
487  
-
488  
-<P>
489  
-Looking at the table above you will notice that it is always possible to
490  
-use the name without any extensions  in an hyperlink (e.g. <SAMP>foo</SAMP>).
491  
-The advantage is that you can hide the actual type of a
492  
-document rsp. file and can change it later, e.g. from <SAMP>html</SAMP>
493  
-to <SAMP>shtml</SAMP> or <SAMP>cgi</SAMP> without changing any
494  
-hyperlink references.
495  
-
496  
-<P>
497  
-If you want to continue to use a mime-type in your hyperlinks (e.g.
498  
-<SAMP>foo.html</SAMP>) the language extension (including an encoding extension
499  
-if there is one) must be on the right hand side of the mime-type extension
500  
-(e.g. <SAMP>foo.html.en</SAMP>).
501  
-
502  
-
503  
-<H2>Note on Caching</H2>
504  
-
505  
-<P>
506  
-When a cache stores a document, it associates it with the request URL.
507  
-The next time that URL is requested, the cache can use the stored
508  
-document, provided it is still within date. But if the resource is
509  
-subject to content negotiation at the server, this would result in
510  
-only the first requested variant being cached, and subsequent cache
511  
-hits could return the wrong response. To prevent this,
512  
-Apache normally marks all responses that are returned after content negotiation
513  
-as non-cacheable by HTTP/1.0 clients. Apache also supports the HTTP/1.1
514  
-protocol features to allow caching of negotiated responses. <P>
515  
-
516  
-For requests which come from a HTTP/1.0 compliant client (either a
517  
-browser or a cache), the directive <TT>CacheNegotiatedDocs</TT> can be
518  
-used to allow caching of responses which were subject to negotiation.
519  
-This directive can be given in the server config or virtual host, and
520  
-takes no arguments. It has no effect on requests from HTTP/1.1
521  
-clients.
522  
-
523  
-<!--#include virtual="footer.html" -->
524  
-</BODY>
525  
-</HTML>
152  docs/manual/custom-error.html.en
... ...
@@ -1,152 +0,0 @@
1  
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2  
-<HTML>
3  
-<HEAD>
4  
-<TITLE>Custom error responses</TITLE>
5  
-</HEAD>
6  
-
7  
-<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
8  
-<BODY
9  
- BGCOLOR="#FFFFFF"
10  
- TEXT="#000000"
11  
- LINK="#0000FF"
12  
- VLINK="#000080"
13  
- ALINK="#FF0000"
14  
->
15  
-<!--#include virtual="header.html" -->
16  
-<H1 ALIGN="CENTER">Custom error responses</H1>
17  
-
18  
-<DL>
19  
-
20  
-<DT>Purpose
21  
-
22  
-  <DD>Additional functionality. Allows webmasters to configure the response of
23  
-      Apache to some error or problem.
24  
-
25  
-      <P>Customizable responses can be defined to be activated in the
26  
-      event of a server detected error or problem.
27  
-
28  
-      <P>e.g. if a script crashes and produces a "500 Server Error"
29  
-      response, then this response can be replaced with either some
30  
-      friendlier text or by a redirection to another URL (local or
31  
-      external).
32  
-      <P>
33  
-
34  
-<DT>Old behavior
35  
-
36  
-  <DD>NCSA httpd 1.3 would return some boring old error/problem message
37  
-      which would often be meaningless to the user, and would provide no
38  
-      means of logging the symptoms which caused it.<BR>
39  
-
40  
-      <P>
41  
-
42  
-<DT>New behavior
43  
-
44  
-  <DD>The server can be asked to;
45  
-  <OL>
46  
-    <LI>Display some other text, instead of the NCSA hard coded messages, or
47  
-    <LI>redirect to a local URL, or
48  
-    <LI>redirect to an external URL.
49  
-  </OL>
50  
-
51  
-  <P>Redirecting to another URL can be useful, but only if some information
52  
-     can be passed which can then be used to explain and/or log the error/problem
53  
-     more clearly.
54  
-
55  
-  <P>To achieve this, Apache will define new CGI-like environment
56  
-     variables, e.g.
57  
-
58  
-  <BLOCKQUOTE><CODE>
59  
-REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/x-xbitmap, image/jpeg <BR>
60  
-REDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2 (X11; I; HP-UX A.09.05 9000/712) <BR>
61  
-REDIRECT_PATH=.:/bin:/usr/local/bin:/etc <BR>
62  
-REDIRECT_QUERY_STRING= <BR>
63  
-REDIRECT_REMOTE_ADDR=121.345.78.123 <BR>
64  
-REDIRECT_REMOTE_HOST=ooh.ahhh.com <BR>
65  
-REDIRECT_SERVER_NAME=crash.bang.edu <BR>
66  
-REDIRECT_SERVER_PORT=80 <BR>
67  
-REDIRECT_SERVER_SOFTWARE=Apache/0.8.15 <BR>
68  
-REDIRECT_URL=/cgi-bin/buggy.pl <BR>
69  
-  </CODE></BLOCKQUOTE>
70  
-
71  
-  <P>note the <CODE>REDIRECT_</CODE> prefix.
72  
-
73  
-  <P>At least <CODE>REDIRECT_URL</CODE> and <CODE>REDIRECT_QUERY_STRING</CODE> will
74  
-     be passed to the new URL (assuming it's a cgi-script or a cgi-include). The
75  
-     other variables will exist only if they existed prior to the error/problem.
76  
-     <STRONG>None</STRONG> of these will be set if your ErrorDocument is an
77  
-     <EM>external</EM> redirect (i.e. anything starting with a protocol name
78  
-     like <CODE>http:</CODE>, even if it refers to the same host as the
79  
-     server).<P>
80  
-
81  
-<DT>Configuration
82  
-
83  
-  <DD> Use of "ErrorDocument" is enabled for .htaccess files when the
84  
-       <A HREF="mod/core.html#allowoverride">"FileInfo" override</A> is allowed.
85  
-
86  
-  <P>Here are some examples...
87  
-
88  
-  <BLOCKQUOTE><CODE>
89  
-ErrorDocument 500 /cgi-bin/crash-recover <BR>
90  
-ErrorDocument 500 "Sorry, our script crashed. Oh dear<BR>
91  
-ErrorDocument 500 http://xxx/ <BR>
92  
-ErrorDocument 404 /Lame_excuses/not_found.html  <BR>
93  
-ErrorDocument 401 /Subscription/how_to_subscribe.html
94  
-  </CODE></BLOCKQUOTE>
95  
-
96  
-  <P>The syntax is,
97  
-
98  
-  <P><CODE><A HREF="mod/core.html#errordocument">ErrorDocument</A></CODE>
99  
-&lt;3-digit-code&gt; action
100  
-
101  
-  <P>where the action can be,
102  
-
103  
-  <OL>
104  
-    <LI>Text to be displayed.  Prefix the text with a quote (&quot;). Whatever
105  
-        follows the quote is displayed. <EM>Note: the (&quot;) prefix isn't
106  
-        displayed.</EM>
107  
-
108  
-    <LI>An external URL to redirect to.
109  
-
110  
-    <LI>A local URL to redirect to.
111  
-
112  
-  </OL>
113  
-</DL>
114  
-
115  
-<P><HR><P>
116  
-
117  
-<H2>Custom error responses and redirects</H2>
118  
-
119  
-<DL>
120  
-
121  
-<DT>Purpose
122  
-
123  
-  <DD>Apache's behavior to redirected URLs has been modified so that additional
124  
-      environment variables are available to a script/server-include.<P>
125  
-
126  
-<DT>Old behavior
127  
-
128  
-  <DD>Standard CGI vars were made available to a script which has been
129  
-      redirected to. No indication of where the redirection came from was provided.
130  
-
131  
-  <P>
132  
-
133  
-<DT>New behavior
134  
-  <DD>
135  
-
136  
-A new batch of environment variables will be initialized for use by a
137  
-script which has been redirected to.  Each new variable will have the
138  
-prefix <CODE>REDIRECT_</CODE>.  <CODE>REDIRECT_</CODE> environment
139  
-variables are created from the CGI environment variables which existed
140  
-prior to the redirect, they are renamed with a <CODE>REDIRECT_</CODE>
141  
-prefix, i.e. <CODE>HTTP_USER_AGENT</CODE> becomes
142  
-<CODE>REDIRECT_HTTP_USER_AGENT</CODE>.  In addition to these new
143  
-variables, Apache will define <CODE>REDIRECT_URL</CODE> and
144  
-<CODE>REDIRECT_STATUS</CODE> to help the script trace its origin.
145  
-Both the original URL and the URL being redirected to can be logged in
146  
-the access log.
147  
-
148  
-</DL>
149  
-
150  
-<!--#include virtual="footer.html" -->
151  
-</BODY>
152  
-</HTML>
1,004  docs/manual/developer/API.html
... ...
@@ -1,1004 +0,0 @@
1  
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2  
-<HTML><HEAD>
3  
-<TITLE>Apache API notes</TITLE>
4  
-</HEAD>
5  
-<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
6  
-<BODY
7  
- BGCOLOR="#FFFFFF"
8  
- TEXT="#000000"
9  
- LINK="#0000FF"
10  
- VLINK="#000080"
11  
- ALINK="#FF0000"
12  
->
13  
-<!--#include virtual="header.html" -->
14  
-<H1 ALIGN="CENTER">Apache API notes</H1>
15  
-
16  
-These are some notes on the Apache API and the data structures you
17  
-have to deal with, etc.  They are not yet nearly complete, but
18  
-hopefully, they will help you get your bearings.  Keep in mind that
19  
-the API is still subject to change as we gain experience with it.
20  
-(See the TODO file for what <EM>might</EM> be coming).  However,
21  
-it will be easy to adapt modules to any changes that are made.
22  
-(We have more modules to adapt than you do).
23  
-<P>
24  
-
25  
-A few notes on general pedagogical style here.  In the interest of
26  
-conciseness, all structure declarations here are incomplete --- the
27  
-real ones have more slots that I'm not telling you about.  For the
28  
-most part, these are reserved to one component of the server core or
29  
-another, and should be altered by modules with caution.  However, in
30  
-some cases, they really are things I just haven't gotten around to
31  
-yet.  Welcome to the bleeding edge.<P>
32  
-
33  
-Finally, here's an outline, to give you some bare idea of what's
34  
-coming up, and in what order:
35  
-
36  
-<UL>
37  
-<LI> <A HREF="#basics">Basic concepts.</A>
38  
-<MENU>
39  
- <LI> <A HREF="#HMR">Handlers, Modules, and Requests</A>
40  
- <LI> <A HREF="#moduletour">A brief tour of a module</A>
41  
-</MENU>
42  
-<LI> <A HREF="#handlers">How handlers work</A>
43  
-<MENU>
44  
- <LI> <A HREF="#req_tour">A brief tour of the <CODE>request_rec</CODE></A>
45  
- <LI> <A HREF="#req_orig">Where request_rec structures come from</A>
46  
- <LI> <A HREF="#req_return">Handling requests, declining, and returning error codes</A>
47  
- <LI> <A HREF="#resp_handlers">Special considerations for response handlers</A>
48  
- <LI> <A HREF="#auth_handlers">Special considerations for authentication handlers</A>
49  
- <LI> <A HREF="#log_handlers">Special considerations for logging handlers</A>
50  
-</MENU>
51  
-<LI> <A HREF="#pools">Resource allocation and resource pools</A>
52  
-<LI> <A HREF="#config">Configuration, commands and the like</A>
53  
-<MENU>
54  
- <LI> <A HREF="#per-dir">Per-directory configuration structures</A>
55  
- <LI> <A HREF="#commands">Command handling</A>
56  
- <LI> <A HREF="#servconf">Side notes --- per-server configuration, virtual servers, etc.</A>
57  
-</MENU>
58  
-</UL>
59  
-
60  
-<H2><A name="basics">Basic concepts.</A></H2>
61  
-
62  
-We begin with an overview of the basic concepts behind the
63  
-API, and how they are manifested in the code.
64  
-
65  
-<H3><A name="HMR">Handlers, Modules, and Requests</A></H3>
66  
-
67  
-Apache breaks down request handling into a series of steps, more or
68  
-less the same way the Netscape server API does (although this API has
69  
-a few more stages than NetSite does, as hooks for stuff I thought
70  
-might be useful in the future).  These are:
71  
-
72  
-<UL>
73  
-  <LI> URI -&gt; Filename translation
74  
-  <LI> Auth ID checking [is the user who they say they are?]
75  
-  <LI> Auth access checking [is the user authorized <EM>here</EM>?]
76  
-  <LI> Access checking other than auth
77  
-  <LI> Determining MIME type of the object requested
78  
-  <LI> `Fixups' --- there aren't any of these yet, but the phase is
79  
-       intended as a hook for possible extensions like
80  
-       <CODE>SetEnv</CODE>, which don't really fit well elsewhere.
81  
-  <LI> Actually sending a response back to the client.
82  
-  <LI> Logging the request
83  
-</UL>
84  
-
85  
-These phases are handled by looking at each of a succession of
86  
-<EM>modules</EM>, looking to see if each of them has a handler for the
87  
-phase, and attempting invoking it if so.  The handler can typically do
88  
-one of three things:
89  
-
90  
-<UL>
91  
-  <LI> <EM>Handle</EM> the request, and indicate that it has done so
92  
-       by returning the magic constant <CODE>OK</CODE>.
93  
-  <LI> <EM>Decline</EM> to handle the request, by returning the magic
94  
-       integer constant <CODE>DECLINED</CODE>.  In this case, the
95  
-       server behaves in all respects as if the handler simply hadn't
96  
-       been there.
97  
-  <LI> Signal an error, by returning one of the HTTP error codes.
98  
-       This terminates normal handling of the request, although an
99  
-       ErrorDocument may be invoked to try to mop up, and it will be
100  
-       logged in any case.
101  
-</UL>
102  
-
103  
-Most phases are terminated by the first module that handles them;
104  
-however, for logging, `fixups', and non-access authentication
105  
-checking, all handlers always run (barring an error).  Also, the
106  
-response phase is unique in that modules may declare multiple handlers
107  
-for it, via a dispatch table keyed on the MIME type of the requested
108  
-object.  Modules may declare a response-phase handler which can handle
109  
-<EM>any</EM> request, by giving it the key <CODE>*/*</CODE> (i.e., a
110  
-wildcard MIME type specification).  However, wildcard handlers are
111  
-only invoked if the server has already tried and failed to find a more
112  
-specific response handler for the MIME type of the requested object
113  
-(either none existed, or they all declined).<P>
114  
-
115  
-The handlers themselves are functions of one argument (a
116  
-<CODE>request_rec</CODE> structure. vide infra), which returns an
117  
-integer, as above.<P>
118  
-
119  
-<H3><A name="moduletour">A brief tour of a module</A></H3>
120  
-
121  
-At this point, we need to explain the structure of a module.  Our
122  
-candidate will be one of the messier ones, the CGI module --- this
123  
-handles both CGI scripts and the <CODE>ScriptAlias</CODE> config file
124  
-command.  It's actually a great deal more complicated than most
125  
-modules, but if we're going to have only one example, it might as well
126  
-be the one with its fingers in every place.<P>
127  
-
128  
-Let's begin with handlers.  In order to handle the CGI scripts, the
129  
-module declares a response handler for them. Because of
130  
-<CODE>ScriptAlias</CODE>, it also has handlers for the name
131  
-translation phase (to recognize <CODE>ScriptAlias</CODE>ed URIs), the
132  
-type-checking phase (any <CODE>ScriptAlias</CODE>ed request is typed
133  
-as a CGI script).<P>
134  
-
135  
-The module needs to maintain some per (virtual)
136  
-server information, namely, the <CODE>ScriptAlias</CODE>es in effect;
137  
-the module structure therefore contains pointers to a functions which
138  
-builds these structures, and to another which combines two of them (in
139  
-case the main server and a virtual server both have
140  
-<CODE>ScriptAlias</CODE>es declared).<P>
141  
-
142  
-Finally, this module contains code to handle the
143  
-<CODE>ScriptAlias</CODE> command itself.  This particular module only
144  
-declares one command, but there could be more, so modules have
145  
-<EM>command tables</EM> which declare their commands, and describe
146  
-where they are permitted, and how they are to be invoked.  <P>
147  
-
148  
-A final note on the declared types of the arguments of some of these
149  
-commands: a <CODE>pool</CODE> is a pointer to a <EM>resource pool</EM>
150  
-structure; these are used by the server to keep track of the memory
151  
-which has been allocated, files opened, etc., either to service a
152  
-particular request, or to handle the process of configuring itself.
153  
-That way, when the request is over (or, for the configuration pool,
154  
-when the server is restarting), the memory can be freed, and the files
155  
-closed, <EM>en masse</EM>, without anyone having to write explicit code to
156  
-track them all down and dispose of them.  Also, a
157  
-<CODE>cmd_parms</CODE> structure contains various information about
158  
-the config file being read, and other status information, which is
159  
-sometimes of use to the function which processes a config-file command
160  
-(such as <CODE>ScriptAlias</CODE>).
161  
-
162  
-With no further ado, the module itself:
163  
-
164  
-<PRE>
165  
-/* Declarations of handlers. */
166  
-
167  
-int translate_scriptalias (request_rec *);
168  
-int type_scriptalias (request_rec *);
169  
-int cgi_handler (request_rec *);
170  
-
171  
-/* Subsidiary dispatch table for response-phase handlers, by MIME type */
172  
-
173  
-handler_rec cgi_handlers[] = {
174  
-{ "application/x-httpd-cgi", cgi_handler },
175  
-{ NULL }
176  
-};
177  
-
178  
-/* Declarations of routines to manipulate the module's configuration
179  
- * info.  Note that these are returned, and passed in, as void *'s;
180  
- * the server core keeps track of them, but it doesn't, and can't,
181  
- * know their internal structure.
182  
- */
183  
-
184  
-void *make_cgi_server_config (pool *);
185  
-void *merge_cgi_server_config (pool *, void *, void *);
186  
-
187  
-/* Declarations of routines to handle config-file commands */
188  
-
189  
-extern char *script_alias(cmd_parms *, void *per_dir_config, char *fake,
190  
-                          char *real);
191  
-
192  
-command_rec cgi_cmds[] = {
193  
-{ "ScriptAlias", script_alias, NULL, RSRC_CONF, TAKE2,
194  
-    "a fakename and a realname"},
195  
-{ NULL }
196  
-};
197  
-
198  
-module cgi_module = {
199  
-   STANDARD_MODULE_STUFF,
200  
-   NULL,                     /* initializer */
201  
-   NULL,                     /* dir config creator */
202  
-   NULL,                     /* dir merger --- default is to override */
203  
-   make_cgi_server_config,   /* server config */
204  
-   merge_cgi_server_config,  /* merge server config */
205  
-   cgi_cmds,                 /* command table */
206  
-   cgi_handlers,             /* handlers */
207  
-   translate_scriptalias,    /* filename translation */
208  
-   NULL,                     /* check_user_id */
209  
-   NULL,                     /* check auth */
210  
-   NULL,                     /* check access */
211  
-   type_scriptalias,         /* type_checker */
212  
-   NULL,                     /* fixups */
213  
-   NULL,                     /* logger */
214  
-   NULL                      /* header parser */
215  
-};
216  
-</PRE>
217  
-