diff options
| author | André Malo <nd@apache.org> | 2003-05-03 02:12:37 +0200 |
|---|---|---|
| committer | André Malo <nd@apache.org> | 2003-05-03 02:12:37 +0200 |
| commit | a26af67e7a1132465275428ff5ef0d0c3fdf79d2 (patch) | |
| tree | d2459f8ae03877ce33a6fbc92038a0c915a1b331 | |
| parent | Throw a warning if AllowOverride is used inside of <Location> or <Files>. (diff) | |
| download | apache2-a26af67e7a1132465275428ff5ef0d0c3fdf79d2.tar.xz apache2-a26af67e7a1132465275428ff5ef0d0c3fdf79d2.zip | |
That was the LAST XML file.
Additional cleanup: Get a rid of all the footer/header files
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@99697 13f79535-47bb-0310-9956-ffa450edef68
| -rw-r--r-- | docs/STATUS | 18 | ||||
| -rw-r--r-- | docs/manual/developer/API.html | 1258 | ||||
| -rw-r--r-- | docs/manual/developer/API.html.en | 1221 | ||||
| -rw-r--r-- | docs/manual/developer/API.xml | 1219 | ||||
| -rw-r--r-- | docs/manual/developer/API.xml.meta | 11 | ||||
| -rw-r--r-- | docs/manual/developer/footer.html | 7 | ||||
| -rw-r--r-- | docs/manual/developer/header.html | 6 | ||||
| -rw-r--r-- | docs/manual/faq/footer.html | 6 | ||||
| -rw-r--r-- | docs/manual/faq/header.html | 7 | ||||
| -rw-r--r-- | docs/manual/footer.html | 6 | ||||
| -rw-r--r-- | docs/manual/header.html | 7 | ||||
| -rw-r--r-- | docs/manual/howto/footer.html | 7 | ||||
| -rw-r--r-- | docs/manual/howto/header.html | 6 | ||||
| -rw-r--r-- | docs/manual/mod/footer.html | 6 | ||||
| -rw-r--r-- | docs/manual/mod/header.html | 6 | ||||
| -rw-r--r-- | docs/manual/platform/footer.html | 6 | ||||
| -rw-r--r-- | docs/manual/platform/header.html | 6 | ||||
| -rw-r--r-- | docs/manual/ssl/footer.html | 7 | ||||
| -rw-r--r-- | docs/manual/ssl/header.html | 6 | ||||
| -rw-r--r-- | docs/manual/style/chm/hhc.xsl | 2 | ||||
| -rw-r--r-- | docs/manual/vhosts/footer.html | 5 | ||||
| -rw-r--r-- | docs/manual/vhosts/header.html | 7 |
22 files changed, 2453 insertions, 1377 deletions
diff --git a/docs/STATUS b/docs/STATUS index 30ba2a9e42..6ae2593b8c 100644 --- a/docs/STATUS +++ b/docs/STATUS @@ -1,5 +1,5 @@ Apache HTTP Server 2.1 Documentation Status File. -Last modified: $Date: 2003/05/02 19:10:07 $ +Last modified: $Date: 2003/05/03 00:12:35 $ For more information on how to contribute to the Apache Documentation Project, please see http://httpd.apache.org/docs-project/ @@ -53,12 +53,6 @@ Decisions pending Things That Need Fixing ======================= -- XML - - Rewriting of the remainder of the manual into xml is in - progress. See the bottom of this file for status info. - - add ids to non-directive sections of the module docs, so they - get a chance to be linked in the sidebar - - Windows platform docs are in desperate need of rewrites/updates for 2.0. - Bill Rowe and Bill Stoddard are good contacts for tech questions. - "using apache" has been done, "compiling apache" is still open @@ -177,13 +171,3 @@ Documentation improvements * Summarize all the implemented drafts/standards with short explanations within a document. (PR 16938) -XML Conversions -=============== - -The following files need to be converted to XML as described at -http://httpd.apache.org/docs-project/docsformat.html - -# Perhaps these should be left in html to allow the developers to -# play with them -# nope. in order to create other formats, we need 'em as xml. --nd -developer/API.html diff --git a/docs/manual/developer/API.html b/docs/manual/developer/API.html deleted file mode 100644 index 8ccf04e7fa..0000000000 --- a/docs/manual/developer/API.html +++ /dev/null @@ -1,1258 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> - -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <meta name="generator" content="HTML Tidy, see www.w3.org" /> - - <title>Apache API notes</title> - </head> - <!-- Background white, links blue (unvisited), navy (visited), red (active) --> - - <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" - vlink="#000080" alink="#FF0000"> - <div align="center"> - <img src="../images/sub.gif" alt="[APACHE DOCUMENTATION]" /> - - <h3>Apache HTTP Server Version 2.1</h3> - </div> - - - - <blockquote> - <strong>Warning:</strong> This document has not been updated - to take into account changes made in the 2.0 version of the - Apache HTTP Server. Some of the information may still be - relevant, but please use it with care. - </blockquote> - - <h1 align="center">Apache API notes</h1> - These are some notes on the Apache API and the data structures - you have to deal with, <em>etc.</em> They are not yet nearly - complete, but hopefully, they will help you get your bearings. - Keep in mind that the API is still subject to change as we gain - experience with it. (See the TODO file for what <em>might</em> - be coming). However, it will be easy to adapt modules to any - changes that are made. (We have more modules to adapt than you - do). - - <p>A few notes on general pedagogical style here. In the - interest of conciseness, all structure declarations here are - incomplete --- the real ones have more slots that I'm not - telling you about. For the most part, these are reserved to one - component of the server core or another, and should be altered - by modules with caution. However, in some cases, they really - are things I just haven't gotten around to yet. Welcome to the - bleeding edge.</p> - - <p>Finally, here's an outline, to give you some bare idea of - what's coming up, and in what order:</p> - - <ul> - <li> - <a href="#basics">Basic concepts.</a> - - <ul> - <li><a href="#HMR">Handlers, Modules, and - Requests</a></li> - - <li><a href="#moduletour">A brief tour of a - module</a></li> - </ul> - </li> - - <li> - <a href="#handlers">How handlers work</a> - - <ul> - <li><a href="#req_tour">A brief tour of the - <code>request_rec</code></a></li> - - <li><a href="#req_orig">Where request_rec structures come - from</a></li> - - <li><a href="#req_return">Handling requests, declining, - and returning error codes</a></li> - - <li><a href="#resp_handlers">Special considerations for - response handlers</a></li> - - <li><a href="#auth_handlers">Special considerations for - authentication handlers</a></li> - - <li><a href="#log_handlers">Special considerations for - logging handlers</a></li> - </ul> - </li> - - <li><a href="#pools">Resource allocation and resource - pools</a></li> - - <li> - <a href="#config">Configuration, commands and the like</a> - - <ul> - <li><a href="#per-dir">Per-directory configuration - structures</a></li> - - <li><a href="#commands">Command handling</a></li> - - <li><a href="#servconf">Side notes --- per-server - configuration, virtual servers, <em>etc</em>.</a></li> - </ul> - </li> - </ul> - - <h2><a id="basics" name="basics">Basic concepts.</a></h2> - We begin with an overview of the basic concepts behind the API, - and how they are manifested in the code. - - <h3><a id="HMR" name="HMR">Handlers, Modules, and - Requests</a></h3> - Apache breaks down request handling into a series of steps, - more or less the same way the Netscape server API does - (although this API has a few more stages than NetSite does, as - hooks for stuff I thought might be useful in the future). These - are: - - <ul> - <li>URI -> Filename translation</li> - - <li>Auth ID checking [is the user who they say they - are?]</li> - - <li>Auth access checking [is the user authorized - <em>here</em>?]</li> - - <li>Access checking other than auth</li> - - <li>Determining MIME type of the object requested</li> - - <li>`Fixups' --- there aren't any of these yet, but the phase - is intended as a hook for possible extensions like - <code>SetEnv</code>, which don't really fit well - elsewhere.</li> - - <li>Actually sending a response back to the client.</li> - - <li>Logging the request</li> - </ul> - These phases are handled by looking at each of a succession of - <em>modules</em>, looking to see if each of them has a handler - for the phase, and attempting invoking it if so. The handler - can typically do one of three things: - - <ul> - <li><em>Handle</em> the request, and indicate that it has - done so by returning the magic constant <code>OK</code>.</li> - - <li><em>Decline</em> to handle the request, by returning the - magic integer constant <code>DECLINED</code>. In this case, - the server behaves in all respects as if the handler simply - hadn't been there.</li> - - <li>Signal an error, by returning one of the HTTP error - codes. This terminates normal handling of the request, - although an ErrorDocument may be invoked to try to mop up, - and it will be logged in any case.</li> - </ul> - Most phases are terminated by the first module that handles - them; however, for logging, `fixups', and non-access - authentication checking, all handlers always run (barring an - error). Also, the response phase is unique in that modules may - declare multiple handlers for it, via a dispatch table keyed on - the MIME type of the requested object. Modules may declare a - response-phase handler which can handle <em>any</em> request, - by giving it the key <code>*/*</code> (<em>i.e.</em>, a - wildcard MIME type specification). However, wildcard handlers - are only invoked if the server has already tried and failed to - find a more specific response handler for the MIME type of the - requested object (either none existed, or they all declined). - - <p>The handlers themselves are functions of one argument (a - <code>request_rec</code> structure. vide infra), which returns - an integer, as above.</p> - - <h3><a id="moduletour" name="moduletour">A brief tour of a - module</a></h3> - At this point, we need to explain the structure of a module. - Our candidate will be one of the messier ones, the CGI module - --- this handles both CGI scripts and the - <code>ScriptAlias</code> config file command. It's actually a - great deal more complicated than most modules, but if we're - going to have only one example, it might as well be the one - with its fingers in every place. - - <p>Let's begin with handlers. In order to handle the CGI - scripts, the module declares a response handler for them. - Because of <code>ScriptAlias</code>, it also has handlers for - the name translation phase (to recognize - <code>ScriptAlias</code>ed URIs), the type-checking phase (any - <code>ScriptAlias</code>ed request is typed as a CGI - script).</p> - - <p>The module needs to maintain some per (virtual) server - information, namely, the <code>ScriptAlias</code>es in effect; - the module structure therefore contains pointers to a functions - which builds these structures, and to another which combines - two of them (in case the main server and a virtual server both - have <code>ScriptAlias</code>es declared).</p> - - <p>Finally, this module contains code to handle the - <code>ScriptAlias</code> command itself. This particular module - only declares one command, but there could be more, so modules - have <em>command tables</em> which declare their commands, and - describe where they are permitted, and how they are to be - invoked.</p> - - <p>A final note on the declared types of the arguments of some - of these commands: a <code>pool</code> is a pointer to a - <em>resource pool</em> structure; these are used by the server - to keep track of the memory which has been allocated, files - opened, <em>etc.</em>, either to service a particular request, - or to handle the process of configuring itself. That way, when - the request is over (or, for the configuration pool, when the - server is restarting), the memory can be freed, and the files - closed, <em>en masse</em>, without anyone having to write - explicit code to track them all down and dispose of them. Also, - a <code>cmd_parms</code> structure contains various information - about the config file being read, and other status information, - which is sometimes of use to the function which processes a - config-file command (such as <code>ScriptAlias</code>). With no - further ado, the module itself:</p> -<pre> -/* Declarations of handlers. */ - -int translate_scriptalias (request_rec *); -int type_scriptalias (request_rec *); -int cgi_handler (request_rec *); - -/* Subsidiary dispatch table for response-phase handlers, by MIME type */ - -handler_rec cgi_handlers[] = { -{ "application/x-httpd-cgi", cgi_handler }, -{ NULL } -}; - -/* Declarations of routines to manipulate the module's configuration - * info. Note that these are returned, and passed in, as void *'s; - * the server core keeps track of them, but it doesn't, and can't, - * know their internal structure. - */ - -void *make_cgi_server_config (pool *); -void *merge_cgi_server_config (pool *, void *, void *); - -/* Declarations of routines to handle config-file commands */ - -extern char *script_alias(cmd_parms *, void *per_dir_config, char *fake, - char *real); - -command_rec cgi_cmds[] = { -{ "ScriptAlias", script_alias, NULL, RSRC_CONF, TAKE2, - "a fakename and a realname"}, -{ NULL } -}; - -module cgi_module = { - STANDARD_MODULE_STUFF, - NULL, /* initializer */ - NULL, /* dir config creator */ - NULL, /* dir merger --- default is to override */ - make_cgi_server_config, /* server config */ - merge_cgi_server_config, /* merge server config */ - cgi_cmds, /* command table */ - cgi_handlers, /* handlers */ - translate_scriptalias, /* filename translation */ - NULL, /* check_user_id */ - NULL, /* check auth */ - NULL, /* check access */ - type_scriptalias, /* type_checker */ - NULL, /* fixups */ - NULL, /* logger */ - NULL /* header parser */ -}; -</pre> - - <h2><a id="handlers" name="handlers">How handlers work</a></h2> - The sole argument to handlers is a <code>request_rec</code> - structure. This structure describes a particular request which - has been made to the server, on behalf of a client. In most - cases, each connection to the client generates only one - <code>request_rec</code> structure. - - <h3><a id="req_tour" name="req_tour">A brief tour of the - <code>request_rec</code></a></h3> - The <code>request_rec</code> contains pointers to a resource - pool which will be cleared when the server is finished handling - the request; to structures containing per-server and - per-connection information, and most importantly, information - on the request itself. - - <p>The most important such information is a small set of - character strings describing attributes of the object being - requested, including its URI, filename, content-type and - content-encoding (these being filled in by the translation and - type-check handlers which handle the request, - respectively).</p> - - <p>Other commonly used data items are tables giving the MIME - headers on the client's original request, MIME headers to be - sent back with the response (which modules can add to at will), - and environment variables for any subprocesses which are - spawned off in the course of servicing the request. These - tables are manipulated using the <code>ap_table_get</code> and - <code>ap_table_set</code> routines.</p> - - <blockquote> - Note that the <samp>Content-type</samp> header value - <em>cannot</em> be set by module content-handlers using the - <samp>ap_table_*()</samp> routines. Rather, it is set by - pointing the <samp>content_type</samp> field in the - <samp>request_rec</samp> structure to an appropriate string. - <em>E.g.</em>, -<pre> - r->content_type = "text/html"; -</pre> - </blockquote> - Finally, there are pointers to two data structures which, in - turn, point to per-module configuration structures. - Specifically, these hold pointers to the data structures which - the module has built to describe the way it has been configured - to operate in a given directory (via <code>.htaccess</code> - files or <code><Directory></code> sections), for private - data it has built in the course of servicing the request (so - modules' handlers for one phase can pass `notes' to their - handlers for other phases). There is another such configuration - vector in the <code>server_rec</code> data structure pointed to - by the <code>request_rec</code>, which contains per (virtual) - server configuration data. - - <p>Here is an abridged declaration, giving the fields most - commonly used:</p> -<pre> -struct request_rec { - - pool *pool; - conn_rec *connection; - server_rec *server; - - /* What object is being requested */ - - char *uri; - char *filename; - char *path_info; - char *args; /* QUERY_ARGS, if any */ - struct stat finfo; /* Set by server core; - * st_mode set to zero if no such file */ - - char *content_type; - char *content_encoding; - - /* MIME header environments, in and out. Also, an array containing - * environment variables to be passed to subprocesses, so people can - * write modules to add to that environment. - * - * The difference between headers_out and err_headers_out is that - * the latter are printed even on error, and persist across internal - * redirects (so the headers printed for ErrorDocument handlers will - * have them). - */ - - table *headers_in; - table *headers_out; - table *err_headers_out; - table *subprocess_env; - - /* Info about the request itself... */ - - int header_only; /* HEAD request, as opposed to GET */ - char *protocol; /* Protocol, as given to us, or HTTP/0.9 */ - char *method; /* GET, HEAD, POST, <em>etc.</em> */ - int method_number; /* M_GET, M_POST, <em>etc.</em> */ - - /* Info for logging */ - - char *the_request; - int bytes_sent; - - /* A flag which modules can set, to indicate that the data being - * returned is volatile, and clients should be told not to cache it. - */ - - int no_cache; - - /* Various other config info which may change with .htaccess files - * These are config vectors, with one void* pointer for each module - * (the thing pointed to being the module's business). - */ - - void *per_dir_config; /* Options set in config files, <em>etc.</em> */ - void *request_config; /* Notes on *this* request */ - -}; - -</pre> - - <h3><a id="req_orig" name="req_orig">Where request_rec - structures come from</a></h3> - Most <code>request_rec</code> structures are built by reading - an HTTP request from a client, and filling in the fields. - However, there are a few exceptions: - - <ul> - <li>If the request is to an imagemap, a type map - (<em>i.e.</em>, a <code>*.var</code> file), or a CGI script - which returned a local `Location:', then the resource which - the user requested is going to be ultimately located by some - URI other than what the client originally supplied. In this - case, the server does an <em>internal redirect</em>, - constructing a new <code>request_rec</code> for the new URI, - and processing it almost exactly as if the client had - requested the new URI directly.</li> - - <li>If some handler signaled an error, and an - <code>ErrorDocument</code> is in scope, the same internal - redirect machinery comes into play.</li> - - <li> - Finally, a handler occasionally needs to investigate `what - would happen if' some other request were run. For instance, - the directory indexing module needs to know what MIME type - would be assigned to a request for each directory entry, in - order to figure out what icon to use. - - <p>Such handlers can construct a <em>sub-request</em>, - using the functions <code>ap_sub_req_lookup_file</code>, - <code>ap_sub_req_lookup_uri</code>, and - <code>ap_sub_req_method_uri</code>; these construct a new - <code>request_rec</code> structure and processes it as you - would expect, up to but not including the point of actually - sending a response. (These functions skip over the access - checks if the sub-request is for a file in the same - directory as the original request).</p> - - <p>(Server-side includes work by building sub-requests and - then actually invoking the response handler for them, via - the function <code>ap_run_sub_req</code>).</p> - </li> - </ul> - - <h3><a id="req_return" name="req_return">Handling requests, - declining, and returning error codes</a></h3> - As discussed above, each handler, when invoked to handle a - particular <code>request_rec</code>, has to return an - <code>int</code> to indicate what happened. That can either be - - <ul> - <li>OK --- the request was handled successfully. This may or - may not terminate the phase.</li> - - <li>DECLINED --- no erroneous condition exists, but the - module declines to handle the phase; the server tries to find - another.</li> - - <li>an HTTP error code, which aborts handling of the - request.</li> - </ul> - Note that if the error code returned is <code>REDIRECT</code>, - then the module should put a <code>Location</code> in the - request's <code>headers_out</code>, to indicate where the - client should be redirected <em>to</em>. - - <h3><a id="resp_handlers" name="resp_handlers">Special - considerations for response handlers</a></h3> - Handlers for most phases do their work by simply setting a few - fields in the <code>request_rec</code> structure (or, in the - case of access checkers, simply by returning the correct error - code). However, response handlers have to actually send a - request back to the client. - - <p>They should begin by sending an HTTP response header, using - the function <code>ap_send_http_header</code>. (You don't have - to do anything special to skip sending the header for HTTP/0.9 - requests; the function figures out on its own that it shouldn't - do anything). If the request is marked - <code>header_only</code>, that's all they should do; they - should return after that, without attempting any further - output.</p> - - <p>Otherwise, they should produce a request body which responds - to the client as appropriate. The primitives for this are - <code>ap_rputc</code> and <code>ap_rprintf</code>, for - internally generated output, and <code>ap_send_fd</code>, to - copy the contents of some <code>FILE *</code> straight to the - client.</p> - - <p>At this point, you should more or less understand the - following piece of code, which is the handler which handles - <code>GET</code> requests which have no more specific handler; - it also shows how conditional <code>GET</code>s can be handled, - if it's desirable to do so in a particular response handler --- - <code>ap_set_last_modified</code> checks against the - <code>If-modified-since</code> value supplied by the client, if - any, and returns an appropriate code (which will, if nonzero, - be USE_LOCAL_COPY). No similar considerations apply for - <code>ap_set_content_length</code>, but it returns an error - code for symmetry.</p> -<pre> -int default_handler (request_rec *r) -{ - int errstatus; - FILE *f; - - if (r->method_number != M_GET) return DECLINED; - if (r->finfo.st_mode == 0) return NOT_FOUND; - - if ((errstatus = ap_set_content_length (r, r->finfo.st_size)) - || (errstatus = ap_set_last_modified (r, r->finfo.st_mtime))) - return errstatus; - - f = fopen (r->filename, "r"); - - if (f == NULL) { - log_reason("file permissions deny server access", - r->filename, r); - return FORBIDDEN; - } - - register_timeout ("send", r); - ap_send_http_header (r); - - if (!r->header_only) send_fd (f, r); - ap_pfclose (r->pool, f); - return OK; -} -</pre> - Finally, if all of this is too much of a challenge, there are a - few ways out of it. First off, as shown above, a response - handler which has not yet produced any output can simply return - an error code, in which case the server will automatically - produce an error response. Secondly, it can punt to some other - handler by invoking <code>ap_internal_redirect</code>, which is - how the internal redirection machinery discussed above is - invoked. A response handler which has internally redirected - should always return <code>OK</code>. - - <p>(Invoking <code>ap_internal_redirect</code> from handlers - which are <em>not</em> response handlers will lead to serious - confusion).</p> - - <h3><a id="auth_handlers" name="auth_handlers">Special - considerations for authentication handlers</a></h3> - Stuff that should be discussed here in detail: - - <ul> - <li>Authentication-phase handlers not invoked unless auth is - configured for the directory.</li> - - <li>Common auth configuration stored in the core per-dir - configuration; it has accessors <code>ap_auth_type</code>, - <code>ap_auth_name</code>, and <code>ap_requires</code>.</li> - - <li>Common routines, to handle the protocol end of things, at - least for HTTP basic authentication - (<code>ap_get_basic_auth_pw</code>, which sets the - <code>connection->user</code> structure field - automatically, and <code>ap_note_basic_auth_failure</code>, - which arranges for the proper <code>WWW-Authenticate:</code> - header to be sent back).</li> - </ul> - - <h3><a id="log_handlers" name="log_handlers">Special - considerations for logging handlers</a></h3> - When a request has internally redirected, there is the question - of what to log. Apache handles this by bundling the entire - chain of redirects into a list of <code>request_rec</code> - structures which are threaded through the - <code>r->prev</code> and <code>r->next</code> pointers. - The <code>request_rec</code> which is passed to the logging - handlers in such cases is the one which was originally built - for the initial request from the client; note that the - bytes_sent field will only be correct in the last request in - the chain (the one for which a response was actually sent). - - <h2><a id="pools" name="pools">Resource allocation and resource - pools</a></h2> - - <p>One of the problems of writing and designing a server-pool - server is that of preventing leakage, that is, allocating - resources (memory, open files, <em>etc.</em>), without - subsequently releasing them. The resource pool machinery is - designed to make it easy to prevent this from happening, by - allowing resource to be allocated in such a way that they are - <em>automatically</em> released when the server is done with - them.</p> - - <p>The way this works is as follows: the memory which is - allocated, file opened, <em>etc.</em>, to deal with a - particular request are tied to a <em>resource pool</em> which - is allocated for the request. The pool is a data structure - which itself tracks the resources in question.</p> - - <p>When the request has been processed, the pool is - <em>cleared</em>. At that point, all the memory associated with - it is released for reuse, all files associated with it are - closed, and any other clean-up functions which are associated - with the pool are run. When this is over, we can be confident - that all the resource tied to the pool have been released, and - that none of them have leaked.</p> - - <p>Server restarts, and allocation of memory and resources for - per-server configuration, are handled in a similar way. There - is a <em>configuration pool</em>, which keeps track of - resources which were allocated while reading the server - configuration files, and handling the commands therein (for - instance, the memory that was allocated for per-server module - configuration, log files and other files that were opened, and - so forth). When the server restarts, and has to reread the - configuration files, the configuration pool is cleared, and so - the memory and file descriptors which were taken up by reading - them the last time are made available for reuse.</p> - - <p>It should be noted that use of the pool machinery isn't - generally obligatory, except for situations like logging - handlers, where you really need to register cleanups to make - sure that the log file gets closed when the server restarts - (this is most easily done by using the function <code><a - href="#pool-files">ap_pfopen</a></code>, which also arranges - for the underlying file descriptor to be closed before any - child processes, such as for CGI scripts, are - <code>exec</code>ed), or in case you are using the timeout - machinery (which isn't yet even documented here). However, - there are two benefits to using it: resources allocated to a - pool never leak (even if you allocate a scratch string, and - just forget about it); also, for memory allocation, - <code>ap_palloc</code> is generally faster than - <code>malloc</code>.</p> - - <p>We begin here by describing how memory is allocated to - pools, and then discuss how other resources are tracked by the - resource pool machinery.</p> - - <h3>Allocation of memory in pools</h3> - - <p>Memory is allocated to pools by calling the function - <code>ap_palloc</code>, which takes two arguments, one being a - pointer to a resource pool structure, and the other being the - amount of memory to allocate (in <code>char</code>s). Within - handlers for handling requests, the most common way of getting - a resource pool structure is by looking at the - <code>pool</code> slot of the relevant - <code>request_rec</code>; hence the repeated appearance of the - following idiom in module code:</p> -<pre> -int my_handler(request_rec *r) -{ - struct my_structure *foo; - ... - - foo = (foo *)ap_palloc (r->pool, sizeof(my_structure)); -} -</pre> - - <p>Note that <em>there is no <code>ap_pfree</code></em> --- - <code>ap_palloc</code>ed memory is freed only when the - associated resource pool is cleared. This means that - <code>ap_palloc</code> does not have to do as much accounting - as <code>malloc()</code>; all it does in the typical case is to - round up the size, bump a pointer, and do a range check.</p> - - <p>(It also raises the possibility that heavy use of - <code>ap_palloc</code> could cause a server process to grow - excessively large. There are two ways to deal with this, which - are dealt with below; briefly, you can use <code>malloc</code>, - and try to be sure that all of the memory gets explicitly - <code>free</code>d, or you can allocate a sub-pool of the main - pool, allocate your memory in the sub-pool, and clear it out - periodically. The latter technique is discussed in the section - on sub-pools below, and is used in the directory-indexing code, - in order to avoid excessive storage allocation when listing - directories with thousands of files).</p> - - <h3>Allocating initialized memory</h3> - - <p>There are functions which allocate initialized memory, and - are frequently useful. The function <code>ap_pcalloc</code> has - the same interface as <code>ap_palloc</code>, but clears out - the memory it allocates before it returns it. The function - <code>ap_pstrdup</code> takes a resource pool and a <code>char - *</code> as arguments, and allocates memory for a copy of the - string the pointer points to, returning a pointer to the copy. - Finally <code>ap_pstrcat</code> is a varargs-style function, - which takes a pointer to a resource pool, and at least two - <code>char *</code> arguments, the last of which must be - <code>NULL</code>. It allocates enough memory to fit copies of - each of the strings, as a unit; for instance:</p> -<pre> - ap_pstrcat (r->pool, "foo", "/", "bar", NULL); -</pre> - - <p>returns a pointer to 8 bytes worth of memory, initialized to - <code>"foo/bar"</code>.</p> - - <h3><a id="pools-used" name="pools-used">Commonly-used pools in - the Apache Web server</a></h3> - - <p>A pool is really defined by its lifetime more than anything - else. There are some static pools in http_main which are passed - to various non-http_main functions as arguments at opportune - times. Here they are:</p> - - <dl compact="compact"> - <dt>permanent_pool</dt> - - <dd> - <ul> - <li>never passed to anything else, this is the ancestor - of all pools</li> - </ul> - </dd> - - <dt>pconf</dt> - - <dd> - <ul> - <li>subpool of permanent_pool</li> - - <li>created at the beginning of a config "cycle"; exists - until the server is terminated or restarts; passed to all - config-time routines, either via cmd->pool, or as the - "pool *p" argument on those which don't take pools</li> - - <li>passed to the module init() functions</li> - </ul> - </dd> - - <dt>ptemp</dt> - - <dd> - <ul> - <li>sorry I lie, this pool isn't called this currently in - 1.3, I renamed it this in my pthreads development. I'm - referring to the use of ptrans in the parent... contrast - this with the later definition of ptrans in the - child.</li> - - <li>subpool of permanent_pool</li> - - <li>created at the beginning of a config "cycle"; exists - until the end of config parsing; passed to config-time - routines <em>via</em> cmd->temp_pool. Somewhat of a - "bastard child" because it isn't available everywhere. - Used for temporary scratch space which may be needed by - some config routines but which is deleted at the end of - config.</li> - </ul> - </dd> - - <dt>pchild</dt> - - <dd> - <ul> - <li>subpool of permanent_pool</li> - - <li>created when a child is spawned (or a thread is - created); lives until that child (thread) is - destroyed</li> - - <li>passed to the module child_init functions</li> - - <li>destruction happens right after the child_exit - functions are called... (which may explain why I think - child_exit is redundant and unneeded)</li> - </ul> - </dd> - - <dt>ptrans</dt> - - <dd> - <ul> - <li>should be a subpool of pchild, but currently is a - subpool of permanent_pool, see above</li> - - <li>cleared by the child before going into the accept() - loop to receive a connection</li> - - <li>used as connection->pool</li> - </ul> - </dd> - - <dt>r->pool</dt> - - <dd> - <ul> - <li>for the main request this is a subpool of - connection->pool; for subrequests it is a subpool of - the parent request's pool.</li> - - <li>exists until the end of the request (<em>i.e.</em>, - ap_destroy_sub_req, or in child_main after - process_request has finished)</li> - - <li>note that r itself is allocated from r->pool; - <em>i.e.</em>, r->pool is first created and then r is - the first thing palloc()d from it</li> - </ul> - </dd> - </dl> - - <p>For almost everything folks do, r->pool is the pool to - use. But you can see how other lifetimes, such as pchild, are - useful to some modules... such as modules that need to open a - database connection once per child, and wish to clean it up - when the child dies.</p> - - <p>You can also see how some bugs have manifested themself, - such as setting connection->user to a value from r->pool - -- in this case connection exists for the lifetime of ptrans, - which is longer than r->pool (especially if r->pool is a - subrequest!). So the correct thing to do is to allocate from - connection->pool.</p> - - <p>And there was another interesting bug in - mod_include/mod_cgi. You'll see in those that they do this test - to decide if they should use r->pool or r->main->pool. - In this case the resource that they are registering for cleanup - is a child process. If it were registered in r->pool, then - the code would wait() for the child when the subrequest - finishes. With mod_include this could be any old #include, and - the delay can be up to 3 seconds... and happened quite - frequently. Instead the subprocess is registered in - r->main->pool which causes it to be cleaned up when the - entire request is done -- <em>i.e.</em>, after the output has - been sent to the client and logging has happened.</p> - - <h3><a id="pool-files" name="pool-files">Tracking open files, - etc.</a></h3> - - <p>As indicated above, resource pools are also used to track - other sorts of resources besides memory. The most common are - open files. The routine which is typically used for this is - <code>ap_pfopen</code>, which takes a resource pool and two - strings as arguments; the strings are the same as the typical - arguments to <code>fopen</code>, <em>e.g.</em>,</p> -<pre> - ... - FILE *f = ap_pfopen (r->pool, r->filename, "r"); - - if (f == NULL) { ... } else { ... } -</pre> - - <p>There is also a <code>ap_popenf</code> routine, which - parallels the lower-level <code>open</code> system call. Both - of these routines arrange for the file to be closed when the - resource pool in question is cleared.</p> - - <p>Unlike the case for memory, there <em>are</em> functions to - close files allocated with <code>ap_pfopen</code>, and - <code>ap_popenf</code>, namely <code>ap_pfclose</code> and - <code>ap_pclosef</code>. (This is because, on many systems, the - number of files which a single process can have open is quite - limited). It is important to use these functions to close files - allocated with <code>ap_pfopen</code> and - <code>ap_popenf</code>, since to do otherwise could cause fatal - errors on systems such as Linux, which react badly if the same - <code>FILE*</code> is closed more than once.</p> - - <p>(Using the <code>close</code> functions is not mandatory, - since the file will eventually be closed regardless, but you - should consider it in cases where your module is opening, or - could open, a lot of files).</p> - - <h3>Other sorts of resources --- cleanup functions</h3> - - <blockquote> - More text goes here. Describe the the cleanup primitives in - terms of which the file stuff is implemented; also, - <code>spawn_process</code>. - </blockquote> - - <p>Pool cleanups live until clear_pool() is called: - clear_pool(a) recursively calls destroy_pool() on all subpools - of a; then calls all the cleanups for a; then releases all the - memory for a. destroy_pool(a) calls clear_pool(a) and then - releases the pool structure itself. <em>i.e.</em>, - clear_pool(a) doesn't delete a, it just frees up all the - resources and you can start using it again immediately.</p> - - <h3>Fine control --- creating and dealing with sub-pools, with - a note on sub-requests</h3> - On rare occasions, too-free use of <code>ap_palloc()</code> and - the associated primitives may result in undesirably profligate - resource allocation. You can deal with such a case by creating - a <em>sub-pool</em>, allocating within the sub-pool rather than - the main pool, and clearing or destroying the sub-pool, which - releases the resources which were associated with it. (This - really <em>is</em> a rare situation; the only case in which it - comes up in the standard module set is in case of listing - directories, and then only with <em>very</em> large - directories. Unnecessary use of the primitives discussed here - can hair up your code quite a bit, with very little gain). - - <p>The primitive for creating a sub-pool is - <code>ap_make_sub_pool</code>, which takes another pool (the - parent pool) as an argument. When the main pool is cleared, the - sub-pool will be destroyed. The sub-pool may also be cleared or - destroyed at any time, by calling the functions - <code>ap_clear_pool</code> and <code>ap_destroy_pool</code>, - respectively. (The difference is that - <code>ap_clear_pool</code> frees resources associated with the - pool, while <code>ap_destroy_pool</code> also deallocates the - pool itself. In the former case, you can allocate new resources - within the pool, and clear it again, and so forth; in the - latter case, it is simply gone).</p> - - <p>One final note --- sub-requests have their own resource - pools, which are sub-pools of the resource pool for the main - request. The polite way to reclaim the resources associated - with a sub request which you have allocated (using the - <code>ap_sub_req_...</code> functions) is - <code>ap_destroy_sub_req</code>, which frees the resource pool. - Before calling this function, be sure to copy anything that you - care about which might be allocated in the sub-request's - resource pool into someplace a little less volatile (for - instance, the filename in its <code>request_rec</code> - structure).</p> - - <p>(Again, under most circumstances, you shouldn't feel obliged - to call this function; only 2K of memory or so are allocated - for a typical sub request, and it will be freed anyway when the - main request pool is cleared. It is only when you are - allocating many, many sub-requests for a single main request - that you should seriously consider the - <code>ap_destroy_...</code> functions).</p> - - <h2><a id="config" name="config">Configuration, commands and - the like</a></h2> - One of the design goals for this server was to maintain - external compatibility with the NCSA 1.3 server --- that is, to - read the same configuration files, to process all the - directives therein correctly, and in general to be a drop-in - replacement for NCSA. On the other hand, another design goal - was to move as much of the server's functionality into modules - which have as little as possible to do with the monolithic - server core. The only way to reconcile these goals is to move - the handling of most commands from the central server into the - modules. - - <p>However, just giving the modules command tables is not - enough to divorce them completely from the server core. The - server has to remember the commands in order to act on them - later. That involves maintaining data which is private to the - modules, and which can be either per-server, or per-directory. - Most things are per-directory, including in particular access - control and authorization information, but also information on - how to determine file types from suffixes, which can be - modified by <code>AddType</code> and <code>DefaultType</code> - directives, and so forth. In general, the governing philosophy - is that anything which <em>can</em> be made configurable by - directory should be; per-server information is generally used - in the standard set of modules for information like - <code>Alias</code>es and <code>Redirect</code>s which come into - play before the request is tied to a particular place in the - underlying file system.</p> - - <p>Another requirement for emulating the NCSA server is being - able to handle the per-directory configuration files, generally - called <code>.htaccess</code> files, though even in the NCSA - server they can contain directives which have nothing at all to - do with access control. Accordingly, after URI -> filename - translation, but before performing any other phase, the server - walks down the directory hierarchy of the underlying - filesystem, following the translated pathname, to read any - <code>.htaccess</code> files which might be present. The - information which is read in then has to be <em>merged</em> - with the applicable information from the server's own config - files (either from the <code><Directory></code> sections - in <code>access.conf</code>, or from defaults in - <code>srm.conf</code>, which actually behaves for most purposes - almost exactly like <code><Directory /></code>).</p> - - <p>Finally, after having served a request which involved - reading <code>.htaccess</code> files, we need to discard the - storage allocated for handling them. That is solved the same - way it is solved wherever else similar problems come up, by - tying those structures to the per-transaction resource - pool.</p> - - <h3><a id="per-dir" name="per-dir">Per-directory configuration - structures</a></h3> - Let's look out how all of this plays out in - <code>mod_mime.c</code>, which defines the file typing handler - which emulates the NCSA server's behavior of determining file - types from suffixes. What we'll be looking at, here, is the - code which implements the <code>AddType</code> and - <code>AddEncoding</code> commands. These commands can appear in - <code>.htaccess</code> files, so they must be handled in the - module's private per-directory data, which in fact, consists of - two separate <code>table</code>s for MIME types and encoding - information, and is declared as follows: -<pre> -typedef struct { - table *forced_types; /* Additional AddTyped stuff */ - table *encoding_types; /* Added with AddEncoding... */ -} mime_dir_config; -</pre> - When the server is reading a configuration file, or - <code><Directory></code> section, which includes one of - the MIME module's commands, it needs to create a - <code>mime_dir_config</code> structure, so those commands have - something to act on. It does this by invoking the function it - finds in the module's `create per-dir config slot', with two - arguments: the name of the directory to which this - configuration information applies (or <code>NULL</code> for - <code>srm.conf</code>), and a pointer to a resource pool in - which the allocation should happen. - - <p>(If we are reading a <code>.htaccess</code> file, that - resource pool is the per-request resource pool for the request; - otherwise it is a resource pool which is used for configuration - data, and cleared on restarts. Either way, it is important for - the structure being created to vanish when the pool is cleared, - by registering a cleanup on the pool if necessary).</p> - - <p>For the MIME module, the per-dir config creation function - just <code>ap_palloc</code>s the structure above, and a creates - a couple of <code>table</code>s to fill it. That looks like - this:</p> -<pre> -void *create_mime_dir_config (pool *p, char *dummy) -{ - mime_dir_config *new = - (mime_dir_config *) ap_palloc (p, sizeof(mime_dir_config)); - - new->forced_types = ap_make_table (p, 4); - new->encoding_types = ap_make_table (p, 4); - - return new; -} -</pre> - Now, suppose we've just read in a <code>.htaccess</code> file. - We already have the per-directory configuration structure for - the next directory up in the hierarchy. If the - <code>.htaccess</code> file we just read in didn't have any - <code>AddType</code> or <code>AddEncoding</code> commands, its - per-directory config structure for the MIME module is still - valid, and we can just use it. Otherwise, we need to merge the - two structures somehow. - - <p>To do that, the server invokes the module's per-directory - config merge function, if one is present. That function takes - three arguments: the two structures being merged, and a - resource pool in which to allocate the result. For the MIME - module, all that needs to be done is overlay the tables from - the new per-directory config structure with those from the - parent:</p> -<pre> -void *merge_mime_dir_configs (pool *p, void *parent_dirv, void *subdirv) -{ - mime_dir_config *parent_dir = (mime_dir_config *)parent_dirv; - mime_dir_config *subdir = (mime_dir_config *)subdirv; - mime_dir_config *new = - (mime_dir_config *)ap_palloc (p, sizeof(mime_dir_config)); - - new->forced_types = ap_overlay_tables (p, subdir->forced_types, - parent_dir->forced_types); - new->encoding_types = ap_overlay_tables (p, subdir->encoding_types, - parent_dir->encoding_types); - - return new; -} -</pre> - As a note --- if there is no per-directory merge function - present, the server will just use the subdirectory's - configuration info, and ignore the parent's. For some modules, - that works just fine (<em>e.g.</em>, for the includes module, - whose per-directory configuration information consists solely - of the state of the <code>XBITHACK</code>), and for those - modules, you can just not declare one, and leave the - corresponding structure slot in the module itself - <code>NULL</code>. - - <h3><a id="commands" name="commands">Command handling</a></h3> - Now that we have these structures, we need to be able to figure - out how to fill them. That involves processing the actual - <code>AddType</code> and <code>AddEncoding</code> commands. To - find commands, the server looks in the module's <code>command - table</code>. That table contains information on how many - arguments the commands take, and in what formats, where it is - permitted, and so forth. That information is sufficient to - allow the server to invoke most command-handling functions with - pre-parsed arguments. Without further ado, let's look at the - <code>AddType</code> command handler, which looks like this - (the <code>AddEncoding</code> command looks basically the same, - and won't be shown here): -<pre> -char *add_type(cmd_parms *cmd, mime_dir_config *m, char *ct, char *ext) -{ - if (*ext == '.') ++ext; - ap_table_set (m->forced_types, ext, ct); - return NULL; -} -</pre> - This command handler is unusually simple. As you can see, it - takes four arguments, two of which are pre-parsed arguments, - the third being the per-directory configuration structure for - the module in question, and the fourth being a pointer to a - <code>cmd_parms</code> structure. That structure contains a - bunch of arguments which are frequently of use to some, but not - all, commands, including a resource pool (from which memory can - be allocated, and to which cleanups should be tied), and the - (virtual) server being configured, from which the module's - per-server configuration data can be obtained if required. - - <p>Another way in which this particular command handler is - unusually simple is that there are no error conditions which it - can encounter. If there were, it could return an error message - instead of <code>NULL</code>; this causes an error to be - printed out on the server's <code>stderr</code>, followed by a - quick exit, if it is in the main config files; for a - <code>.htaccess</code> file, the syntax error is logged in the - server error log (along with an indication of where it came - from), and the request is bounced with a server error response - (HTTP error status, code 500).</p> - - <p>The MIME module's command table has entries for these - commands, which look like this:</p> -<pre> -command_rec mime_cmds[] = { -{ "AddType", add_type, NULL, OR_FILEINFO, TAKE2, - "a mime type followed by a file extension" }, -{ "AddEncoding", add_encoding, NULL, OR_FILEINFO, TAKE2, - "an encoding (<em>e.g.</em>, gzip), followed by a file extension" }, -{ NULL } -}; -</pre> - The entries in these tables are: - - <ul> - <li>The name of the command</li> - - <li>The function which handles it</li> - - <li>a <code>(void *)</code> pointer, which is passed in the - <code>cmd_parms</code> structure to the command handler --- - this is useful in case many similar commands are handled by - the same function.</li> - - <li>A bit mask indicating where the command may appear. There - are mask bits corresponding to each - <code>AllowOverride</code> option, and an additional mask - bit, <code>RSRC_CONF</code>, indicating that the command may - appear in the server's own config files, but <em>not</em> in - any <code>.htaccess</code> file.</li> - - <li>A flag indicating how many arguments the command handler - wants pre-parsed, and how they should be passed in. - <code>TAKE2</code> indicates two pre-parsed arguments. Other - options are <code>TAKE1</code>, which indicates one - pre-parsed argument, <code>FLAG</code>, which indicates that - the argument should be <code>On</code> or <code>Off</code>, - and is passed in as a boolean flag, <code>RAW_ARGS</code>, - which causes the server to give the command the raw, unparsed - arguments (everything but the command name itself). There is - also <code>ITERATE</code>, which means that the handler looks - the same as <code>TAKE1</code>, but that if multiple - arguments are present, it should be called multiple times, - and finally <code>ITERATE2</code>, which indicates that the - command handler looks like a <code>TAKE2</code>, but if more - arguments are present, then it should be called multiple - times, holding the first argument constant.</li> - - <li>Finally, we have a string which describes the arguments - that should be present. If the arguments in the actual config - file are not as required, this string will be used to help - give a more specific error message. (You can safely leave - this <code>NULL</code>).</li> - </ul> - Finally, having set this all up, we have to use it. This is - ultimately done in the module's handlers, specifically for its - file-typing handler, which looks more or less like this; note - that the per-directory configuration structure is extracted - from the <code>request_rec</code>'s per-directory configuration - vector by using the <code>ap_get_module_config</code> function. - -<pre> -int find_ct(request_rec *r) -{ - int i; - char *fn = ap_pstrdup (r->pool, r->filename); - mime_dir_config *conf = (mime_dir_config *) - ap_get_module_config(r->per_dir_config, &mime_module); - char *type; - - if (S_ISDIR(r->finfo.st_mode)) { - r->content_type = DIR_MAGIC_TYPE; - return OK; - } - - if((i=ap_rind(fn,'.')) < 0) return DECLINED; - ++i; - - if ((type = ap_table_get (conf->encoding_types, &fn[i]))) - { - r->content_encoding = type; - - /* go back to previous extension to try to use it as a type */ - - fn[i-1] = '\0'; - if((i=ap_rind(fn,'.')) < 0) return OK; - ++i; - } - - if ((type = ap_table_get (conf->forced_types, &fn[i]))) - { - r->content_type = type; - } - - return OK; -} - -</pre> - - <h3><a id="servconf" name="servconf">Side notes --- per-server - configuration, virtual servers, <em>etc</em>.</a></h3> - The basic ideas behind per-server module configuration are - basically the same as those for per-directory configuration; - there is a creation function and a merge function, the latter - being invoked where a virtual server has partially overridden - the base server configuration, and a combined structure must be - computed. (As with per-directory configuration, the default if - no merge function is specified, and a module is configured in - some virtual server, is that the base configuration is simply - ignored). - - <p>The only substantial difference is that when a command needs - to configure the per-server private module data, it needs to go - to the <code>cmd_parms</code> data to get at it. Here's an - example, from the alias module, which also indicates how a - syntax error can be returned (note that the per-directory - configuration argument to the command handler is declared as a - dummy, since the module doesn't actually have per-directory - config data):</p> -<pre> -char *add_redirect(cmd_parms *cmd, void *dummy, char *f, char *url) -{ - server_rec *s = cmd->server; - alias_server_conf *conf = (alias_server_conf *) - ap_get_module_config(s->module_config,&alias_module); - alias_entry *new = ap_push_array (conf->redirects); - - if (!ap_is_url (url)) return "Redirect to non-URL"; - - new->fake = f; new->real = url; - return NULL; -} -</pre> - <hr /> - - <h3 align="center">Apache HTTP Server Version 2.1</h3> - <a href="./"><img src="../images/index.gif" alt="Index" /></a> - <a href="../"><img src="../images/home.gif" alt="Home" /></a> - - - - </body> -</html> - diff --git a/docs/manual/developer/API.html.en b/docs/manual/developer/API.html.en new file mode 100644 index 0000000000..36fd338100 --- /dev/null +++ b/docs/manual/developer/API.html.en @@ -0,0 +1,1221 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!-- + XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + This file is generated from xml source: DO NOT EDIT + XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + --> +<title>Apache 1.3 API notes - Apache HTTP Server</title> +<link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /> +<link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /> +<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /> +<link href="../images/favicon.ico" rel="shortcut icon" /></head> +<body id="manual-page"><div id="page-header"> +<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p> +<p class="apache">Apache HTTP Server Version 2.1</p> +<img alt="" src="../images/feather.gif" /></div> +<div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div> +<div id="path"> +<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs-project/">Documentation</a> > <a href="../">Version 2.1</a> > <a href="./">Developer Documentation</a></div><div id="page-content"><div id="preamble"><h1>Apache 1.3 API notes</h1> +<div class="toplang"> +<p><span>Available Languages: </span><a href="../en/developer/API.html"> en </a></p> +</div> + + <div class="warning"><h3>Warning</h3> + <p>This document has not been updated to take into account changes made + in the 2.0 version of the Apache HTTP Server. Some of the information may + still be relevant, but please use it with care.</p> + </div> + + <p>These are some notes on the Apache API and the data structures you have + to deal with, <em>etc.</em> They are not yet nearly complete, but hopefully, + they will help you get your bearings. Keep in mind that the API is still + subject to change as we gain experience with it. (See the TODO file for + what <em>might</em> be coming). However, it will be easy to adapt modules + to any changes that are made. (We have more modules to adapt than you + do).</p> + + <p>A few notes on general pedagogical style here. In the interest of + conciseness, all structure declarations here are incomplete -- the real + ones have more slots that I'm not telling you about. For the most part, + these are reserved to one component of the server core or another, and + should be altered by modules with caution. However, in some cases, they + really are things I just haven't gotten around to yet. Welcome to the + bleeding edge.</p> + + <p>Finally, here's an outline, to give you some bare idea of what's coming + up, and in what order:</p> + + <ul> + <li> + <a href="#basics">Basic concepts.</a> + + <ul> + <li><a href="#HMR">Handlers, Modules, and + Requests</a></li> + + <li><a href="#moduletour">A brief tour of a + module</a></li> + </ul> + </li> + + <li> + <a href="#handlers">How handlers work</a> + + <ul> + <li><a href="#req_tour">A brief tour of the + <code>request_rec</code></a></li> + + <li><a href="#req_orig">Where request_rec structures come + from</a></li> + + <li><a href="#req_return">Handling requests, declining, + and returning error codes</a></li> + + <li><a href="#resp_handlers">Special considerations for + response handlers</a></li> + + <li><a href="#auth_handlers">Special considerations for + authentication handlers</a></li> + + <li><a href="#log_handlers">Special considerations for + logging handlers</a></li> + </ul> + </li> + + <li><a href="#pools">Resource allocation and resource + pools</a></li> + + <li> + <a href="#config">Configuration, commands and the like</a> + + <ul> + <li><a href="#per-dir">Per-directory configuration + structures</a></li> + + <li><a href="#commands">Command handling</a></li> + + <li><a href="#servconf">Side notes --- per-server + configuration, virtual servers, <em>etc</em>.</a></li> + </ul> + </li> + </ul> +</div> +<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#basics">Basic concepts</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#handlers">How handlers work</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#pools">Resource allocation and resource pools</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#config">Configuration, commands and the like</a></li> +</ul></div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="basics" id="basics">Basic concepts</a></h2> + <p>We begin with an overview of the basic concepts behind the API, and how + they are manifested in the code.</p> + + <h3><a name="HMR" id="HMR">Handlers, Modules, and Requests</a></h3> + <p>Apache breaks down request handling into a series of steps, more or + less the same way the Netscape server API does (although this API has a + few more stages than NetSite does, as hooks for stuff I thought might be + useful in the future). These are:</p> + + <ul> + <li>URI -> Filename translation</li> + <li>Auth ID checking [is the user who they say they are?]</li> + <li>Auth access checking [is the user authorized <em>here</em>?]</li> + <li>Access checking other than auth</li> + <li>Determining MIME type of the object requested</li> + <li>`Fixups' -- there aren't any of these yet, but the phase is intended + as a hook for possible extensions like <code class="directive"><a href="../mod/mod_env.html#setenv">SetEnv</a></code>, which don't really fit well elsewhere.</li> + <li>Actually sending a response back to the client.</li> + <li>Logging the request</li> + </ul> + + <p>These phases are handled by looking at each of a succession of + <em>modules</em>, looking to see if each of them has a handler for the + phase, and attempting invoking it if so. The handler can typically do one + of three things:</p> + + <ul> + <li><em>Handle</em> the request, and indicate that it has done so by + returning the magic constant <code>OK</code>.</li> + + <li><em>Decline</em> to handle the request, by returning the magic integer + constant <code>DECLINED</code>. In this case, the server behaves in all + respects as if the handler simply hadn't been there.</li> + + <li>Signal an error, by returning one of the HTTP error codes. This + terminates normal handling of the request, although an ErrorDocument may + be invoked to try to mop up, and it will be logged in any case.</li> + </ul> + + <p>Most phases are terminated by the first module that handles them; + however, for logging, `fixups', and non-access authentication checking, + all handlers always run (barring an error). Also, the response phase is + unique in that modules may declare multiple handlers for it, via a + dispatch table keyed on the MIME type of the requested object. Modules may + declare a response-phase handler which can handle <em>any</em> request, + by giving it the key <code>*/*</code> (<em>i.e.</em>, a wildcard MIME type + specification). However, wildcard handlers are only invoked if the server + has already tried and failed to find a more specific response handler for + the MIME type of the requested object (either none existed, or they all + declined).</p> + + <p>The handlers themselves are functions of one argument (a + <code>request_rec</code> structure. vide infra), which returns an integer, + as above.</p> + + + <h3><a name="moduletour" id="moduletour">A brief tour of a module</a></h3> + <p>At this point, we need to explain the structure of a module. Our + candidate will be one of the messier ones, the CGI module -- this handles + both CGI scripts and the <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code> config file command. It's actually a great deal + more complicated than most modules, but if we're going to have only one + example, it might as well be the one with its fingers in every place.</p> + + <p>Let's begin with handlers. In order to handle the CGI scripts, the + module declares a response handler for them. Because of <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>, it also has handlers for the + name translation phase (to recognize <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>ed URIs), the type-checking phase (any + <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>ed request is typed + as a CGI script).</p> + + <p>The module needs to maintain some per (virtual) server information, + namely, the <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>es in + effect; the module structure therefore contains pointers to a functions + which builds these structures, and to another which combines two of them + (in case the main server and a virtual server both have <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>es declared).</p> + + <p>Finally, this module contains code to handle the <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code> command itself. This particular + module only declares one command, but there could be more, so modules have + <em>command tables</em> which declare their commands, and describe where + they are permitted, and how they are to be invoked.</p> + + <p>A final note on the declared types of the arguments of some of these + commands: a <code>pool</code> is a pointer to a <em>resource pool</em> + structure; these are used by the server to keep track of the memory which + has been allocated, files opened, <em>etc.</em>, either to service a + particular request, or to handle the process of configuring itself. That + way, when the request is over (or, for the configuration pool, when the + server is restarting), the memory can be freed, and the files closed, + <em>en masse</em>, without anyone having to write explicit code to track + them all down and dispose of them. Also, a <code>cmd_parms</code> + structure contains various information about the config file being read, + and other status information, which is sometimes of use to the function + which processes a config-file command (such as <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>). With no further ado, the + module itself:</p> + + <div class="example"><p><code> + /* Declarations of handlers. */<br /> + <br /> + int translate_scriptalias (request_rec *);<br /> + int type_scriptalias (request_rec *);<br /> + int cgi_handler (request_rec *);<br /> + <br /> + /* Subsidiary dispatch table for response-phase <br /> + * handlers, by MIME type */<br /> + <br /> + handler_rec cgi_handlers[] = {<br /> + <span class="indent"> + { "application/x-httpd-cgi", cgi_handler },<br /> + { NULL }<br /> + </span> + };<br /> + <br /> + /* Declarations of routines to manipulate the <br /> + * module's configuration info. Note that these are<br /> + * returned, and passed in, as void *'s; the server<br /> + * core keeps track of them, but it doesn't, and can't,<br /> + * know their internal structure.<br /> + */<br /> + <br /> + void *make_cgi_server_config (pool *);<br /> + void *merge_cgi_server_config (pool *, void *, void *);<br /> + <br /> + /* Declarations of routines to handle config-file commands */<br /> + <br /> + extern char *script_alias(cmd_parms *, void *per_dir_config, char *fake, + char *real);<br /> + <br /> + command_rec cgi_cmds[] = {<br /> + <span class="indent"> + { "ScriptAlias", script_alias, NULL, RSRC_CONF, TAKE2,<br /> + <span class="indent">"a fakename and a realname"},<br /></span> + { NULL }<br /> + </span> + };<br /> + <br /> + module cgi_module = { +</code></p><pre> STANDARD_MODULE_STUFF, + NULL, /* initializer */ + NULL, /* dir config creator */ + NULL, /* dir merger */ + make_cgi_server_config, /* server config */ + merge_cgi_server_config, /* merge server config */ + cgi_cmds, /* command table */ + cgi_handlers, /* handlers */ + translate_scriptalias, /* filename translation */ + NULL, /* check_user_id */ + NULL, /* check auth */ + NULL, /* check access */ + type_scriptalias, /* type_checker */ + NULL, /* fixups */ + NULL, /* logger */ + NULL /* header parser */ +};</pre></div> + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="handlers" id="handlers">How handlers work</a></h2> + <p>The sole argument to handlers is a <code>request_rec</code> structure. + This structure describes a particular request which has been made to the + server, on behalf of a client. In most cases, each connection to the + client generates only one <code>request_rec</code> structure.</p> + + <h3><a name="req_tour" id="req_tour">A brief tour of the request_rec</a></h3> + <p>The <code>request_rec</code> contains pointers to a resource pool + which will be cleared when the server is finished handling the request; + to structures containing per-server and per-connection information, and + most importantly, information on the request itself.</p> + + <p>The most important such information is a small set of character strings + describing attributes of the object being requested, including its URI, + filename, content-type and content-encoding (these being filled in by the + translation and type-check handlers which handle the request, + respectively).</p> + + <p>Other commonly used data items are tables giving the MIME headers on + the client's original request, MIME headers to be sent back with the + response (which modules can add to at will), and environment variables for + any subprocesses which are spawned off in the course of servicing the + request. These tables are manipulated using the <code>ap_table_get</code> + and <code>ap_table_set</code> routines.</p> + + <div class="note"> + <p>Note that the <code>Content-type</code> header value <em>cannot</em> + be set by module content-handlers using the <code>ap_table_*()</code> + routines. Rather, it is set by pointing the <code>content_type</code> + field in the <code>request_rec</code> structure to an appropriate + string. <em>e.g.</em>,</p> + <div class="example"><p><code> + r->content_type = "text/html"; + </code></p></div> + </div> + + <p>Finally, there are pointers to two data structures which, in turn, + point to per-module configuration structures. Specifically, these hold + pointers to the data structures which the module has built to describe + the way it has been configured to operate in a given directory (via + <code>.htaccess</code> files or <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> sections), for private data it has built in the + course of servicing the request (so modules' handlers for one phase can + pass `notes' to their handlers for other phases). There is another such + configuration vector in the <code>server_rec</code> data structure pointed + to by the <code>request_rec</code>, which contains per (virtual) server + configuration data.</p> + + <p>Here is an abridged declaration, giving the fields most commonly + used:</p> + + <div class="example"><p><code> + struct request_rec {<br /> + <br /> + pool *pool;<br /> + conn_rec *connection;<br /> + server_rec *server;<br /> + <br /> + /* What object is being requested */<br /> + <br /> + char *uri;<br /> + char *filename;<br /> + char *path_info; +</code></p><pre>char *args; /* QUERY_ARGS, if any */ +struct stat finfo; /* Set by server core; + * st_mode set to zero if no such file */</pre><p><code> + char *content_type;<br /> + char *content_encoding;<br /> + <br /> + /* MIME header environments, in and out. Also, <br /> + *an array containing environment variables to<br /> + * be passed to subprocesses, so people can write<br /> + * modules to add to that environment.<br /> + *<br /> + * The difference between headers_out and <br /> + * err_headers_out is that the latter are printed <br /> + * even on error, and persist across internal<br /> + * redirects (so the headers printed for <br /> + * <code class="directive"><a href="../mod/core.html#errordocument">ErrorDocument</a></code> handlers will have + them).<br /> + */<br /> + <br /> + table *headers_in;<br /> + table *headers_out;<br /> + table *err_headers_out;<br /> + table *subprocess_env;<br /> + <br /> + /* Info about the request itself... */<br /> + <br /> +</code></p><pre>int header_only; /* HEAD request, as opposed to GET */ +char *protocol; /* Protocol, as given to us, or HTTP/0.9 */ +char *method; /* GET, HEAD, POST, <em>etc.</em> */ +int method_number; /* M_GET, M_POST, <em>etc.</em> */</pre><p><code> + <br /> + /* Info for logging */<br /> + <br /> + char *the_request;<br /> + int bytes_sent;<br /> + <br /> + /* A flag which modules can set, to indicate that<br /> + * the data being returned is volatile, and clients<br /> + * should be told not to cache it.<br /> + */<br /> + <br /> + int no_cache;<br /> + <br /> + /* Various other config info which may change<br /> + * with .htaccess files<br /> + * These are config vectors, with one void*<br /> + * pointer for each module (the thing pointed<br /> + * to being the module's business).<br /> + */<br /> + <br /> +</code></p><pre>void *per_dir_config; /* Options set in config files, <em>etc.</em> */ +void *request_config; /* Notes on *this* request */</pre><p><code> + <br /> + }; + </code></p></div> + + + <h3><a name="req_orig" id="req_orig">Where request_rec structures come from</a></h3> + <p>Most <code>request_rec</code> structures are built by reading an HTTP + request from a client, and filling in the fields. However, there are a + few exceptions:</p> + + <ul> + <li>If the request is to an imagemap, a type map (<em>i.e.</em>, a + <code>*.var</code> file), or a CGI script which returned a local + `Location:', then the resource which the user requested is going to be + ultimately located by some URI other than what the client originally + supplied. In this case, the server does an <em>internal redirect</em>, + constructing a new <code>request_rec</code> for the new URI, and + processing it almost exactly as if the client had requested the new URI + directly.</li> + + <li>If some handler signaled an error, and an <code>ErrorDocument</code> + is in scope, the same internal redirect machinery comes into play.</li> + + <li><p>Finally, a handler occasionally needs to investigate `what would + happen if' some other request were run. For instance, the directory + indexing module needs to know what MIME type would be assigned to a + request for each directory entry, in order to figure out what icon to + use.</p> + + <p>Such handlers can construct a <em>sub-request</em>, using the + functions <code>ap_sub_req_lookup_file</code>, + <code>ap_sub_req_lookup_uri</code>, and <code>ap_sub_req_method_uri</code>; + these construct a new <code>request_rec</code> structure and processes it + as you would expect, up to but not including the point of actually sending + a response. (These functions skip over the access checks if the + sub-request is for a file in the same directory as the original + request).</p> + + <p>(Server-side includes work by building sub-requests and then actually + invoking the response handler for them, via the function + <code>ap_run_sub_req</code>).</p> + </li> + </ul> + + + <h3><a name="req_return" id="req_return">Handling requests, declining, and returning + error codes</a></h3> + <p>As discussed above, each handler, when invoked to handle a particular + <code>request_rec</code>, has to return an <code>int</code> to indicate + what happened. That can either be</p> + + <ul> + <li><code>OK</code> -- the request was handled successfully. This may or + may not terminate the phase.</li> + + <li><code>DECLINED</code> -- no erroneous condition exists, but the module + declines to handle the phase; the server tries to find another.</li> + + <li>an HTTP error code, which aborts handling of the request.</li> + </ul> + + <p>Note that if the error code returned is <code>REDIRECT</code>, then + the module should put a <code>Location</code> in the request's + <code>headers_out</code>, to indicate where the client should be + redirected <em>to</em>.</p> + + + <h3><a name="resp_handlers" id="resp_handlers">Special considerations for response + handlers</a></h3> + <p>Handlers for most phases do their work by simply setting a few fields + in the <code>request_rec</code> structure (or, in the case of access + checkers, simply by returning the correct error code). However, response + handlers have to actually send a request back to the client.</p> + + <p>They should begin by sending an HTTP response header, using the + function <code>ap_send_http_header</code>. (You don't have to do anything + special to skip sending the header for HTTP/0.9 requests; the function + figures out on its own that it shouldn't do anything). If the request is + marked <code>header_only</code>, that's all they should do; they should + return after that, without attempting any further output.</p> + + <p>Otherwise, they should produce a request body which responds to the + client as appropriate. The primitives for this are <code>ap_rputc</code> + and <code>ap_rprintf</code>, for internally generated output, and + <code>ap_send_fd</code>, to copy the contents of some <code>FILE *</code> + straight to the client.</p> + + <p>At this point, you should more or less understand the following piece + of code, which is the handler which handles <code>GET</code> requests + which have no more specific handler; it also shows how conditional + <code>GET</code>s can be handled, if it's desirable to do so in a + particular response handler -- <code>ap_set_last_modified</code> checks + against the <code>If-modified-since</code> value supplied by the client, + if any, and returns an appropriate code (which will, if nonzero, be + USE_LOCAL_COPY). No similar considerations apply for + <code>ap_set_content_length</code>, but it returns an error code for + symmetry.</p> + + <div class="example"><p><code> + int default_handler (request_rec *r)<br /> + {<br /> + <span class="indent"> + int errstatus;<br /> + FILE *f;<br /> + <br /> + if (r->method_number != M_GET) return DECLINED;<br /> + if (r->finfo.st_mode == 0) return NOT_FOUND;<br /> + <br /> + if ((errstatus = ap_set_content_length (r, r->finfo.st_size))<br /> + || + (errstatus = ap_set_last_modified (r, r->finfo.st_mtime)))<br /> + return errstatus;<br /> + <br /> + f = fopen (r->filename, "r");<br /> + <br /> + if (f == NULL) {<br /> + <span class="indent"> + log_reason("file permissions deny server access", r->filename, r);<br /> + return FORBIDDEN;<br /> + </span> + }<br /> + <br /> + register_timeout ("send", r);<br /> + ap_send_http_header (r);<br /> + <br /> + if (!r->header_only) send_fd (f, r);<br /> + ap_pfclose (r->pool, f);<br /> + return OK;<br /> + </span> + } + </code></p></div> + + <p>Finally, if all of this is too much of a challenge, there are a few + ways out of it. First off, as shown above, a response handler which has + not yet produced any output can simply return an error code, in which + case the server will automatically produce an error response. Secondly, + it can punt to some other handler by invoking + <code>ap_internal_redirect</code>, which is how the internal redirection + machinery discussed above is invoked. A response handler which has + internally redirected should always return <code>OK</code>.</p> + + <p>(Invoking <code>ap_internal_redirect</code> from handlers which are + <em>not</em> response handlers will lead to serious confusion).</p> + + + <h3><a name="auth_handlers" id="auth_handlers">Special considerations for authentication + handlers</a></h3> + <p>Stuff that should be discussed here in detail:</p> + + <ul> + <li>Authentication-phase handlers not invoked unless auth is + configured for the directory.</li> + + <li>Common auth configuration stored in the core per-dir + configuration; it has accessors <code>ap_auth_type</code>, + <code>ap_auth_name</code>, and <code>ap_requires</code>.</li> + + <li>Common routines, to handle the protocol end of things, at + least for HTTP basic authentication + (<code>ap_get_basic_auth_pw</code>, which sets the + <code>connection->user</code> structure field + automatically, and <code>ap_note_basic_auth_failure</code>, + which arranges for the proper <code>WWW-Authenticate:</code> + header to be sent back).</li> + </ul> + + + <h3><a name="log_handlers" id="log_handlers">Special considerations for logging + handlers</a></h3> + <p>When a request has internally redirected, there is the question of + what to log. Apache handles this by bundling the entire chain of redirects + into a list of <code>request_rec</code> structures which are threaded + through the <code>r->prev</code> and <code>r->next</code> pointers. + The <code>request_rec</code> which is passed to the logging handlers in + such cases is the one which was originally built for the initial request + from the client; note that the <code>bytes_sent</code> field will only be + correct in the last request in the chain (the one for which a response was + actually sent).</p> + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="pools" id="pools">Resource allocation and resource pools</a></h2> + <p>One of the problems of writing and designing a server-pool server is + that of preventing leakage, that is, allocating resources (memory, open + files, <em>etc.</em>), without subsequently releasing them. The resource + pool machinery is designed to make it easy to prevent this from happening, + by allowing resource to be allocated in such a way that they are + <em>automatically</em> released when the server is done with them.</p> + + <p>The way this works is as follows: the memory which is allocated, file + opened, <em>etc.</em>, to deal with a particular request are tied to a + <em>resource pool</em> which is allocated for the request. The pool is a + data structure which itself tracks the resources in question.</p> + + <p>When the request has been processed, the pool is <em>cleared</em>. At + that point, all the memory associated with it is released for reuse, all + files associated with it are closed, and any other clean-up functions which + are associated with the pool are run. When this is over, we can be confident + that all the resource tied to the pool have been released, and that none of + them have leaked.</p> + + <p>Server restarts, and allocation of memory and resources for per-server + configuration, are handled in a similar way. There is a <em>configuration + pool</em>, which keeps track of resources which were allocated while reading + the server configuration files, and handling the commands therein (for + instance, the memory that was allocated for per-server module configuration, + log files and other files that were opened, and so forth). When the server + restarts, and has to reread the configuration files, the configuration pool + is cleared, and so the memory and file descriptors which were taken up by + reading them the last time are made available for reuse.</p> + + <p>It should be noted that use of the pool machinery isn't generally + obligatory, except for situations like logging handlers, where you really + need to register cleanups to make sure that the log file gets closed when + the server restarts (this is most easily done by using the function <code><a href="#pool-files">ap_pfopen</a></code>, which also arranges for the + underlying file descriptor to be closed before any child processes, such as + for CGI scripts, are <code>exec</code>ed), or in case you are using the + timeout machinery (which isn't yet even documented here). However, there are + two benefits to using it: resources allocated to a pool never leak (even if + you allocate a scratch string, and just forget about it); also, for memory + allocation, <code>ap_palloc</code> is generally faster than + <code>malloc</code>.</p> + + <p>We begin here by describing how memory is allocated to pools, and then + discuss how other resources are tracked by the resource pool machinery.</p> + + <h3>Allocation of memory in pools</h3> + <p>Memory is allocated to pools by calling the function + <code>ap_palloc</code>, which takes two arguments, one being a pointer to + a resource pool structure, and the other being the amount of memory to + allocate (in <code>char</code>s). Within handlers for handling requests, + the most common way of getting a resource pool structure is by looking at + the <code>pool</code> slot of the relevant <code>request_rec</code>; hence + the repeated appearance of the following idiom in module code:</p> + + <div class="example"><p><code> + int my_handler(request_rec *r)<br /> + {<br /> + <span class="indent"> + struct my_structure *foo;<br /> + ...<br /> + <br /> + foo = (foo *)ap_palloc (r->pool, sizeof(my_structure));<br /> + </span> + } + </code></p></div> + + <p>Note that <em>there is no <code>ap_pfree</code></em> -- + <code>ap_palloc</code>ed memory is freed only when the associated resource + pool is cleared. This means that <code>ap_palloc</code> does not have to + do as much accounting as <code>malloc()</code>; all it does in the typical + case is to round up the size, bump a pointer, and do a range check.</p> + + <p>(It also raises the possibility that heavy use of + <code>ap_palloc</code> could cause a server process to grow excessively + large. There are two ways to deal with this, which are dealt with below; + briefly, you can use <code>malloc</code>, and try to be sure that all of + the memory gets explicitly <code>free</code>d, or you can allocate a + sub-pool of the main pool, allocate your memory in the sub-pool, and clear + it out periodically. The latter technique is discussed in the section + on sub-pools below, and is used in the directory-indexing code, in order + to avoid excessive storage allocation when listing directories with + thousands of files).</p> + + + <h3>Allocating initialized memory</h3> + <p>There are functions which allocate initialized memory, and are + frequently useful. The function <code>ap_pcalloc</code> has the same + interface as <code>ap_palloc</code>, but clears out the memory it + allocates before it returns it. The function <code>ap_pstrdup</code> + takes a resource pool and a <code>char *</code> as arguments, and + allocates memory for a copy of the string the pointer points to, returning + a pointer to the copy. Finally <code>ap_pstrcat</code> is a varargs-style + function, which takes a pointer to a resource pool, and at least two + <code>char *</code> arguments, the last of which must be + <code>NULL</code>. It allocates enough memory to fit copies of each of + the strings, as a unit; for instance:</p> + + <div class="example"><p><code> + ap_pstrcat (r->pool, "foo", "/", "bar", NULL); + </code></p></div> + + <p>returns a pointer to 8 bytes worth of memory, initialized to + <code>"foo/bar"</code>.</p> + + + <h3><a name="pools-used" id="pools-used">Commonly-used pools in the Apache Web + server</a></h3> + <p>A pool is really defined by its lifetime more than anything else. + There are some static pools in http_main which are passed to various + non-http_main functions as arguments at opportune times. Here they + are:</p> + + <dl> + <dt><code>permanent_pool</code></dt> + <dd>never passed to anything else, this is the ancestor of all pools</dd> + + <dt><code>pconf</code></dt> + <dd> + <ul> + <li>subpool of permanent_pool</li> + + <li>created at the beginning of a config "cycle"; exists + until the server is terminated or restarts; passed to all + config-time routines, either via cmd->pool, or as the + "pool *p" argument on those which don't take pools</li> + + <li>passed to the module init() functions</li> + </ul> + </dd> + + <dt><code>ptemp</code></dt> + <dd> + <ul> + <li>sorry I lie, this pool isn't called this currently in + 1.3, I renamed it this in my pthreads development. I'm + referring to the use of ptrans in the parent... contrast + this with the later definition of ptrans in the + child.</li> + + <li>subpool of permanent_pool</li> + + <li>created at the beginning of a config "cycle"; exists + until the end of config parsing; passed to config-time + routines <em>via</em> cmd->temp_pool. Somewhat of a + "bastard child" because it isn't available everywhere. + Used for temporary scratch space which may be needed by + some config routines but which is deleted at the end of + config.</li> + </ul> + </dd> + + <dt><code>pchild</code></dt> + <dd> + <ul> + <li>subpool of permanent_pool</li> + + <li>created when a child is spawned (or a thread is + created); lives until that child (thread) is + destroyed</li> + + <li>passed to the module child_init functions</li> + + <li>destruction happens right after the child_exit + functions are called... (which may explain why I think + child_exit is redundant and unneeded)</li> + </ul> + </dd> + + <dt><code>ptrans</code></dt> + <dd> + <ul> + <li>should be a subpool of pchild, but currently is a + subpool of permanent_pool, see above</li> + + <li>cleared by the child before going into the accept() + loop to receive a connection</li> + + <li>used as connection->pool</li> + </ul> + </dd> + + <dt><code>r->pool</code></dt> + <dd> + <ul> + <li>for the main request this is a subpool of + connection->pool; for subrequests it is a subpool of + the parent request's pool.</li> + + <li>exists until the end of the request (<em>i.e.</em>, + ap_destroy_sub_req, or in child_main after + process_request has finished)</li> + + <li>note that r itself is allocated from r->pool; + <em>i.e.</em>, r->pool is first created and then r is + the first thing palloc()d from it</li> + </ul> + </dd> + </dl> + + <p>For almost everything folks do, <code>r->pool</code> is the pool to + use. But you can see how other lifetimes, such as pchild, are useful to + some modules... such as modules that need to open a database connection + once per child, and wish to clean it up when the child dies.</p> + + <p>You can also see how some bugs have manifested themself, such as + setting <code>connection->user</code> to a value from + <code>r->pool</code> -- in this case connection exists for the + lifetime of <code>ptrans</code>, which is longer than + <code>r->pool</code> (especially if <code>r->pool</code> is a + subrequest!). So the correct thing to do is to allocate from + <code>connection->pool</code>.</p> + + <p>And there was another interesting bug in <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> + / <code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code>. You'll see in those that they do this test + to decide if they should use <code>r->pool</code> or + <code>r->main->pool</code>. In this case the resource that they are + registering for cleanup is a child process. If it were registered in + <code>r->pool</code>, then the code would <code>wait()</code> for the + child when the subrequest finishes. With <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> this + could be any old <code>#include</code>, and the delay can be up to 3 + seconds... and happened quite frequently. Instead the subprocess is + registered in <code>r->main->pool</code> which causes it to be + cleaned up when the entire request is done -- <em>i.e.</em>, after the + output has been sent to the client and logging has happened.</p> + + + <h3><a name="pool-files" id="pool-files">Tracking open files, etc.</a></h3> + <p>As indicated above, resource pools are also used to track other sorts + of resources besides memory. The most common are open files. The routine + which is typically used for this is <code>ap_pfopen</code>, which takes a + resource pool and two strings as arguments; the strings are the same as + the typical arguments to <code>fopen</code>, <em>e.g.</em>,</p> + + <div class="example"><p><code> + ...<br /> + FILE *f = ap_pfopen (r->pool, r->filename, "r");<br /> + <br /> + if (f == NULL) { ... } else { ... }<br /> + </code></p></div> + + <p>There is also a <code>ap_popenf</code> routine, which parallels the + lower-level <code>open</code> system call. Both of these routines arrange + for the file to be closed when the resource pool in question is + cleared.</p> + + <p>Unlike the case for memory, there <em>are</em> functions to close files + allocated with <code>ap_pfopen</code>, and <code>ap_popenf</code>, namely + <code>ap_pfclose</code> and <code>ap_pclosef</code>. (This is because, on + many systems, the number of files which a single process can have open is + quite limited). It is important to use these functions to close files + allocated with <code>ap_pfopen</code> and <code>ap_popenf</code>, since to + do otherwise could cause fatal errors on systems such as Linux, which + react badly if the same <code>FILE*</code> is closed more than once.</p> + + <p>(Using the <code>close</code> functions is not mandatory, since the + file will eventually be closed regardless, but you should consider it in + cases where your module is opening, or could open, a lot of files).</p> + + + <h3>Other sorts of resources -- cleanup functions</h3> + <p>More text goes here. Describe the the cleanup primitives in terms of + which the file stuff is implemented; also, <code>spawn_process</code>.</p> + + <p>Pool cleanups live until <code>clear_pool()</code> is called: + <code>clear_pool(a)</code> recursively calls <code>destroy_pool()</code> + on all subpools of <code>a</code>; then calls all the cleanups for + <code>a</code>; then releases all the memory for <code>a</code>. + <code>destroy_pool(a)</code> calls <code>clear_pool(a)</code> and then + releases the pool structure itself. <em>i.e.</em>, + <code>clear_pool(a)</code> doesn't delete <code>a</code>, it just frees + up all the resources and you can start using it again immediately.</p> + + + <h3>Fine control -- creating and dealing with sub-pools, with + a note on sub-requests</h3> + <p>On rare occasions, too-free use of <code>ap_palloc()</code> and the + associated primitives may result in undesirably profligate resource + allocation. You can deal with such a case by creating a <em>sub-pool</em>, + allocating within the sub-pool rather than the main pool, and clearing or + destroying the sub-pool, which releases the resources which were + associated with it. (This really <em>is</em> a rare situation; the only + case in which it comes up in the standard module set is in case of listing + directories, and then only with <em>very</em> large directories. + Unnecessary use of the primitives discussed here can hair up your code + quite a bit, with very little gain).</p> + + <p>The primitive for creating a sub-pool is <code>ap_make_sub_pool</code>, + which takes another pool (the parent pool) as an argument. When the main + pool is cleared, the sub-pool will be destroyed. The sub-pool may also be + cleared or destroyed at any time, by calling the functions + <code>ap_clear_pool</code> and <code>ap_destroy_pool</code>, respectively. + (The difference is that <code>ap_clear_pool</code> frees resources + associated with the pool, while <code>ap_destroy_pool</code> also + deallocates the pool itself. In the former case, you can allocate new + resources within the pool, and clear it again, and so forth; in the + latter case, it is simply gone).</p> + + <p>One final note -- sub-requests have their own resource pools, which are + sub-pools of the resource pool for the main request. The polite way to + reclaim the resources associated with a sub request which you have + allocated (using the <code>ap_sub_req_...</code> functions) is + <code>ap_destroy_sub_req</code>, which frees the resource pool. Before + calling this function, be sure to copy anything that you care about which + might be allocated in the sub-request's resource pool into someplace a + little less volatile (for instance, the filename in its + <code>request_rec</code> structure).</p> + + <p>(Again, under most circumstances, you shouldn't feel obliged to call + this function; only 2K of memory or so are allocated for a typical sub + request, and it will be freed anyway when the main request pool is + cleared. It is only when you are allocating many, many sub-requests for a + single main request that you should seriously consider the + <code>ap_destroy_...</code> functions).</p> + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="config" id="config">Configuration, commands and the like</a></h2> + <p>One of the design goals for this server was to maintain external + compatibility with the NCSA 1.3 server --- that is, to read the same + configuration files, to process all the directives therein correctly, and + in general to be a drop-in replacement for NCSA. On the other hand, another + design goal was to move as much of the server's functionality into modules + which have as little as possible to do with the monolithic server core. The + only way to reconcile these goals is to move the handling of most commands + from the central server into the modules.</p> + + <p>However, just giving the modules command tables is not enough to divorce + them completely from the server core. The server has to remember the + commands in order to act on them later. That involves maintaining data which + is private to the modules, and which can be either per-server, or + per-directory. Most things are per-directory, including in particular access + control and authorization information, but also information on how to + determine file types from suffixes, which can be modified by + <code class="directive"><a href="../mod/mod_mime.html#addtype">AddType</a></code> and <code class="directive"><a href="../mod/core.html#defaulttype">DefaultType</a></code> directives, and so forth. In general, + the governing philosophy is that anything which <em>can</em> be made + configurable by directory should be; per-server information is generally + used in the standard set of modules for information like + <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code>es and <code class="directive"><a href="../mod/mod_alias.html#redirect">Redirect</a></code>s which come into play before the + request is tied to a particular place in the underlying file system.</p> + + <p>Another requirement for emulating the NCSA server is being able to handle + the per-directory configuration files, generally called + <code>.htaccess</code> files, though even in the NCSA server they can + contain directives which have nothing at all to do with access control. + Accordingly, after URI -> filename translation, but before performing any + other phase, the server walks down the directory hierarchy of the underlying + filesystem, following the translated pathname, to read any + <code>.htaccess</code> files which might be present. The information which + is read in then has to be <em>merged</em> with the applicable information + from the server's own config files (either from the <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> sections in + <code>access.conf</code>, or from defaults in <code>srm.conf</code>, which + actually behaves for most purposes almost exactly like <code><Directory + /></code>).</p> + + <p>Finally, after having served a request which involved reading + <code>.htaccess</code> files, we need to discard the storage allocated for + handling them. That is solved the same way it is solved wherever else + similar problems come up, by tying those structures to the per-transaction + resource pool.</p> + + <h3><a name="per-dir" id="per-dir">Per-directory configuration structures</a></h3> + <p>Let's look out how all of this plays out in <code>mod_mime.c</code>, + which defines the file typing handler which emulates the NCSA server's + behavior of determining file types from suffixes. What we'll be looking + at, here, is the code which implements the <code class="directive"><a href="../mod/mod_mime.html#addtype">AddType</a></code> and <code class="directive"><a href="../mod/mod_mime.html#addencoding">AddEncoding</a></code> commands. These commands can appear in + <code>.htaccess</code> files, so they must be handled in the module's + private per-directory data, which in fact, consists of two separate + tables for MIME types and encoding information, and is declared as + follows:</p> + + <div class="example"><pre>typedef struct { + table *forced_types; /* Additional AddTyped stuff */ + table *encoding_types; /* Added with AddEncoding... */ +} mime_dir_config;</pre></div> + + <p>When the server is reading a configuration file, or <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> section, which includes + one of the MIME module's commands, it needs to create a + <code>mime_dir_config</code> structure, so those commands have something + to act on. It does this by invoking the function it finds in the module's + `create per-dir config slot', with two arguments: the name of the + directory to which this configuration information applies (or + <code>NULL</code> for <code>srm.conf</code>), and a pointer to a + resource pool in which the allocation should happen.</p> + + <p>(If we are reading a <code>.htaccess</code> file, that resource pool + is the per-request resource pool for the request; otherwise it is a + resource pool which is used for configuration data, and cleared on + restarts. Either way, it is important for the structure being created to + vanish when the pool is cleared, by registering a cleanup on the pool if + necessary).</p> + + <p>For the MIME module, the per-dir config creation function just + <code>ap_palloc</code>s the structure above, and a creates a couple of + tables to fill it. That looks like this:</p> + + <div class="example"><p><code> + void *create_mime_dir_config (pool *p, char *dummy)<br /> + {<br /> + <span class="indent"> + mime_dir_config *new =<br /> + <span class="indent"> + (mime_dir_config *) ap_palloc (p, sizeof(mime_dir_config));<br /> + </span> + <br /> + new->forced_types = ap_make_table (p, 4);<br /> + new->encoding_types = ap_make_table (p, 4);<br /> + <br /> + return new;<br /> + </span> + } + </code></p></div> + + <p>Now, suppose we've just read in a <code>.htaccess</code> file. We + already have the per-directory configuration structure for the next + directory up in the hierarchy. If the <code>.htaccess</code> file we just + read in didn't have any <code class="directive"><a href="../mod/mod_mime.html#addtype">AddType</a></code> + or <code class="directive"><a href="../mod/mod_mime.html#addencoding">AddEncoding</a></code> commands, its + per-directory config structure for the MIME module is still valid, and we + can just use it. Otherwise, we need to merge the two structures + somehow.</p> + + <p>To do that, the server invokes the module's per-directory config merge + function, if one is present. That function takes three arguments: the two + structures being merged, and a resource pool in which to allocate the + result. For the MIME module, all that needs to be done is overlay the + tables from the new per-directory config structure with those from the + parent:</p> + + <div class="example"><p><code> + void *merge_mime_dir_configs (pool *p, void *parent_dirv, void *subdirv)<br /> + {<br /> + <span class="indent"> + mime_dir_config *parent_dir = (mime_dir_config *)parent_dirv;<br /> + mime_dir_config *subdir = (mime_dir_config *)subdirv;<br /> + mime_dir_config *new =<br /> + <span class="indent"> + (mime_dir_config *)ap_palloc (p, sizeof(mime_dir_config));<br /> + </span> + <br /> + new->forced_types = ap_overlay_tables (p, subdir->forced_types,<br /> + <span class="indent"> + parent_dir->forced_types);<br /> + </span> + new->encoding_types = ap_overlay_tables (p, subdir->encoding_types,<br /> + <span class="indent"> + parent_dir->encoding_types);<br /> + </span> + <br /> + return new;<br /> + </span> + } + </code></p></div> + + <p>As a note -- if there is no per-directory merge function present, the + server will just use the subdirectory's configuration info, and ignore + the parent's. For some modules, that works just fine (<em>e.g.</em>, for + the includes module, whose per-directory configuration information + consists solely of the state of the <code>XBITHACK</code>), and for those + modules, you can just not declare one, and leave the corresponding + structure slot in the module itself <code>NULL</code>.</p> + + + <h3><a name="commands" id="commands">Command handling</a></h3> + <p>Now that we have these structures, we need to be able to figure out how + to fill them. That involves processing the actual <code class="directive"><a href="../mod/mod_mime.html#addtype">AddType</a></code> and <code class="directive"><a href="../mod/mod_mime.html#addencoding">AddEncoding</a></code> commands. To find commands, the server looks in + the module's command table. That table contains information on how many + arguments the commands take, and in what formats, where it is permitted, + and so forth. That information is sufficient to allow the server to invoke + most command-handling functions with pre-parsed arguments. Without further + ado, let's look at the <code class="directive"><a href="../mod/mod_mime.html#addtype">AddType</a></code> + command handler, which looks like this (the <code class="directive"><a href="../mod/mod_mime.html#addencoding">AddEncoding</a></code> command looks basically the same, and won't be + shown here):</p> + + <div class="example"><p><code> + char *add_type(cmd_parms *cmd, mime_dir_config *m, char *ct, char *ext)<br /> + {<br /> + <span class="indent"> + if (*ext == '.') ++ext;<br /> + ap_table_set (m->forced_types, ext, ct);<br /> + return NULL;<br /> + </span> + } + </code></p></div> + + <p>This command handler is unusually simple. As you can see, it takes + four arguments, two of which are pre-parsed arguments, the third being the + per-directory configuration structure for the module in question, and the + fourth being a pointer to a <code>cmd_parms</code> structure. That + structure contains a bunch of arguments which are frequently of use to + some, but not all, commands, including a resource pool (from which memory + can be allocated, and to which cleanups should be tied), and the (virtual) + server being configured, from which the module's per-server configuration + data can be obtained if required.</p> + + <p>Another way in which this particular command handler is unusually + simple is that there are no error conditions which it can encounter. If + there were, it could return an error message instead of <code>NULL</code>; + this causes an error to be printed out on the server's + <code>stderr</code>, followed by a quick exit, if it is in the main config + files; for a <code>.htaccess</code> file, the syntax error is logged in + the server error log (along with an indication of where it came from), and + the request is bounced with a server error response (HTTP error status, + code 500).</p> + + <p>The MIME module's command table has entries for these commands, which + look like this:</p> + + <div class="example"><p><code> + command_rec mime_cmds[] = {<br /> + <span class="indent"> + { "AddType", add_type, NULL, OR_FILEINFO, TAKE2,<br /> + <span class="indent">"a mime type followed by a file extension" },<br /></span> + { "AddEncoding", add_encoding, NULL, OR_FILEINFO, TAKE2,<br /> + <span class="indent"> + "an encoding (<em>e.g.</em>, gzip), followed by a file extension" },<br /> + </span> + { NULL }<br /> + </span> + }; + </code></p></div> + + <p>The entries in these tables are:</p> + <ul> + <li>The name of the command</li> + <li>The function which handles it</li> + <li>a <code>(void *)</code> pointer, which is passed in the + <code>cmd_parms</code> structure to the command handler --- + this is useful in case many similar commands are handled by + the same function.</li> + + <li>A bit mask indicating where the command may appear. There + are mask bits corresponding to each + <code>AllowOverride</code> option, and an additional mask + bit, <code>RSRC_CONF</code>, indicating that the command may + appear in the server's own config files, but <em>not</em> in + any <code>.htaccess</code> file.</li> + + <li>A flag indicating how many arguments the command handler + wants pre-parsed, and how they should be passed in. + <code>TAKE2</code> indicates two pre-parsed arguments. Other + options are <code>TAKE1</code>, which indicates one + pre-parsed argument, <code>FLAG</code>, which indicates that + the argument should be <code>On</code> or <code>Off</code>, + and is passed in as a boolean flag, <code>RAW_ARGS</code>, + which causes the server to give the command the raw, unparsed + arguments (everything but the command name itself). There is + also <code>ITERATE</code>, which means that the handler looks + the same as <code>TAKE1</code>, but that if multiple + arguments are present, it should be called multiple times, + and finally <code>ITERATE2</code>, which indicates that the + command handler looks like a <code>TAKE2</code>, but if more + arguments are present, then it should be called multiple + times, holding the first argument constant.</li> + + <li>Finally, we have a string which describes the arguments + that should be present. If the arguments in the actual config + file are not as required, this string will be used to help + give a more specific error message. (You can safely leave + this <code>NULL</code>).</li> + </ul> + + <p>Finally, having set this all up, we have to use it. This is ultimately + done in the module's handlers, specifically for its file-typing handler, + which looks more or less like this; note that the per-directory + configuration structure is extracted from the <code>request_rec</code>'s + per-directory configuration vector by using the + <code>ap_get_module_config</code> function.</p> + + <div class="example"><p><code> + int find_ct(request_rec *r)<br /> + {<br /> + <span class="indent"> + int i;<br /> + char *fn = ap_pstrdup (r->pool, r->filename);<br /> + mime_dir_config *conf = (mime_dir_config *)<br /> + <span class="indent"> + ap_get_module_config(r->per_dir_config, &mime_module);<br /> + </span> + char *type;<br /> + <br /> + if (S_ISDIR(r->finfo.st_mode)) {<br /> + <span class="indent"> + r->content_type = DIR_MAGIC_TYPE;<br /> + return OK;<br /> + </span> + }<br /> + <br /> + if((i=ap_rind(fn,'.')) < 0) return DECLINED;<br /> + ++i;<br /> + <br /> + if ((type = ap_table_get (conf->encoding_types, &fn[i])))<br /> + {<br /> + <span class="indent"> + r->content_encoding = type;<br /> + <br /> + /* go back to previous extension to try to use it as a type */<br /> + fn[i-1] = '\0';<br /> + if((i=ap_rind(fn,'.')) < 0) return OK;<br /> + ++i;<br /> + </span> + }<br /> + <br /> + if ((type = ap_table_get (conf->forced_types, &fn[i])))<br /> + {<br /> + <span class="indent"> + r->content_type = type;<br /> + </span> + }<br /> + <br /> + return OK; + </span> + } + </code></p></div> + + + <h3><a name="servconf" id="servconf">Side notes -- per-server configuration, + virtual servers, <em>etc</em>.</a></h3> + <p>The basic ideas behind per-server module configuration are basically + the same as those for per-directory configuration; there is a creation + function and a merge function, the latter being invoked where a virtual + server has partially overridden the base server configuration, and a + combined structure must be computed. (As with per-directory configuration, + the default if no merge function is specified, and a module is configured + in some virtual server, is that the base configuration is simply + ignored).</p> + + <p>The only substantial difference is that when a command needs to + configure the per-server private module data, it needs to go to the + <code>cmd_parms</code> data to get at it. Here's an example, from the + alias module, which also indicates how a syntax error can be returned + (note that the per-directory configuration argument to the command + handler is declared as a dummy, since the module doesn't actually have + per-directory config data):</p> + + <div class="example"><p><code> + char *add_redirect(cmd_parms *cmd, void *dummy, char *f, char *url)<br /> + {<br /> + <span class="indent"> + server_rec *s = cmd->server;<br /> + alias_server_conf *conf = (alias_server_conf *)<br /> + <span class="indent"> + ap_get_module_config(s->module_config,&alias_module);<br /> + </span> + alias_entry *new = ap_push_array (conf->redirects);<br /> + <br /> + if (!ap_is_url (url)) return "Redirect to non-URL";<br /> + <br /> + new->fake = f; new->real = url;<br /> + return NULL;<br /> + </span> + } + </code></p></div> + +</div></div> +<div class="bottomlang"> +<p><span>Available Languages: </span><a href="../en/developer/API.html"> en </a></p> +</div><div id="footer"> +<p class="apache">Maintained by the <a href="http://httpd.apache.org/docs-project/">Apache HTTP Server Documentation Project</a></p> +<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div> +</body></html>
\ No newline at end of file diff --git a/docs/manual/developer/API.xml b/docs/manual/developer/API.xml new file mode 100644 index 0000000000..eb7cf21e51 --- /dev/null +++ b/docs/manual/developer/API.xml @@ -0,0 +1,1219 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd"> +<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> + +<manualpage metafile="API.xml.meta"> +<parentdocument href="./">Developer Documentation</parentdocument> + +<title>Apache 1.3 API notes</title> + +<summary> + <note type="warning"><title>Warning</title> + <p>This document has not been updated to take into account changes made + in the 2.0 version of the Apache HTTP Server. Some of the information may + still be relevant, but please use it with care.</p> + </note> + + <p>These are some notes on the Apache API and the data structures you have + to deal with, <em>etc.</em> They are not yet nearly complete, but hopefully, + they will help you get your bearings. Keep in mind that the API is still + subject to change as we gain experience with it. (See the TODO file for + what <em>might</em> be coming). However, it will be easy to adapt modules + to any changes that are made. (We have more modules to adapt than you + do).</p> + + <p>A few notes on general pedagogical style here. In the interest of + conciseness, all structure declarations here are incomplete -- the real + ones have more slots that I'm not telling you about. For the most part, + these are reserved to one component of the server core or another, and + should be altered by modules with caution. However, in some cases, they + really are things I just haven't gotten around to yet. Welcome to the + bleeding edge.</p> + + <p>Finally, here's an outline, to give you some bare idea of what's coming + up, and in what order:</p> + + <ul> + <li> + <a href="#basics">Basic concepts.</a> + + <ul> + <li><a href="#HMR">Handlers, Modules, and + Requests</a></li> + + <li><a href="#moduletour">A brief tour of a + module</a></li> + </ul> + </li> + + <li> + <a href="#handlers">How handlers work</a> + + <ul> + <li><a href="#req_tour">A brief tour of the + <code>request_rec</code></a></li> + + <li><a href="#req_orig">Where request_rec structures come + from</a></li> + + <li><a href="#req_return">Handling requests, declining, + and returning error codes</a></li> + + <li><a href="#resp_handlers">Special considerations for + response handlers</a></li> + + <li><a href="#auth_handlers">Special considerations for + authentication handlers</a></li> + + <li><a href="#log_handlers">Special considerations for + logging handlers</a></li> + </ul> + </li> + + <li><a href="#pools">Resource allocation and resource + pools</a></li> + + <li> + <a href="#config">Configuration, commands and the like</a> + + <ul> + <li><a href="#per-dir">Per-directory configuration + structures</a></li> + + <li><a href="#commands">Command handling</a></li> + + <li><a href="#servconf">Side notes --- per-server + configuration, virtual servers, <em>etc</em>.</a></li> + </ul> + </li> + </ul> +</summary> + +<section id="basics"><title>Basic concepts</title> + <p>We begin with an overview of the basic concepts behind the API, and how + they are manifested in the code.</p> + + <section id="HMR"><title>Handlers, Modules, and Requests</title> + <p>Apache breaks down request handling into a series of steps, more or + less the same way the Netscape server API does (although this API has a + few more stages than NetSite does, as hooks for stuff I thought might be + useful in the future). These are:</p> + + <ul> + <li>URI -> Filename translation</li> + <li>Auth ID checking [is the user who they say they are?]</li> + <li>Auth access checking [is the user authorized <em>here</em>?]</li> + <li>Access checking other than auth</li> + <li>Determining MIME type of the object requested</li> + <li>`Fixups' -- there aren't any of these yet, but the phase is intended + as a hook for possible extensions like <directive module="mod_env" + >SetEnv</directive>, which don't really fit well elsewhere.</li> + <li>Actually sending a response back to the client.</li> + <li>Logging the request</li> + </ul> + + <p>These phases are handled by looking at each of a succession of + <em>modules</em>, looking to see if each of them has a handler for the + phase, and attempting invoking it if so. The handler can typically do one + of three things:</p> + + <ul> + <li><em>Handle</em> the request, and indicate that it has done so by + returning the magic constant <code>OK</code>.</li> + + <li><em>Decline</em> to handle the request, by returning the magic integer + constant <code>DECLINED</code>. In this case, the server behaves in all + respects as if the handler simply hadn't been there.</li> + + <li>Signal an error, by returning one of the HTTP error codes. This + terminates normal handling of the request, although an ErrorDocument may + be invoked to try to mop up, and it will be logged in any case.</li> + </ul> + + <p>Most phases are terminated by the first module that handles them; + however, for logging, `fixups', and non-access authentication checking, + all handlers always run (barring an error). Also, the response phase is + unique in that modules may declare multiple handlers for it, via a + dispatch table keyed on the MIME type of the requested object. Modules may + declare a response-phase handler which can handle <em>any</em> request, + by giving it the key <code>*/*</code> (<em>i.e.</em>, a wildcard MIME type + specification). However, wildcard handlers are only invoked if the server + has already tried and failed to find a more specific response handler for + the MIME type of the requested object (either none existed, or they all + declined).</p> + + <p>The handlers themselves are functions of one argument (a + <code>request_rec</code> structure. vide infra), which returns an integer, + as above.</p> + </section> + + <section id="moduletour"><title>A brief tour of a module</title> + <p>At this point, we need to explain the structure of a module. Our + candidate will be one of the messier ones, the CGI module -- this handles + both CGI scripts and the <directive module="mod_alias" + >ScriptAlias</directive> config file command. It's actually a great deal + more complicated than most modules, but if we're going to have only one + example, it might as well be the one with its fingers in every place.</p> + + <p>Let's begin with handlers. In order to handle the CGI scripts, the + module declares a response handler for them. Because of <directive + module="mod_alias">ScriptAlias</directive>, it also has handlers for the + name translation phase (to recognize <directive module="mod_alias" + >ScriptAlias</directive>ed URIs), the type-checking phase (any + <directive module="mod_alias">ScriptAlias</directive>ed request is typed + as a CGI script).</p> + + <p>The module needs to maintain some per (virtual) server information, + namely, the <directive module="mod_alias">ScriptAlias</directive>es in + effect; the module structure therefore contains pointers to a functions + which builds these structures, and to another which combines two of them + (in case the main server and a virtual server both have <directive + module="mod_alias">ScriptAlias</directive>es declared).</p> + + <p>Finally, this module contains code to handle the <directive + module="mod_alias">ScriptAlias</directive> command itself. This particular + module only declares one command, but there could be more, so modules have + <em>command tables</em> which declare their commands, and describe where + they are permitted, and how they are to be invoked.</p> + + <p>A final note on the declared types of the arguments of some of these + commands: a <code>pool</code> is a pointer to a <em>resource pool</em> + structure; these are used by the server to keep track of the memory which + has been allocated, files opened, <em>etc.</em>, either to service a + particular request, or to handle the process of configuring itself. That + way, when the request is over (or, for the configuration pool, when the + server is restarting), the memory can be freed, and the files closed, + <em>en masse</em>, without anyone having to write explicit code to track + them all down and dispose of them. Also, a <code>cmd_parms</code> + structure contains various information about the config file being read, + and other status information, which is sometimes of use to the function + which processes a config-file command (such as <directive + module="mod_alias">ScriptAlias</directive>). With no further ado, the + module itself:</p> + + <example> + /* Declarations of handlers. */<br /> + <br /> + int translate_scriptalias (request_rec *);<br /> + int type_scriptalias (request_rec *);<br /> + int cgi_handler (request_rec *);<br /> + <br /> + /* Subsidiary dispatch table for response-phase <br /> + * handlers, by MIME type */<br /> + <br /> + handler_rec cgi_handlers[] = {<br /> + <indent> + { "application/x-httpd-cgi", cgi_handler },<br /> + { NULL }<br /> + </indent> + };<br /> + <br /> + /* Declarations of routines to manipulate the <br /> + * module's configuration info. Note that these are<br /> + * returned, and passed in, as void *'s; the server<br /> + * core keeps track of them, but it doesn't, and can't,<br /> + * know their internal structure.<br /> + */<br /> + <br /> + void *make_cgi_server_config (pool *);<br /> + void *merge_cgi_server_config (pool *, void *, void *);<br /> + <br /> + /* Declarations of routines to handle config-file commands */<br /> + <br /> + extern char *script_alias(cmd_parms *, void *per_dir_config, char *fake, + char *real);<br /> + <br /> + command_rec cgi_cmds[] = {<br /> + <indent> + { "ScriptAlias", script_alias, NULL, RSRC_CONF, TAKE2,<br /> + <indent>"a fakename and a realname"},<br /></indent> + { NULL }<br /> + </indent> + };<br /> + <br /> + module cgi_module = { +<pre> STANDARD_MODULE_STUFF, + NULL, /* initializer */ + NULL, /* dir config creator */ + NULL, /* dir merger */ + make_cgi_server_config, /* server config */ + merge_cgi_server_config, /* merge server config */ + cgi_cmds, /* command table */ + cgi_handlers, /* handlers */ + translate_scriptalias, /* filename translation */ + NULL, /* check_user_id */ + NULL, /* check auth */ + NULL, /* check access */ + type_scriptalias, /* type_checker */ + NULL, /* fixups */ + NULL, /* logger */ + NULL /* header parser */ +};</pre> + </example> + </section> +</section> + +<section id="handlers"><title>How handlers work</title> + <p>The sole argument to handlers is a <code>request_rec</code> structure. + This structure describes a particular request which has been made to the + server, on behalf of a client. In most cases, each connection to the + client generates only one <code>request_rec</code> structure.</p> + + <section id="req_tour"><title>A brief tour of the request_rec</title> + <p>The <code>request_rec</code> contains pointers to a resource pool + which will be cleared when the server is finished handling the request; + to structures containing per-server and per-connection information, and + most importantly, information on the request itself.</p> + + <p>The most important such information is a small set of character strings + describing attributes of the object being requested, including its URI, + filename, content-type and content-encoding (these being filled in by the + translation and type-check handlers which handle the request, + respectively).</p> + + <p>Other commonly used data items are tables giving the MIME headers on + the client's original request, MIME headers to be sent back with the + response (which modules can add to at will), and environment variables for + any subprocesses which are spawned off in the course of servicing the + request. These tables are manipulated using the <code>ap_table_get</code> + and <code>ap_table_set</code> routines.</p> + + <note> + <p>Note that the <code>Content-type</code> header value <em>cannot</em> + be set by module content-handlers using the <code>ap_table_*()</code> + routines. Rather, it is set by pointing the <code>content_type</code> + field in the <code>request_rec</code> structure to an appropriate + string. <em>e.g.</em>,</p> + <example> + r->content_type = "text/html"; + </example> + </note> + + <p>Finally, there are pointers to two data structures which, in turn, + point to per-module configuration structures. Specifically, these hold + pointers to the data structures which the module has built to describe + the way it has been configured to operate in a given directory (via + <code>.htaccess</code> files or <directive type="section" module="core" + >Directory</directive> sections), for private data it has built in the + course of servicing the request (so modules' handlers for one phase can + pass `notes' to their handlers for other phases). There is another such + configuration vector in the <code>server_rec</code> data structure pointed + to by the <code>request_rec</code>, which contains per (virtual) server + configuration data.</p> + + <p>Here is an abridged declaration, giving the fields most commonly + used:</p> + + <example> + struct request_rec {<br /> + <br /> + pool *pool;<br /> + conn_rec *connection;<br /> + server_rec *server;<br /> + <br /> + /* What object is being requested */<br /> + <br /> + char *uri;<br /> + char *filename;<br /> + char *path_info; +<pre>char *args; /* QUERY_ARGS, if any */ +struct stat finfo; /* Set by server core; + * st_mode set to zero if no such file */</pre> + char *content_type;<br /> + char *content_encoding;<br /> + <br /> + /* MIME header environments, in and out. Also, <br /> + * an array containing environment variables to<br /> + * be passed to subprocesses, so people can write<br /> + * modules to add to that environment.<br /> + *<br /> + * The difference between headers_out and <br /> + * err_headers_out is that the latter are printed <br /> + * even on error, and persist across internal<br /> + * redirects (so the headers printed for <br /> + * <directive module="core">ErrorDocument</directive> handlers will have + them).<br /> + */<br /> + <br /> + table *headers_in;<br /> + table *headers_out;<br /> + table *err_headers_out;<br /> + table *subprocess_env;<br /> + <br /> + /* Info about the request itself... */<br /> + <br /> +<pre>int header_only; /* HEAD request, as opposed to GET */ +char *protocol; /* Protocol, as given to us, or HTTP/0.9 */ +char *method; /* GET, HEAD, POST, <em>etc.</em> */ +int method_number; /* M_GET, M_POST, <em>etc.</em> */</pre> + <br /> + /* Info for logging */<br /> + <br /> + char *the_request;<br /> + int bytes_sent;<br /> + <br /> + /* A flag which modules can set, to indicate that<br /> + * the data being returned is volatile, and clients<br /> + * should be told not to cache it.<br /> + */<br /> + <br /> + int no_cache;<br /> + <br /> + /* Various other config info which may change<br /> + * with .htaccess files<br /> + * These are config vectors, with one void*<br /> + * pointer for each module (the thing pointed<br /> + * to being the module's business).<br /> + */<br /> + <br /> +<pre>void *per_dir_config; /* Options set in config files, <em>etc.</em> */ +void *request_config; /* Notes on *this* request */</pre> + <br /> + }; + </example> + </section> + + <section id="req_orig"><title>Where request_rec structures come from</title> + <p>Most <code>request_rec</code> structures are built by reading an HTTP + request from a client, and filling in the fields. However, there are a + few exceptions:</p> + + <ul> + <li>If the request is to an imagemap, a type map (<em>i.e.</em>, a + <code>*.var</code> file), or a CGI script which returned a local + `Location:', then the resource which the user requested is going to be + ultimately located by some URI other than what the client originally + supplied. In this case, the server does an <em>internal redirect</em>, + constructing a new <code>request_rec</code> for the new URI, and + processing it almost exactly as if the client had requested the new URI + directly.</li> + + <li>If some handler signaled an error, and an <code>ErrorDocument</code> + is in scope, the same internal redirect machinery comes into play.</li> + + <li><p>Finally, a handler occasionally needs to investigate `what would + happen if' some other request were run. For instance, the directory + indexing module needs to know what MIME type would be assigned to a + request for each directory entry, in order to figure out what icon to + use.</p> + + <p>Such handlers can construct a <em>sub-request</em>, using the + functions <code>ap_sub_req_lookup_file</code>, + <code>ap_sub_req_lookup_uri</code>, and <code>ap_sub_req_method_uri</code>; + these construct a new <code>request_rec</code> structure and processes it + as you would expect, up to but not including the point of actually sending + a response. (These functions skip over the access checks if the + sub-request is for a file in the same directory as the original + request).</p> + + <p>(Server-side includes work by building sub-requests and then actually + invoking the response handler for them, via the function + <code>ap_run_sub_req</code>).</p> + </li> + </ul> + </section> + + <section id="req_return"><title>Handling requests, declining, and returning + error codes</title> + <p>As discussed above, each handler, when invoked to handle a particular + <code>request_rec</code>, has to return an <code>int</code> to indicate + what happened. That can either be</p> + + <ul> + <li><code>OK</code> -- the request was handled successfully. This may or + may not terminate the phase.</li> + + <li><code>DECLINED</code> -- no erroneous condition exists, but the module + declines to handle the phase; the server tries to find another.</li> + + <li>an HTTP error code, which aborts handling of the request.</li> + </ul> + + <p>Note that if the error code returned is <code>REDIRECT</code>, then + the module should put a <code>Location</code> in the request's + <code>headers_out</code>, to indicate where the client should be + redirected <em>to</em>.</p> + </section> + + <section id="resp_handlers"><title>Special considerations for response + handlers</title> + <p>Handlers for most phases do their work by simply setting a few fields + in the <code>request_rec</code> structure (or, in the case of access + checkers, simply by returning the correct error code). However, response + handlers have to actually send a request back to the client.</p> + + <p>They should begin by sending an HTTP response header, using the + function <code>ap_send_http_header</code>. (You don't have to do anything + special to skip sending the header for HTTP/0.9 requests; the function + figures out on its own that it shouldn't do anything). If the request is + marked <code>header_only</code>, that's all they should do; they should + return after that, without attempting any further output.</p> + + <p>Otherwise, they should produce a request body which responds to the + client as appropriate. The primitives for this are <code>ap_rputc</code> + and <code>ap_rprintf</code>, for internally generated output, and + <code>ap_send_fd</code>, to copy the contents of some <code>FILE *</code> + straight to the client.</p> + + <p>At this point, you should more or less understand the following piece + of code, which is the handler which handles <code>GET</code> requests + which have no more specific handler; it also shows how conditional + <code>GET</code>s can be handled, if it's desirable to do so in a + particular response handler -- <code>ap_set_last_modified</code> checks + against the <code>If-modified-since</code> value supplied by the client, + if any, and returns an appropriate code (which will, if nonzero, be + USE_LOCAL_COPY). No similar considerations apply for + <code>ap_set_content_length</code>, but it returns an error code for + symmetry.</p> + + <example> + int default_handler (request_rec *r)<br /> + {<br /> + <indent> + int errstatus;<br /> + FILE *f;<br /> + <br /> + if (r->method_number != M_GET) return DECLINED;<br /> + if (r->finfo.st_mode == 0) return NOT_FOUND;<br /> + <br /> + if ((errstatus = ap_set_content_length (r, r->finfo.st_size))<br /> + || + (errstatus = ap_set_last_modified (r, r->finfo.st_mtime)))<br /> + return errstatus;<br /> + <br /> + f = fopen (r->filename, "r");<br /> + <br /> + if (f == NULL) {<br /> + <indent> + log_reason("file permissions deny server access", r->filename, r);<br /> + return FORBIDDEN;<br /> + </indent> + }<br /> + <br /> + register_timeout ("send", r);<br /> + ap_send_http_header (r);<br /> + <br /> + if (!r->header_only) send_fd (f, r);<br /> + ap_pfclose (r->pool, f);<br /> + return OK;<br /> + </indent> + } + </example> + + <p>Finally, if all of this is too much of a challenge, there are a few + ways out of it. First off, as shown above, a response handler which has + not yet produced any output can simply return an error code, in which + case the server will automatically produce an error response. Secondly, + it can punt to some other handler by invoking + <code>ap_internal_redirect</code>, which is how the internal redirection + machinery discussed above is invoked. A response handler which has + internally redirected should always return <code>OK</code>.</p> + + <p>(Invoking <code>ap_internal_redirect</code> from handlers which are + <em>not</em> response handlers will lead to serious confusion).</p> + </section> + + <section id="auth_handlers"><title>Special considerations for authentication + handlers</title> + <p>Stuff that should be discussed here in detail:</p> + + <ul> + <li>Authentication-phase handlers not invoked unless auth is + configured for the directory.</li> + + <li>Common auth configuration stored in the core per-dir + configuration; it has accessors <code>ap_auth_type</code>, + <code>ap_auth_name</code>, and <code>ap_requires</code>.</li> + + <li>Common routines, to handle the protocol end of things, at + least for HTTP basic authentication + (<code>ap_get_basic_auth_pw</code>, which sets the + <code>connection->user</code> structure field + automatically, and <code>ap_note_basic_auth_failure</code>, + which arranges for the proper <code>WWW-Authenticate:</code> + header to be sent back).</li> + </ul> + </section> + + <section id="log_handlers"><title>Special considerations for logging + handlers</title> + <p>When a request has internally redirected, there is the question of + what to log. Apache handles this by bundling the entire chain of redirects + into a list of <code>request_rec</code> structures which are threaded + through the <code>r->prev</code> and <code>r->next</code> pointers. + The <code>request_rec</code> which is passed to the logging handlers in + such cases is the one which was originally built for the initial request + from the client; note that the <code>bytes_sent</code> field will only be + correct in the last request in the chain (the one for which a response was + actually sent).</p> + </section> +</section> + +<section id="pools"><title>Resource allocation and resource pools</title> + <p>One of the problems of writing and designing a server-pool server is + that of preventing leakage, that is, allocating resources (memory, open + files, <em>etc.</em>), without subsequently releasing them. The resource + pool machinery is designed to make it easy to prevent this from happening, + by allowing resource to be allocated in such a way that they are + <em>automatically</em> released when the server is done with them.</p> + + <p>The way this works is as follows: the memory which is allocated, file + opened, <em>etc.</em>, to deal with a particular request are tied to a + <em>resource pool</em> which is allocated for the request. The pool is a + data structure which itself tracks the resources in question.</p> + + <p>When the request has been processed, the pool is <em>cleared</em>. At + that point, all the memory associated with it is released for reuse, all + files associated with it are closed, and any other clean-up functions which + are associated with the pool are run. When this is over, we can be confident + that all the resource tied to the pool have been released, and that none of + them have leaked.</p> + + <p>Server restarts, and allocation of memory and resources for per-server + configuration, are handled in a similar way. There is a <em>configuration + pool</em>, which keeps track of resources which were allocated while reading + the server configuration files, and handling the commands therein (for + instance, the memory that was allocated for per-server module configuration, + log files and other files that were opened, and so forth). When the server + restarts, and has to reread the configuration files, the configuration pool + is cleared, and so the memory and file descriptors which were taken up by + reading them the last time are made available for reuse.</p> + + <p>It should be noted that use of the pool machinery isn't generally + obligatory, except for situations like logging handlers, where you really + need to register cleanups to make sure that the log file gets closed when + the server restarts (this is most easily done by using the function <code><a + href="#pool-files">ap_pfopen</a></code>, which also arranges for the + underlying file descriptor to be closed before any child processes, such as + for CGI scripts, are <code>exec</code>ed), or in case you are using the + timeout machinery (which isn't yet even documented here). However, there are + two benefits to using it: resources allocated to a pool never leak (even if + you allocate a scratch string, and just forget about it); also, for memory + allocation, <code>ap_palloc</code> is generally faster than + <code>malloc</code>.</p> + + <p>We begin here by describing how memory is allocated to pools, and then + discuss how other resources are tracked by the resource pool machinery.</p> + + <section><title>Allocation of memory in pools</title> + <p>Memory is allocated to pools by calling the function + <code>ap_palloc</code>, which takes two arguments, one being a pointer to + a resource pool structure, and the other being the amount of memory to + allocate (in <code>char</code>s). Within handlers for handling requests, + the most common way of getting a resource pool structure is by looking at + the <code>pool</code> slot of the relevant <code>request_rec</code>; hence + the repeated appearance of the following idiom in module code:</p> + + <example> + int my_handler(request_rec *r)<br /> + {<br /> + <indent> + struct my_structure *foo;<br /> + ...<br /> + <br /> + foo = (foo *)ap_palloc (r->pool, sizeof(my_structure));<br /> + </indent> + } + </example> + + <p>Note that <em>there is no <code>ap_pfree</code></em> -- + <code>ap_palloc</code>ed memory is freed only when the associated resource + pool is cleared. This means that <code>ap_palloc</code> does not have to + do as much accounting as <code>malloc()</code>; all it does in the typical + case is to round up the size, bump a pointer, and do a range check.</p> + + <p>(It also raises the possibility that heavy use of + <code>ap_palloc</code> could cause a server process to grow excessively + large. There are two ways to deal with this, which are dealt with below; + briefly, you can use <code>malloc</code>, and try to be sure that all of + the memory gets explicitly <code>free</code>d, or you can allocate a + sub-pool of the main pool, allocate your memory in the sub-pool, and clear + it out periodically. The latter technique is discussed in the section + on sub-pools below, and is used in the directory-indexing code, in order + to avoid excessive storage allocation when listing directories with + thousands of files).</p> + </section> + + <section><title>Allocating initialized memory</title> + <p>There are functions which allocate initialized memory, and are + frequently useful. The function <code>ap_pcalloc</code> has the same + interface as <code>ap_palloc</code>, but clears out the memory it + allocates before it returns it. The function <code>ap_pstrdup</code> + takes a resource pool and a <code>char *</code> as arguments, and + allocates memory for a copy of the string the pointer points to, returning + a pointer to the copy. Finally <code>ap_pstrcat</code> is a varargs-style + function, which takes a pointer to a resource pool, and at least two + <code>char *</code> arguments, the last of which must be + <code>NULL</code>. It allocates enough memory to fit copies of each of + the strings, as a unit; for instance:</p> + + <example> + ap_pstrcat (r->pool, "foo", "/", "bar", NULL); + </example> + + <p>returns a pointer to 8 bytes worth of memory, initialized to + <code>"foo/bar"</code>.</p> + </section> + + <section id="pools-used"><title>Commonly-used pools in the Apache Web + server</title> + <p>A pool is really defined by its lifetime more than anything else. + There are some static pools in http_main which are passed to various + non-http_main functions as arguments at opportune times. Here they + are:</p> + + <dl> + <dt><code>permanent_pool</code></dt> + <dd>never passed to anything else, this is the ancestor of all pools</dd> + + <dt><code>pconf</code></dt> + <dd> + <ul> + <li>subpool of permanent_pool</li> + + <li>created at the beginning of a config "cycle"; exists + until the server is terminated or restarts; passed to all + config-time routines, either via cmd->pool, or as the + "pool *p" argument on those which don't take pools</li> + + <li>passed to the module init() functions</li> + </ul> + </dd> + + <dt><code>ptemp</code></dt> + <dd> + <ul> + <li>sorry I lie, this pool isn't called this currently in + 1.3, I renamed it this in my pthreads development. I'm + referring to the use of ptrans in the parent... contrast + this with the later definition of ptrans in the + child.</li> + + <li>subpool of permanent_pool</li> + + <li>created at the beginning of a config "cycle"; exists + until the end of config parsing; passed to config-time + routines <em>via</em> cmd->temp_pool. Somewhat of a + "bastard child" because it isn't available everywhere. + Used for temporary scratch space which may be needed by + some config routines but which is deleted at the end of + config.</li> + </ul> + </dd> + + <dt><code>pchild</code></dt> + <dd> + <ul> + <li>subpool of permanent_pool</li> + + <li>created when a child is spawned (or a thread is + created); lives until that child (thread) is + destroyed</li> + + <li>passed to the module child_init functions</li> + + <li>destruction happens right after the child_exit + functions are called... (which may explain why I think + child_exit is redundant and unneeded)</li> + </ul> + </dd> + + <dt><code>ptrans</code></dt> + <dd> + <ul> + <li>should be a subpool of pchild, but currently is a + subpool of permanent_pool, see above</li> + + <li>cleared by the child before going into the accept() + loop to receive a connection</li> + + <li>used as connection->pool</li> + </ul> + </dd> + + <dt><code>r->pool</code></dt> + <dd> + <ul> + <li>for the main request this is a subpool of + connection->pool; for subrequests it is a subpool of + the parent request's pool.</li> + + <li>exists until the end of the request (<em>i.e.</em>, + ap_destroy_sub_req, or in child_main after + process_request has finished)</li> + + <li>note that r itself is allocated from r->pool; + <em>i.e.</em>, r->pool is first created and then r is + the first thing palloc()d from it</li> + </ul> + </dd> + </dl> + + <p>For almost everything folks do, <code>r->pool</code> is the pool to + use. But you can see how other lifetimes, such as pchild, are useful to + some modules... such as modules that need to open a database connection + once per child, and wish to clean it up when the child dies.</p> + + <p>You can also see how some bugs have manifested themself, such as + setting <code>connection->user</code> to a value from + <code>r->pool</code> -- in this case connection exists for the + lifetime of <code>ptrans</code>, which is longer than + <code>r->pool</code> (especially if <code>r->pool</code> is a + subrequest!). So the correct thing to do is to allocate from + <code>connection->pool</code>.</p> + + <p>And there was another interesting bug in <module>mod_include</module> + / <module>mod_cgi</module>. You'll see in those that they do this test + to decide if they should use <code>r->pool</code> or + <code>r->main->pool</code>. In this case the resource that they are + registering for cleanup is a child process. If it were registered in + <code>r->pool</code>, then the code would <code>wait()</code> for the + child when the subrequest finishes. With <module>mod_include</module> this + could be any old <code>#include</code>, and the delay can be up to 3 + seconds... and happened quite frequently. Instead the subprocess is + registered in <code>r->main->pool</code> which causes it to be + cleaned up when the entire request is done -- <em>i.e.</em>, after the + output has been sent to the client and logging has happened.</p> + </section> + + <section id="pool-files"><title>Tracking open files, etc.</title> + <p>As indicated above, resource pools are also used to track other sorts + of resources besides memory. The most common are open files. The routine + which is typically used for this is <code>ap_pfopen</code>, which takes a + resource pool and two strings as arguments; the strings are the same as + the typical arguments to <code>fopen</code>, <em>e.g.</em>,</p> + + <example> + ...<br /> + FILE *f = ap_pfopen (r->pool, r->filename, "r");<br /> + <br /> + if (f == NULL) { ... } else { ... }<br /> + </example> + + <p>There is also a <code>ap_popenf</code> routine, which parallels the + lower-level <code>open</code> system call. Both of these routines arrange + for the file to be closed when the resource pool in question is + cleared.</p> + + <p>Unlike the case for memory, there <em>are</em> functions to close files + allocated with <code>ap_pfopen</code>, and <code>ap_popenf</code>, namely + <code>ap_pfclose</code> and <code>ap_pclosef</code>. (This is because, on + many systems, the number of files which a single process can have open is + quite limited). It is important to use these functions to close files + allocated with <code>ap_pfopen</code> and <code>ap_popenf</code>, since to + do otherwise could cause fatal errors on systems such as Linux, which + react badly if the same <code>FILE*</code> is closed more than once.</p> + + <p>(Using the <code>close</code> functions is not mandatory, since the + file will eventually be closed regardless, but you should consider it in + cases where your module is opening, or could open, a lot of files).</p> + </section> + + <section><title>Other sorts of resources -- cleanup functions</title> + <p>More text goes here. Describe the the cleanup primitives in terms of + which the file stuff is implemented; also, <code>spawn_process</code>.</p> + + <p>Pool cleanups live until <code>clear_pool()</code> is called: + <code>clear_pool(a)</code> recursively calls <code>destroy_pool()</code> + on all subpools of <code>a</code>; then calls all the cleanups for + <code>a</code>; then releases all the memory for <code>a</code>. + <code>destroy_pool(a)</code> calls <code>clear_pool(a)</code> and then + releases the pool structure itself. <em>i.e.</em>, + <code>clear_pool(a)</code> doesn't delete <code>a</code>, it just frees + up all the resources and you can start using it again immediately.</p> + </section> + + <section><title>Fine control -- creating and dealing with sub-pools, with + a note on sub-requests</title> + <p>On rare occasions, too-free use of <code>ap_palloc()</code> and the + associated primitives may result in undesirably profligate resource + allocation. You can deal with such a case by creating a <em>sub-pool</em>, + allocating within the sub-pool rather than the main pool, and clearing or + destroying the sub-pool, which releases the resources which were + associated with it. (This really <em>is</em> a rare situation; the only + case in which it comes up in the standard module set is in case of listing + directories, and then only with <em>very</em> large directories. + Unnecessary use of the primitives discussed here can hair up your code + quite a bit, with very little gain).</p> + + <p>The primitive for creating a sub-pool is <code>ap_make_sub_pool</code>, + which takes another pool (the parent pool) as an argument. When the main + pool is cleared, the sub-pool will be destroyed. The sub-pool may also be + cleared or destroyed at any time, by calling the functions + <code>ap_clear_pool</code> and <code>ap_destroy_pool</code>, respectively. + (The difference is that <code>ap_clear_pool</code> frees resources + associated with the pool, while <code>ap_destroy_pool</code> also + deallocates the pool itself. In the former case, you can allocate new + resources within the pool, and clear it again, and so forth; in the + latter case, it is simply gone).</p> + + <p>One final note -- sub-requests have their own resource pools, which are + sub-pools of the resource pool for the main request. The polite way to + reclaim the resources associated with a sub request which you have + allocated (using the <code>ap_sub_req_...</code> functions) is + <code>ap_destroy_sub_req</code>, which frees the resource pool. Before + calling this function, be sure to copy anything that you care about which + might be allocated in the sub-request's resource pool into someplace a + little less volatile (for instance, the filename in its + <code>request_rec</code> structure).</p> + + <p>(Again, under most circumstances, you shouldn't feel obliged to call + this function; only 2K of memory or so are allocated for a typical sub + request, and it will be freed anyway when the main request pool is + cleared. It is only when you are allocating many, many sub-requests for a + single main request that you should seriously consider the + <code>ap_destroy_...</code> functions).</p> + </section> +</section> + +<section id="config"><title>Configuration, commands and the like</title> + <p>One of the design goals for this server was to maintain external + compatibility with the NCSA 1.3 server --- that is, to read the same + configuration files, to process all the directives therein correctly, and + in general to be a drop-in replacement for NCSA. On the other hand, another + design goal was to move as much of the server's functionality into modules + which have as little as possible to do with the monolithic server core. The + only way to reconcile these goals is to move the handling of most commands + from the central server into the modules.</p> + + <p>However, just giving the modules command tables is not enough to divorce + them completely from the server core. The server has to remember the + commands in order to act on them later. That involves maintaining data which + is private to the modules, and which can be either per-server, or + per-directory. Most things are per-directory, including in particular access + control and authorization information, but also information on how to + determine file types from suffixes, which can be modified by + <directive module="mod_mime">AddType</directive> and <directive + module="core">DefaultType</directive> directives, and so forth. In general, + the governing philosophy is that anything which <em>can</em> be made + configurable by directory should be; per-server information is generally + used in the standard set of modules for information like + <directive module="mod_alias">Alias</directive>es and <directive + module="mod_alias">Redirect</directive>s which come into play before the + request is tied to a particular place in the underlying file system.</p> + + <p>Another requirement for emulating the NCSA server is being able to handle + the per-directory configuration files, generally called + <code>.htaccess</code> files, though even in the NCSA server they can + contain directives which have nothing at all to do with access control. + Accordingly, after URI -> filename translation, but before performing any + other phase, the server walks down the directory hierarchy of the underlying + filesystem, following the translated pathname, to read any + <code>.htaccess</code> files which might be present. The information which + is read in then has to be <em>merged</em> with the applicable information + from the server's own config files (either from the <directive + type="section" module="core">Directory</directive> sections in + <code>access.conf</code>, or from defaults in <code>srm.conf</code>, which + actually behaves for most purposes almost exactly like <code><Directory + /></code>).</p> + + <p>Finally, after having served a request which involved reading + <code>.htaccess</code> files, we need to discard the storage allocated for + handling them. That is solved the same way it is solved wherever else + similar problems come up, by tying those structures to the per-transaction + resource pool.</p> + + <section id="per-dir"><title>Per-directory configuration structures</title> + <p>Let's look out how all of this plays out in <code>mod_mime.c</code>, + which defines the file typing handler which emulates the NCSA server's + behavior of determining file types from suffixes. What we'll be looking + at, here, is the code which implements the <directive module="mod_mime" + >AddType</directive> and <directive module="mod_mime" + >AddEncoding</directive> commands. These commands can appear in + <code>.htaccess</code> files, so they must be handled in the module's + private per-directory data, which in fact, consists of two separate + tables for MIME types and encoding information, and is declared as + follows:</p> + + <example> +<pre>typedef struct { + table *forced_types; /* Additional AddTyped stuff */ + table *encoding_types; /* Added with AddEncoding... */ +} mime_dir_config;</pre> + </example> + + <p>When the server is reading a configuration file, or <directive + type="section" module="core">Directory</directive> section, which includes + one of the MIME module's commands, it needs to create a + <code>mime_dir_config</code> structure, so those commands have something + to act on. It does this by invoking the function it finds in the module's + `create per-dir config slot', with two arguments: the name of the + directory to which this configuration information applies (or + <code>NULL</code> for <code>srm.conf</code>), and a pointer to a + resource pool in which the allocation should happen.</p> + + <p>(If we are reading a <code>.htaccess</code> file, that resource pool + is the per-request resource pool for the request; otherwise it is a + resource pool which is used for configuration data, and cleared on + restarts. Either way, it is important for the structure being created to + vanish when the pool is cleared, by registering a cleanup on the pool if + necessary).</p> + + <p>For the MIME module, the per-dir config creation function just + <code>ap_palloc</code>s the structure above, and a creates a couple of + tables to fill it. That looks like this:</p> + + <example> + void *create_mime_dir_config (pool *p, char *dummy)<br /> + {<br /> + <indent> + mime_dir_config *new =<br /> + <indent> + (mime_dir_config *) ap_palloc (p, sizeof(mime_dir_config));<br /> + </indent> + <br /> + new->forced_types = ap_make_table (p, 4);<br /> + new->encoding_types = ap_make_table (p, 4);<br /> + <br /> + return new;<br /> + </indent> + } + </example> + + <p>Now, suppose we've just read in a <code>.htaccess</code> file. We + already have the per-directory configuration structure for the next + directory up in the hierarchy. If the <code>.htaccess</code> file we just + read in didn't have any <directive module="mod_mime">AddType</directive> + or <directive module="mod_mime">AddEncoding</directive> commands, its + per-directory config structure for the MIME module is still valid, and we + can just use it. Otherwise, we need to merge the two structures + somehow.</p> + + <p>To do that, the server invokes the module's per-directory config merge + function, if one is present. That function takes three arguments: the two + structures being merged, and a resource pool in which to allocate the + result. For the MIME module, all that needs to be done is overlay the + tables from the new per-directory config structure with those from the + parent:</p> + + <example> + void *merge_mime_dir_configs (pool *p, void *parent_dirv, void *subdirv)<br /> + {<br /> + <indent> + mime_dir_config *parent_dir = (mime_dir_config *)parent_dirv;<br /> + mime_dir_config *subdir = (mime_dir_config *)subdirv;<br /> + mime_dir_config *new =<br /> + <indent> + (mime_dir_config *)ap_palloc (p, sizeof(mime_dir_config));<br /> + </indent> + <br /> + new->forced_types = ap_overlay_tables (p, subdir->forced_types,<br /> + <indent> + parent_dir->forced_types);<br /> + </indent> + new->encoding_types = ap_overlay_tables (p, subdir->encoding_types,<br /> + <indent> + parent_dir->encoding_types);<br /> + </indent> + <br /> + return new;<br /> + </indent> + } + </example> + + <p>As a note -- if there is no per-directory merge function present, the + server will just use the subdirectory's configuration info, and ignore + the parent's. For some modules, that works just fine (<em>e.g.</em>, for + the includes module, whose per-directory configuration information + consists solely of the state of the <code>XBITHACK</code>), and for those + modules, you can just not declare one, and leave the corresponding + structure slot in the module itself <code>NULL</code>.</p> + </section> + + <section id="commands"><title>Command handling</title> + <p>Now that we have these structures, we need to be able to figure out how + to fill them. That involves processing the actual <directive + module="mod_mime">AddType</directive> and <directive module="mod_mime" + >AddEncoding</directive> commands. To find commands, the server looks in + the module's command table. That table contains information on how many + arguments the commands take, and in what formats, where it is permitted, + and so forth. That information is sufficient to allow the server to invoke + most command-handling functions with pre-parsed arguments. Without further + ado, let's look at the <directive module="mod_mime">AddType</directive> + command handler, which looks like this (the <directive module="mod_mime" + >AddEncoding</directive> command looks basically the same, and won't be + shown here):</p> + + <example> + char *add_type(cmd_parms *cmd, mime_dir_config *m, char *ct, char *ext)<br /> + {<br /> + <indent> + if (*ext == '.') ++ext;<br /> + ap_table_set (m->forced_types, ext, ct);<br /> + return NULL;<br /> + </indent> + } + </example> + + <p>This command handler is unusually simple. As you can see, it takes + four arguments, two of which are pre-parsed arguments, the third being the + per-directory configuration structure for the module in question, and the + fourth being a pointer to a <code>cmd_parms</code> structure. That + structure contains a bunch of arguments which are frequently of use to + some, but not all, commands, including a resource pool (from which memory + can be allocated, and to which cleanups should be tied), and the (virtual) + server being configured, from which the module's per-server configuration + data can be obtained if required.</p> + + <p>Another way in which this particular command handler is unusually + simple is that there are no error conditions which it can encounter. If + there were, it could return an error message instead of <code>NULL</code>; + this causes an error to be printed out on the server's + <code>stderr</code>, followed by a quick exit, if it is in the main config + files; for a <code>.htaccess</code> file, the syntax error is logged in + the server error log (along with an indication of where it came from), and + the request is bounced with a server error response (HTTP error status, + code 500).</p> + + <p>The MIME module's command table has entries for these commands, which + look like this:</p> + + <example> + command_rec mime_cmds[] = {<br /> + <indent> + { "AddType", add_type, NULL, OR_FILEINFO, TAKE2,<br /> + <indent>"a mime type followed by a file extension" },<br /></indent> + { "AddEncoding", add_encoding, NULL, OR_FILEINFO, TAKE2,<br /> + <indent> + "an encoding (<em>e.g.</em>, gzip), followed by a file extension" },<br /> + </indent> + { NULL }<br /> + </indent> + }; + </example> + + <p>The entries in these tables are:</p> + <ul> + <li>The name of the command</li> + <li>The function which handles it</li> + <li>a <code>(void *)</code> pointer, which is passed in the + <code>cmd_parms</code> structure to the command handler --- + this is useful in case many similar commands are handled by + the same function.</li> + + <li>A bit mask indicating where the command may appear. There + are mask bits corresponding to each + <code>AllowOverride</code> option, and an additional mask + bit, <code>RSRC_CONF</code>, indicating that the command may + appear in the server's own config files, but <em>not</em> in + any <code>.htaccess</code> file.</li> + + <li>A flag indicating how many arguments the command handler + wants pre-parsed, and how they should be passed in. + <code>TAKE2</code> indicates two pre-parsed arguments. Other + options are <code>TAKE1</code>, which indicates one + pre-parsed argument, <code>FLAG</code>, which indicates that + the argument should be <code>On</code> or <code>Off</code>, + and is passed in as a boolean flag, <code>RAW_ARGS</code>, + which causes the server to give the command the raw, unparsed + arguments (everything but the command name itself). There is + also <code>ITERATE</code>, which means that the handler looks + the same as <code>TAKE1</code>, but that if multiple + arguments are present, it should be called multiple times, + and finally <code>ITERATE2</code>, which indicates that the + command handler looks like a <code>TAKE2</code>, but if more + arguments are present, then it should be called multiple + times, holding the first argument constant.</li> + + <li>Finally, we have a string which describes the arguments + that should be present. If the arguments in the actual config + file are not as required, this string will be used to help + give a more specific error message. (You can safely leave + this <code>NULL</code>).</li> + </ul> + + <p>Finally, having set this all up, we have to use it. This is ultimately + done in the module's handlers, specifically for its file-typing handler, + which looks more or less like this; note that the per-directory + configuration structure is extracted from the <code>request_rec</code>'s + per-directory configuration vector by using the + <code>ap_get_module_config</code> function.</p> + + <example> + int find_ct(request_rec *r)<br /> + {<br /> + <indent> + int i;<br /> + char *fn = ap_pstrdup (r->pool, r->filename);<br /> + mime_dir_config *conf = (mime_dir_config *)<br /> + <indent> + ap_get_module_config(r->per_dir_config, &mime_module);<br /> + </indent> + char *type;<br /> + <br /> + if (S_ISDIR(r->finfo.st_mode)) {<br /> + <indent> + r->content_type = DIR_MAGIC_TYPE;<br /> + return OK;<br /> + </indent> + }<br /> + <br /> + if((i=ap_rind(fn,'.')) < 0) return DECLINED;<br /> + ++i;<br /> + <br /> + if ((type = ap_table_get (conf->encoding_types, &fn[i])))<br /> + {<br /> + <indent> + r->content_encoding = type;<br /> + <br /> + /* go back to previous extension to try to use it as a type */<br /> + fn[i-1] = '\0';<br /> + if((i=ap_rind(fn,'.')) < 0) return OK;<br /> + ++i;<br /> + </indent> + }<br /> + <br /> + if ((type = ap_table_get (conf->forced_types, &fn[i])))<br /> + {<br /> + <indent> + r->content_type = type;<br /> + </indent> + }<br /> + <br /> + return OK; + </indent> + } + </example> + </section> + + <section id="servconf"><title>Side notes -- per-server configuration, + virtual servers, <em>etc</em>.</title> + <p>The basic ideas behind per-server module configuration are basically + the same as those for per-directory configuration; there is a creation + function and a merge function, the latter being invoked where a virtual + server has partially overridden the base server configuration, and a + combined structure must be computed. (As with per-directory configuration, + the default if no merge function is specified, and a module is configured + in some virtual server, is that the base configuration is simply + ignored).</p> + + <p>The only substantial difference is that when a command needs to + configure the per-server private module data, it needs to go to the + <code>cmd_parms</code> data to get at it. Here's an example, from the + alias module, which also indicates how a syntax error can be returned + (note that the per-directory configuration argument to the command + handler is declared as a dummy, since the module doesn't actually have + per-directory config data):</p> + + <example> + char *add_redirect(cmd_parms *cmd, void *dummy, char *f, char *url)<br /> + {<br /> + <indent> + server_rec *s = cmd->server;<br /> + alias_server_conf *conf = (alias_server_conf *)<br /> + <indent> + ap_get_module_config(s->module_config,&alias_module);<br /> + </indent> + alias_entry *new = ap_push_array (conf->redirects);<br /> + <br /> + if (!ap_is_url (url)) return "Redirect to non-URL";<br /> + <br /> + new->fake = f; new->real = url;<br /> + return NULL;<br /> + </indent> + } + </example> + </section> +</section> + +</manualpage>
\ No newline at end of file diff --git a/docs/manual/developer/API.xml.meta b/docs/manual/developer/API.xml.meta new file mode 100644 index 0000000000..6fd15b2013 --- /dev/null +++ b/docs/manual/developer/API.xml.meta @@ -0,0 +1,11 @@ +<?xml version="1.0" encoding="UTF-8" ?> + +<metafile> + <basename>API</basename> + <path>/developer/</path> + <relpath>..</relpath> + + <variants> + <variant>en</variant> + </variants> +</metafile> diff --git a/docs/manual/developer/footer.html b/docs/manual/developer/footer.html deleted file mode 100644 index bc5fea53d8..0000000000 --- a/docs/manual/developer/footer.html +++ /dev/null @@ -1,7 +0,0 @@ - <hr /> - - <h3 align="center">Apache HTTP Server Version 2.1</h3> - <a href="./"><img src="../images/index.gif" alt="Index" /></a> - <a href="../"><img src="../images/home.gif" alt="Home" /></a> - - diff --git a/docs/manual/developer/header.html b/docs/manual/developer/header.html deleted file mode 100644 index 3c93b3dce8..0000000000 --- a/docs/manual/developer/header.html +++ /dev/null @@ -1,6 +0,0 @@ - <div align="center"> - <img src="../images/sub.gif" alt="[APACHE DOCUMENTATION]" /> - - <h3>Apache HTTP Server Version 2.1</h3> - </div> - diff --git a/docs/manual/faq/footer.html b/docs/manual/faq/footer.html deleted file mode 100644 index 4f899094b5..0000000000 --- a/docs/manual/faq/footer.html +++ /dev/null @@ -1,6 +0,0 @@ - <hr /> - - <h3 align="center">Apache HTTP Server Version 2.1</h3> - <a href="./"><img src="../images/index.gif" alt="Index" /></a> - <a href="../"><img src="../images/home.gif" alt="Home" /></a> - diff --git a/docs/manual/faq/header.html b/docs/manual/faq/header.html deleted file mode 100644 index 7150a227f3..0000000000 --- a/docs/manual/faq/header.html +++ /dev/null @@ -1,7 +0,0 @@ - <div align="center"> - <img src="../images/sub.gif" alt="[APACHE DOCUMENTATION]" /> - - <h3>Apache HTTP Server Version 2.1</h3> - </div> - - diff --git a/docs/manual/footer.html b/docs/manual/footer.html deleted file mode 100644 index 438f2f81c8..0000000000 --- a/docs/manual/footer.html +++ /dev/null @@ -1,6 +0,0 @@ - <hr /> - - <h3 align="center">Apache HTTP Server Version 2.1</h3> - <a href="./"><img src="images/index.gif" alt="Index" /></a> - - diff --git a/docs/manual/header.html b/docs/manual/header.html deleted file mode 100644 index f2e5f1ad4c..0000000000 --- a/docs/manual/header.html +++ /dev/null @@ -1,7 +0,0 @@ - <div align="center"> - <img src="images/sub.gif" alt="[APACHE DOCUMENTATION]" /> - - <h3>Apache HTTP Server Version 2.1</h3> - </div> - - diff --git a/docs/manual/howto/footer.html b/docs/manual/howto/footer.html deleted file mode 100644 index bc5fea53d8..0000000000 --- a/docs/manual/howto/footer.html +++ /dev/null @@ -1,7 +0,0 @@ - <hr /> - - <h3 align="center">Apache HTTP Server Version 2.1</h3> - <a href="./"><img src="../images/index.gif" alt="Index" /></a> - <a href="../"><img src="../images/home.gif" alt="Home" /></a> - - diff --git a/docs/manual/howto/header.html b/docs/manual/howto/header.html deleted file mode 100644 index 3c93b3dce8..0000000000 --- a/docs/manual/howto/header.html +++ /dev/null @@ -1,6 +0,0 @@ - <div align="center"> - <img src="../images/sub.gif" alt="[APACHE DOCUMENTATION]" /> - - <h3>Apache HTTP Server Version 2.1</h3> - </div> - diff --git a/docs/manual/mod/footer.html b/docs/manual/mod/footer.html deleted file mode 100644 index 4f899094b5..0000000000 --- a/docs/manual/mod/footer.html +++ /dev/null @@ -1,6 +0,0 @@ - <hr /> - - <h3 align="center">Apache HTTP Server Version 2.1</h3> - <a href="./"><img src="../images/index.gif" alt="Index" /></a> - <a href="../"><img src="../images/home.gif" alt="Home" /></a> - diff --git a/docs/manual/mod/header.html b/docs/manual/mod/header.html deleted file mode 100644 index 3c93b3dce8..0000000000 --- a/docs/manual/mod/header.html +++ /dev/null @@ -1,6 +0,0 @@ - <div align="center"> - <img src="../images/sub.gif" alt="[APACHE DOCUMENTATION]" /> - - <h3>Apache HTTP Server Version 2.1</h3> - </div> - diff --git a/docs/manual/platform/footer.html b/docs/manual/platform/footer.html deleted file mode 100644 index 4f899094b5..0000000000 --- a/docs/manual/platform/footer.html +++ /dev/null @@ -1,6 +0,0 @@ - <hr /> - - <h3 align="center">Apache HTTP Server Version 2.1</h3> - <a href="./"><img src="../images/index.gif" alt="Index" /></a> - <a href="../"><img src="../images/home.gif" alt="Home" /></a> - diff --git a/docs/manual/platform/header.html b/docs/manual/platform/header.html deleted file mode 100644 index 3c93b3dce8..0000000000 --- a/docs/manual/platform/header.html +++ /dev/null @@ -1,6 +0,0 @@ - <div align="center"> - <img src="../images/sub.gif" alt="[APACHE DOCUMENTATION]" /> - - <h3>Apache HTTP Server Version 2.1</h3> - </div> - diff --git a/docs/manual/ssl/footer.html b/docs/manual/ssl/footer.html deleted file mode 100644 index bc5fea53d8..0000000000 --- a/docs/manual/ssl/footer.html +++ /dev/null @@ -1,7 +0,0 @@ - <hr /> - - <h3 align="center">Apache HTTP Server Version 2.1</h3> - <a href="./"><img src="../images/index.gif" alt="Index" /></a> - <a href="../"><img src="../images/home.gif" alt="Home" /></a> - - diff --git a/docs/manual/ssl/header.html b/docs/manual/ssl/header.html deleted file mode 100644 index 3c93b3dce8..0000000000 --- a/docs/manual/ssl/header.html +++ /dev/null @@ -1,6 +0,0 @@ - <div align="center"> - <img src="../images/sub.gif" alt="[APACHE DOCUMENTATION]" /> - - <h3>Apache HTTP Server Version 2.1</h3> - </div> - diff --git a/docs/manual/style/chm/hhc.xsl b/docs/manual/style/chm/hhc.xsl index 980df7861c..965279bd4c 100644 --- a/docs/manual/style/chm/hhc.xsl +++ b/docs/manual/style/chm/hhc.xsl @@ -83,7 +83,7 @@ <xsl:template name="data"> <!-- documents not converted (yet?). --> <not-exists> - <file>developer/API.xml</file> +<!-- example: <file>developer/API.xml</file> --> </not-exists> </xsl:template> diff --git a/docs/manual/vhosts/footer.html b/docs/manual/vhosts/footer.html deleted file mode 100644 index a418ad44c6..0000000000 --- a/docs/manual/vhosts/footer.html +++ /dev/null @@ -1,5 +0,0 @@ - <hr /> - - <h3 align="center">Apache HTTP Server Version 2.1</h3> - <a href="./"><img src="../images/index.gif" alt="Index" /></a> - <a href="../"><img src="../images/home.gif" alt="Home" /></a> diff --git a/docs/manual/vhosts/header.html b/docs/manual/vhosts/header.html deleted file mode 100644 index 7150a227f3..0000000000 --- a/docs/manual/vhosts/header.html +++ /dev/null @@ -1,7 +0,0 @@ - <div align="center"> - <img src="../images/sub.gif" alt="[APACHE DOCUMENTATION]" /> - - <h3>Apache HTTP Server Version 2.1</h3> - </div> - - |