diff options
| author |   hongbotian <hongbo.tianhongbo@huawei.com> | 2015-11-30 01:45:08 -0500 |
|---|---|---|
| committer | hongbotian <hongbo.tianhongbo@huawei.com> | 2015-11-30 01:45:08 -0500 |
| commit | e8ec7aa8e38a93f5b034ac74cebce5de23710317 (patch) | |
| tree | aa031937bf856c1f8d6ad7877b8d2cb0224da5ef /rubbos/app/httpd-2.0.64/docs/manual/developer | |
| parent | cc40af334e619bb549038238507407866f774f8f (diff) | |
upload http
JIRA: BOTTLENECK-10
Change-Id: I7598427ff904df438ce77c2819ee48ac75ffa8da
Signed-off-by: hongbotian <hongbo.tianhongbo@huawei.com>
Diffstat (limited to 'rubbos/app/httpd-2.0.64/docs/manual/developer')
19 files changed, 3166 insertions, 0 deletions
diff --git a/rubbos/app/httpd-2.0.64/docs/manual/developer/API.html b/rubbos/app/httpd-2.0.64/docs/manual/developer/API.html new file mode 100644 index 00000000..b8ea3a1c --- /dev/null +++ b/rubbos/app/httpd-2.0.64/docs/manual/developer/API.html @@ -0,0 +1,5 @@ +# GENERATED FROM XML -- DO NOT EDIT + +URI: API.html.en +Content-Language: en +Content-type: text/html; charset=ISO-8859-1 diff --git a/rubbos/app/httpd-2.0.64/docs/manual/developer/API.html.en b/rubbos/app/httpd-2.0.64/docs/manual/developer/API.html.en new file mode 100644 index 00000000..db62a134 --- /dev/null +++ b/rubbos/app/httpd-2.0.64/docs/manual/developer/API.html.en @@ -0,0 +1,1223 @@ +<?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.0</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/">Documentation</a> > <a href="../">Version 2.0</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" title="English"> 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> + /* 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> + }; + </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 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" title="English"> en </a></p> +</div><div id="footer"> +<p class="apache">Copyright 2009 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</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/rubbos/app/httpd-2.0.64/docs/manual/developer/debugging.html b/rubbos/app/httpd-2.0.64/docs/manual/developer/debugging.html new file mode 100644 index 00000000..6d94fa27 --- /dev/null +++ b/rubbos/app/httpd-2.0.64/docs/manual/developer/debugging.html @@ -0,0 +1,5 @@ +# GENERATED FROM XML -- DO NOT EDIT + +URI: debugging.html.en +Content-Language: en +Content-type: text/html; charset=ISO-8859-1 diff --git a/rubbos/app/httpd-2.0.64/docs/manual/developer/debugging.html.en b/rubbos/app/httpd-2.0.64/docs/manual/developer/debugging.html.en new file mode 100644 index 00000000..3febd64c --- /dev/null +++ b/rubbos/app/httpd-2.0.64/docs/manual/developer/debugging.html.en @@ -0,0 +1,196 @@ +<?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>Debugging Memory Allocation in APR - 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.0</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/">Documentation</a> > <a href="../">Version 2.0</a> > <a href="./">Developer Documentation</a></div><div id="page-content"><div id="preamble"><h1>Debugging Memory Allocation in APR</h1> +<div class="toplang"> +<p><span>Available Languages: </span><a href="../en/developer/debugging.html" title="English"> en </a></p> +</div> + + <p>The allocation mechanism's within APR have a number of debugging modes + that can be used to assist in finding memory problems. This document + describes the modes available and gives instructions on activating + them.</p> +</div> +<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#options">Available debugging options</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#combo">Allowable Combinations</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#howto">Activating Debugging Options</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="options" id="options">Available debugging options</a></h2> + <h3><a name="alloc_debug" id="alloc_debug">Allocation Debugging - ALLOC_DEBUG</a></h3> + + + <div class="note">Debugging support: Define this to enable code which + helps detect re-use of <code>free()</code>d memory and other such + nonsense.</div> + + <p>The theory is simple. The <code>FILL_BYTE</code> (<code>0xa5</code>) + is written over all <code>malloc</code>'d memory as we receive it, and + is written over everything that we free up during a + <code>clear_pool</code>. We check that blocks on the free list always + have the <code>FILL_BYTE</code> in them, and we check during + <code>palloc()</code> that the bytes still have <code>FILL_BYTE</code> + in them. If you ever see garbage URLs or whatnot containing lots + of <code>0xa5</code>s then you know something used data that's been + freed or uninitialized.</p> + + + <h3><a name="alloc_use_malloc" id="alloc_use_malloc">Malloc Support - ALLOC_USE_MALLOC</a></h3> + + + <div class="note">If defined all allocations will be done with + <code>malloc()</code> and <code>free()</code>d appropriately at the + end.</div> + + <p>This is intended to be used with something like Electric + Fence or Purify to help detect memory problems. Note that if + you're using efence then you should also add in <code>ALLOC_DEBUG</code>. + But don't add in <code>ALLOC_DEBUG</code> if you're using Purify because + <code>ALLOC_DEBUG</code> would hide all the uninitialized read errors + that Purify can diagnose.</p> + + + <h3><a name="pool_debug" id="pool_debug">Pool Debugging - POOL_DEBUG</a></h3> + <div class="note">This is intended to detect cases where the wrong pool is + used when assigning data to an object in another pool.</div> + + <p>In particular, it causes the <code>table_{set,add,merge}n</code> + routines to check that their arguments are safe for the + <code>apr_table_t</code> they're being placed in. It currently only works + with the unix multiprocess model, but could be extended to others.</p> + + + <h3><a name="make_table_profile" id="make_table_profile">Table Debugging - MAKE_TABLE_PROFILE</a></h3> + + + <div class="note">Provide diagnostic information about make_table() calls + which are possibly too small.</div> + + <p>This requires a recent gcc which supports + <code>__builtin_return_address()</code>. The error_log output will be a + message such as:</p> + <div class="example"><p><code> + table_push: apr_table_t created by 0x804d874 hit limit of 10 + </code></p></div> + + <p>Use <code>l *0x804d874</code> to find the + source that corresponds to. It indicates that a <code>apr_table_t</code> + allocated by a call at that address has possibly too small an + initial <code>apr_table_t</code> size guess.</p> + + + <h3><a name="alloc_stats" id="alloc_stats">Allocation Statistics - ALLOC_STATS</a></h3> + + + <div class="note">Provide some statistics on the cost of allocations.</div> + + <p>This requires a bit of an understanding of how alloc.c works.</p> + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="combo" id="combo">Allowable Combinations</a></h2> + + <p>Not all the options outlined above can be activated at the + same time. the following table gives more information.</p> + + <table class="bordered"><tr class="header"><th /> + <th>ALLOC DEBUG</th> + <th>ALLOC USE MALLOC</th> + <th>POOL DEBUG</th> + <th>MAKE TABLE PROFILE</th> + <th>ALLOC STATS</th></tr> +<tr><th>ALLOC DEBUG</th> + <td>-</td><td>No</td><td>Yes</td><td>Yes</td><td>Yes</td></tr> +<tr class="odd"><th>ALLOC USE MALLOC</th> + <td>No</td><td>-</td><td>No</td><td>No</td><td>No</td></tr> +<tr><th>POOL DEBUG</th> + <td>Yes</td><td>No</td><td>-</td><td>Yes</td><td>Yes</td></tr> +<tr class="odd"><th>MAKE TABLE PROFILE</th> + <td>Yes</td><td>No</td><td>Yes</td><td>-</td><td>Yes</td></tr> +<tr><th>ALLOC STATS</th> + <td>Yes</td><td>No</td><td>Yes</td><td>Yes</td><td>-</td></tr> +</table> + + <p>Additionally the debugging options are not suitable for + multi-threaded versions of the server. When trying to debug + with these options the server should be started in single + process mode.</p> +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="howto" id="howto">Activating Debugging Options</a></h2> + + <p>The various options for debugging memory are now enabled in + the <code>apr_general.h</code> header file in APR. The various options are + enabled by uncommenting the define for the option you wish to + use. The section of the code currently looks like this + (<em>contained in srclib/apr/include/apr_pools.h</em>)</p> + + <div class="example"><p><code> + /*<br /> + #define ALLOC_DEBUG<br /> + #define POOL_DEBUG<br /> + #define ALLOC_USE_MALLOC<br /> + #define MAKE_TABLE_PROFILE<br /> + #define ALLOC_STATS<br /> + */<br /> + <br /> + typedef struct ap_pool_t {<br /> + <span class="indent"> + union block_hdr *first;<br /> + union block_hdr *last;<br /> + struct cleanup *cleanups;<br /> + struct process_chain *subprocesses;<br /> + struct ap_pool_t *sub_pools;<br /> + struct ap_pool_t *sub_next;<br /> + struct ap_pool_t *sub_prev;<br /> + struct ap_pool_t *parent;<br /> + char *free_first_avail;<br /> + </span> + #ifdef ALLOC_USE_MALLOC<br /> + <span class="indent"> + void *allocation_list;<br /> + </span> + #endif<br /> + #ifdef POOL_DEBUG<br /> + <span class="indent"> + struct ap_pool_t *joined;<br /> + </span> + #endif<br /> + <span class="indent"> + int (*apr_abort)(int retcode);<br /> + struct datastruct *prog_data;<br /> + </span> + } ap_pool_t; + </code></p></div> + + <p>To enable allocation debugging simply move the <code>#define + ALLOC_DEBUG</code> above the start of the comments block and rebuild + the server.</p> + + <div class="note"><h3>Note</h3> + <p>In order to use the various options the server <strong>must</strong> + be rebuilt after editing the header file.</p> + </div> +</div></div> +<div class="bottomlang"> +<p><span>Available Languages: </span><a href="../en/developer/debugging.html" title="English"> en </a></p> +</div><div id="footer"> +<p class="apache">Copyright 2009 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</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/rubbos/app/httpd-2.0.64/docs/manual/developer/documenting.html b/rubbos/app/httpd-2.0.64/docs/manual/developer/documenting.html new file mode 100644 index 00000000..db57cef3 --- /dev/null +++ b/rubbos/app/httpd-2.0.64/docs/manual/developer/documenting.html @@ -0,0 +1,5 @@ +# GENERATED FROM XML -- DO NOT EDIT + +URI: documenting.html.en +Content-Language: en +Content-type: text/html; charset=ISO-8859-1 diff --git a/rubbos/app/httpd-2.0.64/docs/manual/developer/documenting.html.en b/rubbos/app/httpd-2.0.64/docs/manual/developer/documenting.html.en new file mode 100644 index 00000000..204801d4 --- /dev/null +++ b/rubbos/app/httpd-2.0.64/docs/manual/developer/documenting.html.en @@ -0,0 +1,84 @@ +<?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>Documenting Apache 2.0 - 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" class="no-sidebar"><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.0</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/">Documentation</a> > <a href="../">Version 2.0</a> > <a href="./">Developer Documentation</a></div><div id="page-content"><div id="preamble"><h1>Documenting Apache 2.0</h1> +<div class="toplang"> +<p><span>Available Languages: </span><a href="../en/developer/documenting.html" title="English"> en </a></p> +</div> + + <p>Apache 2.0 uses <a href="http://www.doxygen.org/">Doxygen</a> to + document the APIs and global variables in the code. This will explain + the basics of how to document using Doxygen.</p> +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="brief" id="brief">Brief Description</a></h2> + <p>To start a documentation block, use <code>/**</code><br /> + To end a documentation block, use <code>*/</code></p> + + <p>In the middle of the block, there are multiple tags we can + use:</p> + + <div class="example"><p><code> + Description of this functions purpose<br /> + @param parameter_name description<br /> + @return description<br /> + @deffunc signature of the function<br /> + </code></p></div> + + <p>The <code>deffunc</code> is not always necessary. DoxyGen does not + have a full parser in it, so any prototype that use a macro in the + return type declaration is too complex for scandoc. Those functions + require a <code>deffunc</code>. An example (using &gt; rather + than >):</p> + + <div class="example"><p><code> + /**<br /> + * return the final element of the pathname<br /> + * @param pathname The path to get the final element of<br /> + * @return the final element of the path<br /> + * @tip Examples:<br /> + * <pre><br /> + * "/foo/bar/gum" -&gt; "gum"<br /> + * "/foo/bar/gum/" -&gt; ""<br /> + * "gum" -&gt; "gum"<br /> + * "wi\\n32\\stuff" -&gt; "stuff"<br /> + * </pre><br /> + * @deffunc const char * ap_filename_of_pathname(const char *pathname)<br /> + */ + </code></p></div> + + <p>At the top of the header file, always include:</p> + <div class="example"><p><code> + /**<br /> + * @package Name of library header<br /> + */ + </code></p></div> + + <p>Doxygen uses a new HTML file for each package. The HTML files are named + {Name_of_library_header}.html, so try to be concise with your names.</p> + + <p>For a further discussion of the possibilities please refer to + <a href="http://www.doxygen.org/">the Doxygen site</a>.</p> +</div></div> +<div class="bottomlang"> +<p><span>Available Languages: </span><a href="../en/developer/documenting.html" title="English"> en </a></p> +</div><div id="footer"> +<p class="apache">Copyright 2009 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</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/rubbos/app/httpd-2.0.64/docs/manual/developer/filters.html b/rubbos/app/httpd-2.0.64/docs/manual/developer/filters.html new file mode 100644 index 00000000..6caade35 --- /dev/null +++ b/rubbos/app/httpd-2.0.64/docs/manual/developer/filters.html @@ -0,0 +1,5 @@ +# GENERATED FROM XML -- DO NOT EDIT + +URI: filters.html.en +Content-Language: en +Content-type: text/html; charset=ISO-8859-1 diff --git a/rubbos/app/httpd-2.0.64/docs/manual/developer/filters.html.en b/rubbos/app/httpd-2.0.64/docs/manual/developer/filters.html.en new file mode 100644 index 00000000..5f6fc54a --- /dev/null +++ b/rubbos/app/httpd-2.0.64/docs/manual/developer/filters.html.en @@ -0,0 +1,210 @@ +<?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>How filters work in Apache 2.0 - 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.0</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/">Documentation</a> > <a href="../">Version 2.0</a> > <a href="./">Developer Documentation</a></div><div id="page-content"><div id="preamble"><h1>How filters work in Apache 2.0</h1> +<div class="toplang"> +<p><span>Available Languages: </span><a href="../en/developer/filters.html" title="English"> en </a></p> +</div> + + <div class="warning"><h3>Warning</h3> + <p>This is a cut 'n paste job from an email + (<022501c1c529$f63a9550$7f00000a@KOJ>) and only reformatted for + better readability. It's not up to date but may be a good start for + further research.</p> + </div> +</div> +<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#types">Filter Types</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#howinserted">How are filters inserted?</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#asis">Asis</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#conclusion">Explanations</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="types" id="types">Filter Types</a></h2> + <p>There are three basic filter types (each of these is actually broken + down into two categories, but that comes later).</p> + + <dl> + <dt><code>CONNECTION</code></dt> + <dd>Filters of this type are valid for the lifetime of this connection. + (<code>AP_FTYPE_CONNECTION</code>, <code>AP_FTYPE_NETWORK</code>)</dd> + + <dt><code>PROTOCOL</code></dt> + <dd>Filters of this type are valid for the lifetime of this request from + the point of view of the client, this means that the request is valid + from the time that the request is sent until the time that the response + is received. (<code>AP_FTYPE_PROTOCOL</code>, + <code>AP_FTYPE_TRANSCODE</code>)</dd> + + <dt><code>RESOURCE</code></dt> + <dd>Filters of this type are valid for the time that this content is used + to satisfy a request. For simple requests, this is identical to + <code>PROTOCOL</code>, but internal redirects and sub-requests can change + the content without ending the request. (<code>AP_FTYPE_RESOURCE</code>, + <code>AP_FTYPE_CONTENT_SET</code>)</dd> + </dl> + + <p>It is important to make the distinction between a protocol and a + resource filter. A resource filter is tied to a specific resource, it + may also be tied to header information, but the main binding is to a + resource. If you are writing a filter and you want to know if it is + resource or protocol, the correct question to ask is: "Can this filter + be removed if the request is redirected to a different resource?" If + the answer is yes, then it is a resource filter. If it is no, then it + is most likely a protocol or connection filter. I won't go into + connection filters, because they seem to be well understood. With this + definition, a few examples might help:</p> + + <dl> + <dt>Byterange</dt> + <dd>We have coded it to be inserted for all requests, and it is removed + if not used. Because this filter is active at the beginning of all + requests, it can not be removed if it is redirected, so this is a + protocol filter.</dd> + + <dt>http_header</dt> + <dd>This filter actually writes the headers to the network. This is + obviously a required filter (except in the asis case which is special + and will be dealt with below) and so it is a protocol filter.</dd> + + <dt>Deflate</dt> + <dd>The administrator configures this filter based on which file has been + requested. If we do an internal redirect from an autoindex page to an + index.html page, the deflate filter may be added or removed based on + config, so this is a resource filter.</dd> + </dl> + + <p>The further breakdown of each category into two more filter types is + strictly for ordering. We could remove it, and only allow for one + filter type, but the order would tend to be wrong, and we would need to + hack things to make it work. Currently, the <code>RESOURCE</code> filters + only have one filter type, but that should change.</p> +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="howinserted" id="howinserted">How are filters inserted?</a></h2> + <p>This is actually rather simple in theory, but the code is + complex. First of all, it is important that everybody realize that + there are three filter lists for each request, but they are all + concatenated together. So, the first list is + <code>r->output_filters</code>, then <code>r->proto_output_filters</code>, + and finally <code>r->connection->output_filters</code>. These correspond + to the <code>RESOURCE</code>, <code>PROTOCOL</code>, and + <code>CONNECTION</code> filters respectively. The problem previously, was + that we used a singly linked list to create the filter stack, and we + started from the "correct" location. This means that if I had a + <code>RESOURCE</code> filter on the stack, and I added a + <code>CONNECTION</code> filter, the <code>CONNECTION</code> filter would + be ignored. This should make sense, because we would insert the connection + filter at the top of the <code>c->output_filters</code> list, but the end + of <code>r->output_filters</code> pointed to the filter that used to be + at the front of <code>c->output_filters</code>. This is obviously wrong. + The new insertion code uses a doubly linked list. This has the advantage + that we never lose a filter that has been inserted. Unfortunately, it comes + with a separate set of headaches.</p> + + <p>The problem is that we have two different cases were we use subrequests. + The first is to insert more data into a response. The second is to + replace the existing response with an internal redirect. These are two + different cases and need to be treated as such.</p> + + <p>In the first case, we are creating the subrequest from within a handler + or filter. This means that the next filter should be passed to + <code>make_sub_request</code> function, and the last resource filter in the + sub-request will point to the next filter in the main request. This + makes sense, because the sub-request's data needs to flow through the + same set of filters as the main request. A graphical representation + might help:</p> + +<div class="example"><pre> +Default_handler --> includes_filter --> byterange --> ... +</pre></div> + + <p>If the includes filter creates a sub request, then we don't want the + data from that sub-request to go through the includes filter, because it + might not be SSI data. So, the subrequest adds the following:</p> + +<div class="example"><pre> +Default_handler --> includes_filter -/-> byterange --> ... + / +Default_handler --> sub_request_core +</pre></div> + + <p>What happens if the subrequest is SSI data? Well, that's easy, the + <code>includes_filter</code> is a resource filter, so it will be added to + the sub request in between the <code>Default_handler</code> and the + <code>sub_request_core</code> filter.</p> + + <p>The second case for sub-requests is when one sub-request is going to + become the real request. This happens whenever a sub-request is created + outside of a handler or filter, and NULL is passed as the next filter to + the <code>make_sub_request</code> function.</p> + + <p>In this case, the resource filters no longer make sense for the new + request, because the resource has changed. So, instead of starting from + scratch, we simply point the front of the resource filters for the + sub-request to the front of the protocol filters for the old request. + This means that we won't lose any of the protocol filters, neither will + we try to send this data through a filter that shouldn't see it.</p> + + <p>The problem is that we are using a doubly-linked list for our filter + stacks now. But, you should notice that it is possible for two lists to + intersect in this model. So, you do you handle the previous pointer? + This is a very difficult question to answer, because there is no "right" + answer, either method is equally valid. I looked at why we use the + previous pointer. The only reason for it is to allow for easier + addition of new servers. With that being said, the solution I chose was + to make the previous pointer always stay on the original request.</p> + + <p>This causes some more complex logic, but it works for all cases. My + concern in having it move to the sub-request, is that for the more + common case (where a sub-request is used to add data to a response), the + main filter chain would be wrong. That didn't seem like a good idea to + me.</p> +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="asis" id="asis">Asis</a></h2> + <p>The final topic. :-) Mod_Asis is a bit of a hack, but the + handler needs to remove all filters except for connection filters, and + send the data. If you are using <code class="module"><a href="../mod/mod_asis.html">mod_asis</a></code>, all other + bets are off.</p> +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="conclusion" id="conclusion">Explanations</a></h2> + <p>The absolutely last point is that the reason this code was so hard to + get right, was because we had hacked so much to force it to work. I + wrote most of the hacks originally, so I am very much to blame. + However, now that the code is right, I have started to remove some + hacks. Most people should have seen that the <code>reset_filters</code> + and <code>add_required_filters</code> functions are gone. Those inserted + protocol level filters for error conditions, in fact, both functions did + the same thing, one after the other, it was really strange. Because we + don't lose protocol filters for error cases any more, those hacks went away. + The <code>HTTP_HEADER</code>, <code>Content-length</code>, and + <code>Byterange</code> filters are all added in the + <code>insert_filters</code> phase, because if they were added earlier, we + had some interesting interactions. Now, those could all be moved to be + inserted with the <code>HTTP_IN</code>, <code>CORE</code>, and + <code>CORE_IN</code> filters. That would make the code easier to + follow.</p> +</div></div> +<div class="bottomlang"> +<p><span>Available Languages: </span><a href="../en/developer/filters.html" title="English"> en </a></p> +</div><div id="footer"> +<p class="apache">Copyright 2009 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</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/rubbos/app/httpd-2.0.64/docs/manual/developer/hooks.html b/rubbos/app/httpd-2.0.64/docs/manual/developer/hooks.html new file mode 100644 index 00000000..a4077c72 --- /dev/null +++ b/rubbos/app/httpd-2.0.64/docs/manual/developer/hooks.html @@ -0,0 +1,5 @@ +# GENERATED FROM XML -- DO NOT EDIT + +URI: hooks.html.en +Content-Language: en +Content-type: text/html; charset=ISO-8859-1 diff --git a/rubbos/app/httpd-2.0.64/docs/manual/developer/hooks.html.en b/rubbos/app/httpd-2.0.64/docs/manual/developer/hooks.html.en new file mode 100644 index 00000000..b89e9906 --- /dev/null +++ b/rubbos/app/httpd-2.0.64/docs/manual/developer/hooks.html.en @@ -0,0 +1,239 @@ +<?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 2.0 Hook Functions - 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.0</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/">Documentation</a> > <a href="../">Version 2.0</a> > <a href="./">Developer Documentation</a></div><div id="page-content"><div id="preamble"><h1>Apache 2.0 Hook Functions</h1> +<div class="toplang"> +<p><span>Available Languages: </span><a href="../en/developer/hooks.html" title="English"> en </a></p> +</div> + + <div class="warning"><h3>Warning</h3> + <p>This document is still in development and may be partially out of + date.</p> + </div> + + <p>In general, a hook function is one that Apache will call at + some point during the processing of a request. Modules can + provide functions that are called, and specify when they get + called in comparison to other modules.</p> +</div> +<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#create">Creating a hook function</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#hooking">Hooking the hook</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="create" id="create">Creating a hook function</a></h2> + <p>In order to create a new hook, four things need to be + done:</p> + + <h3><a name="create-declare" id="create-declare">Declare the hook function</a></h3> + <p>Use the <code>AP_DECLARE_HOOK</code> macro, which needs to be given + the return type of the hook function, the name of the hook, and the + arguments. For example, if the hook returns an <code>int</code> and + takes a <code>request_rec *</code> and an <code>int</code> and is + called <code>do_something</code>, then declare it like this:</p> + <div class="example"><p><code> + AP_DECLARE_HOOK(int, do_something, (request_rec *r, int n)) + </code></p></div> + + <p>This should go in a header which modules will include if + they want to use the hook.</p> + + + <h3><a name="create-create" id="create-create">Create the hook structure</a></h3> + <p>Each source file that exports a hook has a private structure + which is used to record the module functions that use the hook. + This is declared as follows:</p> + + <div class="example"><p><code> + APR_HOOK_STRUCT(<br /> + <span class="indent"> + APR_HOOK_LINK(do_something)<br /> + ...<br /> + </span> + ) + </code></p></div> + + + <h3><a name="create-implement" id="create-implement">Implement the hook caller</a></h3> + <p>The source file that exports the hook has to implement a + function that will call the hook. There are currently three + possible ways to do this. In all cases, the calling function is + called <code>ap_run_<var>hookname</var>()</code>.</p> + + <h4>Void hooks</h4> + <p>If the return value of a hook is <code>void</code>, then all the + hooks are called, and the caller is implemented like this:</p> + + <div class="example"><p><code> + AP_IMPLEMENT_HOOK_VOID(do_something, (request_rec *r, int n), (r, n)) + </code></p></div> + + <p>The second and third arguments are the dummy argument + declaration and the dummy arguments as they will be used when + calling the hook. In other words, this macro expands to + something like this:</p> + + <div class="example"><p><code> + void ap_run_do_something(request_rec *r, int n)<br /> + {<br /> + <span class="indent"> + ...<br /> + do_something(r, n);<br /> + </span> + } + </code></p></div> + + + <h4>Hooks that return a value</h4> + <p>If the hook returns a value, then it can either be run until + the first hook that does something interesting, like so:</p> + + <div class="example"><p><code> + AP_IMPLEMENT_HOOK_RUN_FIRST(int, do_something, (request_rec *r, int n), (r, n), DECLINED) + </code></p></div> + + <p>The first hook that does <em>not</em> return <code>DECLINED</code> + stops the loop and its return value is returned from the hook + caller. Note that <code>DECLINED</code> is the tradition Apache + hook return meaning "I didn't do anything", but it can be + whatever suits you.</p> + + <p>Alternatively, all hooks can be run until an error occurs. + This boils down to permitting <em>two</em> return values, one of + which means "I did something, and it was OK" and the other + meaning "I did nothing". The first function that returns a + value other than one of those two stops the loop, and its + return is the return value. Declare these like so:</p> + + <div class="example"><p><code> + AP_IMPLEMENT_HOOK_RUN_ALL(int, do_something, (request_rec *r, int n), (r, n), OK, DECLINED) + </code></p></div> + + <p>Again, <code>OK</code> and <code>DECLINED</code> are the traditional + values. You can use what you want.</p> + + + + <h3><a name="create-call" id="create-call">Call the hook callers</a></h3> + <p>At appropriate moments in the code, call the hook caller, + like so:</p> + + <div class="example"><p><code> + int n, ret;<br /> + request_rec *r;<br /> + <br /> + ret=ap_run_do_something(r, n); + </code></p></div> + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="hooking" id="hooking">Hooking the hook</a></h2> + <p>A module that wants a hook to be called needs to do two + things.</p> + + <h3><a name="hooking-implement" id="hooking-implement">Implement the hook function</a></h3> + <p>Include the appropriate header, and define a static function + of the correct type:</p> + + <div class="example"><p><code> + static int my_something_doer(request_rec *r, int n)<br /> + {<br /> + <span class="indent"> + ...<br /> + return OK;<br /> + </span> + } + </code></p></div> + + + <h3><a name="hooking-add" id="hooking-add">Add a hook registering function</a></h3> + <p>During initialisation, Apache will call each modules hook + registering function, which is included in the module + structure:</p> + + <div class="example"><p><code> + static void my_register_hooks()<br /> + {<br /> + <span class="indent"> + ap_hook_do_something(my_something_doer, NULL, NULL, HOOK_MIDDLE);<br /> + </span> + }<br /> + <br /> + mode MODULE_VAR_EXPORT my_module =<br /> + {<br /> + <span class="indent"> + ...<br /> + my_register_hooks /* register hooks */<br /> + </span> + }; + </code></p></div> + + + <h3><a name="hooking-order" id="hooking-order">Controlling hook calling order</a></h3> + <p>In the example above, we didn't use the three arguments in + the hook registration function that control calling order. + There are two mechanisms for doing this. The first, rather + crude, method, allows us to specify roughly where the hook is + run relative to other modules. The final argument control this. + There are three possible values: <code>HOOK_FIRST</code>, + <code>HOOK_MIDDLE</code> and <code>HOOK_LAST</code>.</p> + + <p>All modules using any particular value may be run in any + order relative to each other, but, of course, all modules using + <code>HOOK_FIRST</code> will be run before <code>HOOK_MIDDLE</code> + which are before <code>HOOK_LAST</code>. Modules that don't care + when they are run should use <code>HOOK_MIDDLE</code>. <em>(I spaced + these out so people could do stuff like <code>HOOK_FIRST-2</code> + to get in slightly earlier, but is this wise? - Ben)</em></p> + + <p>Note that there are two more values, + <code>HOOK_REALLY_FIRST</code> and <code>HOOK_REALLY_LAST</code>. These + should only be used by the hook exporter.</p> + + <p>The other method allows finer control. When a module knows + that it must be run before (or after) some other modules, it + can specify them by name. The second (third) argument is a + NULL-terminated array of strings consisting of the names of + modules that must be run before (after) the current module. For + example, suppose we want "mod_xyz.c" and "mod_abc.c" to run + before we do, then we'd hook as follows:</p> + + <div class="example"><p><code> + static void register_hooks()<br /> + {<br /> + <span class="indent"> + static const char * const aszPre[] = { "mod_xyz.c", "mod_abc.c", NULL };<br /> + <br /> + ap_hook_do_something(my_something_doer, aszPre, NULL, HOOK_MIDDLE);<br /> + </span> + } + </code></p></div> + + <p>Note that the sort used to achieve this is stable, so + ordering set by <code>HOOK_<var>ORDER</var></code> is preserved, as far + as is possible.</p> + + <p class="cite"><cite>Ben Laurie</cite>, 15th August 1999</p> + +</div></div> +<div class="bottomlang"> +<p><span>Available Languages: </span><a href="../en/developer/hooks.html" title="English"> en </a></p> +</div><div id="footer"> +<p class="apache">Copyright 2009 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</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/rubbos/app/httpd-2.0.64/docs/manual/developer/index.html b/rubbos/app/httpd-2.0.64/docs/manual/developer/index.html new file mode 100644 index 00000000..e4d079c3 --- /dev/null +++ b/rubbos/app/httpd-2.0.64/docs/manual/developer/index.html @@ -0,0 +1,5 @@ +# GENERATED FROM XML -- DO NOT EDIT + +URI: index.html.en +Content-Language: en +Content-type: text/html; charset=ISO-8859-1 diff --git a/rubbos/app/httpd-2.0.64/docs/manual/developer/index.html.en b/rubbos/app/httpd-2.0.64/docs/manual/developer/index.html.en new file mode 100644 index 00000000..7006579b --- /dev/null +++ b/rubbos/app/httpd-2.0.64/docs/manual/developer/index.html.en @@ -0,0 +1,73 @@ +<?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>Developer Documentation for Apache 2.0 - 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.0</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/">Documentation</a> > <a href="../">Version 2.0</a></div><div id="page-content"><div id="preamble"><h1>Developer Documentation for Apache 2.0</h1> +<div class="toplang"> +<p><span>Available Languages: </span><a href="../en/developer/" title="English"> en </a></p> +</div> + + <p>Many of the documents on these Developer pages are lifted + from Apache 1.3's documentation. While they are all being + updated to Apache 2.0, they are in different stages of + progress. Please be patient, and point out any discrepancies or + errors on the developer/ pages directly to the + <a href="http://httpd.apache.org/lists.html#http-dev">dev@httpd.apache.org</a> mailing list.</p> +</div> +<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#topics">Topics</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#external">External Resources</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="topics" id="topics">Topics</a></h2> + <ul> + <li><a href="API.html">Apache 1.3 API Notes</a></li> + <li><a href="hooks.html">Apache 2.0 Hook Functions</a></li> + <li><a href="request.html">Request Processing in Apache 2.0</a></li> + <li><a href="filters.html">How filters work in Apache 2.0</a></li> + <li><a href="modules.html">Converting Modules from Apache 1.3 to Apache 2.0</a></li> + <li><a href="debugging.html">Debugging Memory Allocation in APR</a></li> + <li><a href="documenting.html">Documenting Apache 2.0</a></li> + <li><a href="thread_safety.html">Apache 2.0 Thread Safety Issues</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="external" id="external">External Resources</a></h2> + <ul> + <li>Tools provided by Ian Holsman: + <ul> + <li><a href="http://lxr.webperf.org/">Apache 2 cross reference</a></li> + <li><a href="http://docx.webperf.org/">Autogenerated Apache 2 code documentation</a></li> + </ul></li> + + <li>Module Development Tutorials by Kevin O'Donnell + <ul> + <li><a href="http://threebit.net/tutorials/apache2_modules/tut1/tutorial1.html">Integrating a module into the Apache build system</a></li> + + <li><a href="http://threebit.net/tutorials/apache2_modules/tut2/tutorial2.html">Handling configuration directives</a></li> + </ul></li> + + <li><a href="http://www.onlamp.com/pub/ct/38">Some notes on + Apache module development by Ryan Bloom</a></li> + </ul> +</div></div> +<div class="bottomlang"> +<p><span>Available Languages: </span><a href="../en/developer/" title="English"> en </a></p> +</div><div id="footer"> +<p class="apache">Copyright 2009 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</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/rubbos/app/httpd-2.0.64/docs/manual/developer/modules.html b/rubbos/app/httpd-2.0.64/docs/manual/developer/modules.html new file mode 100644 index 00000000..33cfd0f4 --- /dev/null +++ b/rubbos/app/httpd-2.0.64/docs/manual/developer/modules.html @@ -0,0 +1,9 @@ +# GENERATED FROM XML -- DO NOT EDIT + +URI: modules.html.en +Content-Language: en +Content-type: text/html; charset=ISO-8859-1 + +URI: modules.html.ja.utf8 +Content-Language: ja +Content-type: text/html; charset=UTF-8 diff --git a/rubbos/app/httpd-2.0.64/docs/manual/developer/modules.html.en b/rubbos/app/httpd-2.0.64/docs/manual/developer/modules.html.en new file mode 100644 index 00000000..176a94dd --- /dev/null +++ b/rubbos/app/httpd-2.0.64/docs/manual/developer/modules.html.en @@ -0,0 +1,273 @@ +<?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>Converting Modules from Apache 1.3 to Apache 2.0 - 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.0</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/">Documentation</a> > <a href="../">Version 2.0</a> > <a href="./">Developer Documentation</a></div><div id="page-content"><div id="preamble"><h1>Converting Modules from Apache 1.3 to Apache 2.0</h1> +<div class="toplang"> +<p><span>Available Languages: </span><a href="../en/developer/modules.html" title="English"> en </a> | +<a href="../ja/developer/modules.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a></p> +</div> + + <p>This is a first attempt at writing the lessons I learned + when trying to convert the <code>mod_mmap_static</code> module to Apache + 2.0. It's by no means definitive and probably won't even be + correct in some ways, but it's a start.</p> +</div> +<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#easy">The easier changes ...</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#messy">The messier changes...</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="easy" id="easy">The easier changes ...</a></h2> + + <h3><a name="cleanup" id="cleanup">Cleanup Routines</a></h3> + <p>These now need to be of type <code>apr_status_t</code> and return a + value of that type. Normally the return value will be + <code>APR_SUCCESS</code> unless there is some need to signal an error in + the cleanup. Be aware that even though you signal an error not all code + yet checks and acts upon the error.</p> + + + <h3><a name="init" id="init">Initialisation Routines</a></h3> + <p>These should now be renamed to better signify where they sit + in the overall process. So the name gets a small change from + <code>mmap_init</code> to <code>mmap_post_config</code>. The arguments + passed have undergone a radical change and now look like</p> + + <ul> + <li><code>apr_pool_t *p</code></li> + <li><code>apr_pool_t *plog</code></li> + <li><code>apr_pool_t *ptemp</code></li> + <li><code>server_rec *s</code></li> + </ul> + + + <h3><a name="datatypes" id="datatypes">Data Types</a></h3> + <p>A lot of the data types have been moved into the <a href="http://apr.apache.org/">APR</a>. This means that some have had + a name change, such as the one shown above. The following is a brief + list of some of the changes that you are likely to have to make.</p> + + <ul> + <li><code>pool</code> becomes <code>apr_pool_t</code></li> + <li><code>table</code> becomes <code>apr_table_t</code></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="messy" id="messy">The messier changes...</a></h2> + + <h3><a name="register-hooks" id="register-hooks">Register Hooks</a></h3> + <p>The new architecture uses a series of hooks to provide for + calling your functions. These you'll need to add to your module + by way of a new function, <code>static void register_hooks(void)</code>. + The function is really reasonably straightforward once you + understand what needs to be done. Each function that needs + calling at some stage in the processing of a request needs to + be registered, handlers do not. There are a number of phases + where functions can be added, and for each you can specify with + a high degree of control the relative order that the function + will be called in.</p> + + <p>This is the code that was added to <code>mod_mmap_static</code>:</p> + <div class="example"><pre> +static void register_hooks(void) +{ + static const char * const aszPre[]={ "http_core.c",NULL }; + ap_hook_post_config(mmap_post_config,NULL,NULL,HOOK_MIDDLE); + ap_hook_translate_name(mmap_static_xlat,aszPre,NULL,HOOK_LAST); +};</pre></div> + + <p>This registers 2 functions that need to be called, one in + the <code>post_config</code> stage (virtually every module will need this + one) and one for the <code>translate_name</code> phase. note that while + there are different function names the format of each is + identical. So what is the format?</p> + + <div class="example"><p><code> + ap_hook_<var>phase_name</var>(<var>function_name</var>, + <var>predecessors</var>, <var>successors</var>, <var>position</var>); + </code></p></div> + + <p>There are 3 hook positions defined...</p> + + <ul> + <li><code>HOOK_FIRST</code></li> + <li><code>HOOK_MIDDLE</code></li> + <li><code>HOOK_LAST</code></li> + </ul> + + <p>To define the position you use the position and then modify + it with the predecessors and successors. Each of the modifiers + can be a list of functions that should be called, either before + the function is run (predecessors) or after the function has + run (successors).</p> + + <p>In the <code>mod_mmap_static</code> case I didn't care about the + <code>post_config</code> stage, but the <code>mmap_static_xlat</code> + <strong>must</strong> be called after the core module had done it's name + translation, hence the use of the aszPre to define a modifier to the + position <code>HOOK_LAST</code>.</p> + + + <h3><a name="moddef" id="moddef">Module Definition</a></h3> + <p>There are now a lot fewer stages to worry about when + creating your module definition. The old defintion looked + like</p> + + <div class="example"><pre> +module MODULE_VAR_EXPORT <var>module_name</var>_module = +{ + STANDARD_MODULE_STUFF, + /* initializer */ + /* dir config creater */ + /* dir merger --- default is to override */ + /* server config */ + /* merge server config */ + /* command handlers */ + /* handlers */ + /* filename translation */ + /* check_user_id */ + /* check auth */ + /* check access */ + /* type_checker */ + /* fixups */ + /* logger */ + /* header parser */ + /* child_init */ + /* child_exit */ + /* post read-request */ +};</pre></div> + + <p>The new structure is a great deal simpler...</p> + <div class="example"><pre> +module MODULE_VAR_EXPORT <var>module_name</var>_module = +{ + STANDARD20_MODULE_STUFF, + /* create per-directory config structures */ + /* merge per-directory config structures */ + /* create per-server config structures */ + /* merge per-server config structures */ + /* command handlers */ + /* handlers */ + /* register hooks */ +};</pre></div> + + <p>Some of these read directly across, some don't. I'll try to + summarise what should be done below.</p> + + <p>The stages that read directly across :</p> + + <dl> + <dt><code>/* dir config creater */</code></dt> + <dd><code>/* create per-directory config structures */</code></dd> + + <dt><code>/* server config */</code></dt> + <dd><code>/* create per-server config structures */</code></dd> + + <dt><code>/* dir merger */</code></dt> + <dd><code>/* merge per-directory config structures */</code></dd> + + <dt><code>/* merge server config */</code></dt> + <dd><code>/* merge per-server config structures */</code></dd> + + <dt><code>/* command table */</code></dt> + <dd><code>/* command apr_table_t */</code></dd> + + <dt><code>/* handlers */</code></dt> + <dd><code>/* handlers */</code></dd> + </dl> + + <p>The remainder of the old functions should be registered as + hooks. There are the following hook stages defined so + far...</p> + + <dl> + <dt><code>ap_hook_post_config</code></dt> + <dd>this is where the old <code>_init</code> routines get + registered</dd> + + <dt><code>ap_hook_http_method</code></dt> + <dd>retrieve the http method from a request. (legacy)</dd> + + <dt><code>ap_hook_open_logs</code></dt> + <dd>open any specified logs</dd> + + <dt><code>ap_hook_auth_checker</code></dt> + <dd>check if the resource requires authorization</dd> + + <dt><code>ap_hook_access_checker</code></dt> + <dd>check for module-specific restrictions</dd> + + <dt><code>ap_hook_check_user_id</code></dt> + <dd>check the user-id and password</dd> + + <dt><code>ap_hook_default_port</code></dt> + <dd>retrieve the default port for the server</dd> + + <dt><code>ap_hook_pre_connection</code></dt> + <dd>do any setup required just before processing, but after + accepting</dd> + + <dt><code>ap_hook_process_connection</code></dt> + <dd>run the correct protocol</dd> + + <dt><code>ap_hook_child_init</code></dt> + <dd>call as soon as the child is started</dd> + + <dt><code>ap_hook_create_request</code></dt> + <dd>??</dd> + + <dt><code>ap_hook_fixups</code></dt> + <dd>last chance to modify things before generating content</dd> + + <dt><code>ap_hook_handler</code></dt> + <dd>generate the content</dd> + + <dt><code>ap_hook_header_parser</code></dt> + <dd>lets modules look at the headers, not used by most modules, because + they use <code>post_read_request</code> for this</dd> + + <dt><code>ap_hook_insert_filter</code></dt> + <dd>to insert filters into the filter chain</dd> + + <dt><code>ap_hook_log_transaction</code></dt> + <dd>log information about the request</dd> + + <dt><code>ap_hook_optional_fn_retrieve</code></dt> + <dd>retrieve any functions registered as optional</dd> + + <dt><code>ap_hook_post_read_request</code></dt> + <dd>called after reading the request, before any other phase</dd> + + <dt><code>ap_hook_quick_handler</code></dt> + <dd>called before any request processing, used by cache modules.</dd> + + <dt><code>ap_hook_translate_name</code></dt> + <dd>translate the URI into a filename</dd> + + <dt><code>ap_hook_type_checker</code></dt> + <dd>determine and/or set the doc type</dd> + </dl> + +</div></div> +<div class="bottomlang"> +<p><span>Available Languages: </span><a href="../en/developer/modules.html" title="English"> en </a> | +<a href="../ja/developer/modules.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a></p> +</div><div id="footer"> +<p class="apache">Copyright 2009 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</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/rubbos/app/httpd-2.0.64/docs/manual/developer/modules.html.ja.utf8 b/rubbos/app/httpd-2.0.64/docs/manual/developer/modules.html.ja.utf8 new file mode 100644 index 00000000..8297d28d --- /dev/null +++ b/rubbos/app/httpd-2.0.64/docs/manual/developer/modules.html.ja.utf8 @@ -0,0 +1,274 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!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="ja" xml:lang="ja"><head><!-- + XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + This file is generated from xml source: DO NOT EDIT + XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + --> +<title>モジュールの Apache 1.3 から Apache 2.0 への移植 - Apache HTTP サーバ</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/">モジュール</a> | <a href="../mod/directives.html">ディレクティブ</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">用語</a> | <a href="../sitemap.html">サイトマップ</a></p> +<p class="apache">Apache HTTP サーバ バージョン 2.0</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 サーバ</a> > <a href="http://httpd.apache.org/docs/">ドキュメンテーション</a> > <a href="../">バージョン 2.0</a> > <a href="./">Developer Documentation</a></div><div id="page-content"><div id="preamble"><h1>モジュールの Apache 1.3 から Apache 2.0 への移植</h1> +<div class="toplang"> +<p><span>Available Languages: </span><a href="../en/developer/modules.html" hreflang="en" rel="alternate" title="English"> en </a> | +<a href="../ja/developer/modules.html" title="Japanese"> ja </a></p> +</div> + + <p>この文書は <code>mod_mmap_static</code> モジュールを Apache 2.0 用に移植した時に + 学んだ経験をもとに書いた、最初の手引き書です。まだまだ完全じゃないし、 + ひょっとすると間違っている部分もあるかもしれませんが、 + 取っ掛りにはなるでしょう。</p> +</div> +<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#easy">簡単な変更点</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#messy">もっと厄介な変更点…</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="easy" id="easy">簡単な変更点</a></h2> + + <h3><a name="cleanup" id="cleanup">クリーンナップ ルーチン</a></h3> + <p>クリーンナップルーチンは <code>apr_status_t</code> 型である必要があります。 + そして、apr_status_t 型の値を返さなくてはなりません。 + クリーンナップ中のエラーを通知する必要がなければ、返り値は普通、 + <code>ARP_SUCCESS</code> です。たとえエラーを通知したとしても、 + すべてのコードがその通知をチェックしたり、 + エラーに応じた動作をするわけではないことに気をつけてください。</p> + + + + <h3><a name="init" id="init">初期化ルーチン</a></h3> + + <p>初期化ルーチンは処理全体から見てしっくりくるような意味を表すように、 + 名前が変更されました。ですから、<code>mmap_init</code> から <code>mmap_post_config</code> + のようにちょっと変更されました。 + 渡される引数は大幅に変更され、次のようになりました。</p> + + <ul> + <li><code>apr_pool_t *p</code></li> + <li><code>apr_pool_t *plog</code></li> + <li><code>apr_pool_t *ptemp</code></li> + <li><code>server_rec *s</code></li> + </ul> + + + <h3><a name="datatypes" id="datatypes">データ型</a></h3> + <p>データ型のほとんどは <a href="http://apr.apache.org/">APR</a> に移されました。つまり、 + いくつかの名前が前述のように変更されています。 + 施すべき変更点の簡単な一覧を以下に示します。</p> + + <ul> + <li><code>pool</code> becomes <code>apr_pool_t</code></li> + <li><code>table</code> becomes <code>apr_table_t</code></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="messy" id="messy">もっと厄介な変更点…</a></h2> + + <h3><a name="register-hooks" id="register-hooks">フックの登録</a></h3> + <p>新しいアーキテクチャでは作成した関数を呼び出すのに + 一連のフックを使用します。このフックは、新しい関数 + <code>static void register_hooks(void)</code> を使って登録するよう、 + モジュールに書き足さなくてはなりません。 + この関数は、なにをすべきか一旦理解してしまえば、 + 十分にわかりやすいものです。 + リクエストの処理のあるステージで呼び出さなくてはならない + 関数は登録する必要があります。ハンドラは登録する必要はありません。 + 関数を登録できるフェーズはたくさんあります。 + それぞれのフェーズで、関数を呼び出す相対的な順番は、 + かなりの程度制御できます。</p> + + <p>以下は、<code>mod_mmap_static</code> に追加したコードです:</p> + + <div class="example"><pre> +static void register_hooks(void) +{ + static const char * const aszPre[]={ "http_core.c",NULL }; + ap_hook_post_config(mmap_post_config,NULL,NULL,HOOK_MIDDLE); + ap_hook_translate_name(mmap_static_xlat,aszPre,NULL,HOOK_LAST); +};</pre></div> + + <p>ここでは呼びだすべき二つの関数を登録しています。一つは + <code>post_config</code> ステージ用 (ほとんどすべてのモジュール + はこれが必要です) で、もう一つは <code>translate_name</code> フェーズ用です。 + それぞれの関数は名前は違うけれども形式は同じであることに注意してください。 + それでは、形式はどのようになっているでしょうか?</p> + + <div class="example"><p><code> + ap_hook_<var>phase_name</var>(<var>function_name</var>, + <var>predecessors</var>, <var>successors</var>, <var>position</var>); + </code></p></div> + + <p>三つの位置が定義されています…</p> + + <ul> + <li><code>HOOK_FIRST</code></li> + <li><code>HOOK_MIDDLE</code></li> + <li><code>HOOK_LAST</code></li> + </ul> + + <p>位置を定義するには、上記の「位置」を指定し、 + 修飾子である「先行」と「後行」で手を加えます。 + 「先行」「後行」は、呼ばれるべき関数のリストです。 + 「先行」は関数の実行前に呼ばれるもので、 + 「後行」は実行後に呼ばれるものです。</p> + + <p><code>mod_mmap_static</code> の場合、<code>post_config</code> + ステージでは必要ありませんが、 + <code>mmap_static_xlat</code> が core モジュールが名前の変換を実行した後に + <strong>呼ばれなければなりません</strong>。 + そこで aszPre を使って <code>HOOK_LAST</code> の修飾子を定義しています。</p> + + + <h3><a name="moddef" id="moddef">モジュールの定義</a></h3> + <p>モジュールの定義を作成する際に注意しなければならない + ステージの数は激減しています。古い定義は次のようになっていました。</p> + + <div class="example"><pre> +module MODULE_VAR_EXPORT <var>module_name</var>_module = +{ + STANDARD_MODULE_STUFF, + /* initializer */ + /* dir config creater */ + /* dir merger --- default is to override */ + /* server config */ + /* merge server config */ + /* command handlers */ + /* handlers */ + /* filename translation */ + /* check_user_id */ + /* check auth */ + /* check access */ + /* type_checker */ + /* fixups */ + /* logger */ + /* header parser */ + /* child_init */ + /* child_exit */ + /* post read-request */ +};</pre></div> + + <p>新しい構造体はとってもシンプルです…</p> + <div class="example"><pre> +module MODULE_VAR_EXPORT <var>module_name</var>_module = +{ + STANDARD20_MODULE_STUFF, + /* create per-directory config structures */ + /* merge per-directory config structures */ + /* create per-server config structures */ + /* merge per-server config structures */ + /* command handlers */ + /* handlers */ + /* register hooks */ +};</pre></div> + + <p>このうちのいくつかは古いものから新しいものに直接読み替えられるもので、 + いくつかはそうではありません。どうすればいいのかを要約してみます。</p> + + <p>直接読み替えられるステージ:</p> + + <dl> + <dt><code>/* ディレクトリ設定作成関数 */</code></dt> + <dd><code>/* ディレクトリ毎設定構造体作成 */</code></dd> + + <dt><code>/* サーバ設定作成関数 */</code></dt> + <dd><code>/* サーバ毎設定構造体作成 */</code></dd> + + <dt><code>/* ディレクトリ設定マージ関数 */</code></dt> + <dd><code>/* ディレクトリ毎設定構造体マージ */</code></dd> + + <dt><code>/* サーバ設定マージ関数 */</code></dt> + <dd><code>/* サーバ毎設定構造体作成マージ */</code></dd> + + <dt><code>/* コマンド・テーブル */</code></dt> + <dd><code>/* コマンド apr_table_t */</code></dd> + + <dt><code>/* ハンドラ */</code></dt> + <dd><code>/* ハンドラ */</code></dd> + </dl> + + <p>古い関数の残りのものはフックとして登録されるべきです。 + 現時点で次のようなフック・ステージが定義されています…</p> + + <dl> + <dt><code>ap_hook_post_config</code></dt> + <dd>(以前の <code>_init</code> ルーチンが登録されるべき場所です)</dd> + + <dt><code>ap_hook_http_method</code></dt> + <dd>(リクエストから HTTP メソッドを取得します (互換用))</dd> + + <dt><code>ap_hook_open_logs</code></dt> + <dd>(特定のログのオープン)</dd> + + <dt><code>ap_hook_auth_checker</code></dt> + <dd>(リソースが権限を必要とするかどうかの確認)</dd> + + <dt><code>ap_hook_access_checker</code></dt> + <dd>(モジュール固有の制約の確認)</dd> + + <dt><code>ap_hook_check_user_id</code></dt> + <dd>(ユーザ ID とパスワードの確認)</dd> + + <dt><code>ap_hook_default_port</code></dt> + <dd>(サーバのデフォルト・ポートの取得)</dd> + + <dt><code>ap_hook_pre_connection</code></dt> + <dd>(処理の直前に必要なことを実行。ただし accept 直後に呼ばれる)</dd> + + <dt><code>ap_hook_process_connection</code></dt> + <dd>(プロトコルの処理)</dd> + + <dt><code>ap_hook_child_init</code></dt> + <dd>(子プロセル起動直後)</dd> + + <dt><code>ap_hook_create_request</code></dt> + <dd>(??)</dd> + + <dt><code>ap_hook_fixups</code></dt> + <dd>(応答内容の生成を変更するラスト・チャンス)</dd> + + <dt><code>ap_hook_handler</code></dt> + <dd>(応答内容の生成)</dd> + + <dt><code>ap_hook_header_parser</code></dt> + <dd>(モジュールにヘッダの照会をさせる。ほとんどのモジュールでは使われません。post_read_request を使います)</dd> + + <dt><code>ap_hook_insert_filter</code></dt> + <dd>(フィルタ・チェインにフィルタを挿入)</dd> + + <dt><code>ap_hook_log_transaction</code></dt> + <dd>(リクエストについての情報を記録する)</dd> + + <dt><code>ap_hook_optional_fn_retrieve</code></dt> + <dd>(オプションとして登録された関数の取得)</dd> + + <dt><code>ap_hook_post_read_request</code></dt> + <dd>(リクエストを読みこんだ後、他のフェーズの前に呼ばれる)</dd> + + <dt><code>ap_hook_quick_handler</code></dt> + <dd>リクエストの処理が始まる前に呼ばれる。キャッシュモジュールが + 使用している</dd> + + <dt><code>ap_hook_translate_name</code></dt> + <dd>(URI をファイル名に変換する)</dd> + + <dt><code>ap_hook_type_checker</code></dt> + <dd>(文書型の決定と設定。あるいはその片方)</dd> + </dl> + +</div></div> +<div class="bottomlang"> +<p><span>Available Languages: </span><a href="../en/developer/modules.html" hreflang="en" rel="alternate" title="English"> en </a> | +<a href="../ja/developer/modules.html" title="Japanese"> ja </a></p> +</div><div id="footer"> +<p class="apache">Copyright 2009 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p> +<p class="menu"><a href="../mod/">モジュール</a> | <a href="../mod/directives.html">ディレクティブ</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">用語</a> | <a href="../sitemap.html">サイトマップ</a></p></div> +</body></html>
\ No newline at end of file diff --git a/rubbos/app/httpd-2.0.64/docs/manual/developer/request.html b/rubbos/app/httpd-2.0.64/docs/manual/developer/request.html new file mode 100644 index 00000000..ed3694f6 --- /dev/null +++ b/rubbos/app/httpd-2.0.64/docs/manual/developer/request.html @@ -0,0 +1,5 @@ +# GENERATED FROM XML -- DO NOT EDIT + +URI: request.html.en +Content-Language: en +Content-type: text/html; charset=ISO-8859-1 diff --git a/rubbos/app/httpd-2.0.64/docs/manual/developer/request.html.en b/rubbos/app/httpd-2.0.64/docs/manual/developer/request.html.en new file mode 100644 index 00000000..1ac89d24 --- /dev/null +++ b/rubbos/app/httpd-2.0.64/docs/manual/developer/request.html.en @@ -0,0 +1,260 @@ +<?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>Request Processing in Apache 2.0 - 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.0</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/">Documentation</a> > <a href="../">Version 2.0</a> > <a href="./">Developer Documentation</a></div><div id="page-content"><div id="preamble"><h1>Request Processing in Apache 2.0</h1> +<div class="toplang"> +<p><span>Available Languages: </span><a href="../en/developer/request.html" title="English"> en </a></p> +</div> + + <div class="warning"><h3>Warning</h3> + <p>Warning - this is a first (fast) draft that needs further + revision!</p> + </div> + + <p>Several changes in Apache 2.0 affect the internal request + processing mechanics. Module authors need to be aware of these + changes so they may take advantage of the optimizations and + security enhancements.</p> + + <p>The first major change is to the subrequest and redirect + mechanisms. There were a number of different code paths in + Apache 1.3 to attempt to optimize subrequest or redirect + behavior. As patches were introduced to 2.0, these + optimizations (and the server behavior) were quickly broken due + to this duplication of code. All duplicate code has been folded + back into <code>ap_process_request_internal()</code> to prevent + the code from falling out of sync again.</p> + + <p>This means that much of the existing code was 'unoptimized'. + It is the Apache HTTP Project's first goal to create a robust + and correct implementation of the HTTP server RFC. Additional + goals include security, scalability and optimization. New + methods were sought to optimize the server (beyond the + performance of Apache 1.3) without introducing fragile or + insecure code.</p> +</div> +<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#processing">The Request Processing Cycle</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#parsing">The Request Parsing Phase</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#security">The Security Phase</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#preparation">The Preparation Phase</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#handler">The Handler Phase</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="processing" id="processing">The Request Processing Cycle</a></h2> + <p>All requests pass through <code>ap_process_request_internal()</code> + in <code>request.c</code>, including subrequests and redirects. If a module + doesn't pass generated requests through this code, the author is cautioned + that the module may be broken by future changes to request + processing.</p> + + <p>To streamline requests, the module author can take advantage + of the hooks offered to drop out of the request cycle early, or + to bypass core Apache hooks which are irrelevant (and costly in + terms of CPU.)</p> +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="parsing" id="parsing">The Request Parsing Phase</a></h2> + <h3><a name="unescape" id="unescape">Unescapes the URL</a></h3> + <p>The request's <code>parsed_uri</code> path is unescaped, once and only + once, at the beginning of internal request processing.</p> + + <p>This step is bypassed if the proxyreq flag is set, or the + <code>parsed_uri.path</code> element is unset. The module has no further + control of this one-time unescape operation, either failing to + unescape or multiply unescaping the URL leads to security + reprecussions.</p> + + + <h3><a name="strip" id="strip">Strips Parent and This Elements from the + URI</a></h3> + <p>All <code>/../</code> and <code>/./</code> elements are + removed by <code>ap_getparents()</code>. This helps to ensure + the path is (nearly) absolute before the request processing + continues.</p> + + <p>This step cannot be bypassed.</p> + + + <h3><a name="inital-location-walk" id="inital-location-walk">Initial URI Location Walk</a></h3> + <p>Every request is subject to an + <code>ap_location_walk()</code> call. This ensures that + <code class="directive"><a href="../mod/core.html#location"><Location></a></code> sections + are consistently enforced for all requests. If the request is an internal + redirect or a sub-request, it may borrow some or all of the processing + from the previous or parent request's ap_location_walk, so this step + is generally very efficient after processing the main request.</p> + + + <h3><a name="translate_name" id="translate_name">translate_name</a></h3> + <p>Modules can determine the file name, or alter the given URI + in this step. For example, <code class="module"><a href="../mod/mod_vhost_alias.html">mod_vhost_alias</a></code> will + translate the URI's path into the configured virtual host, + <code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> will translate the path to an alias path, + and if the request falls back on the core, the <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code> is prepended to the request resource.</p> + + <p>If all modules <code>DECLINE</code> this phase, an error 500 is + returned to the browser, and a "couldn't translate name" error is logged + automatically.</p> + + + <h3><a name="map_to_storage" id="map_to_storage">Hook: map_to_storage</a></h3> + <p>After the file or correct URI was determined, the + appropriate per-dir configurations are merged together. For + example, <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> compares and merges the appropriate + <code class="directive"><a href="../mod/mod_proxy.html#proxy"><Proxy></a></code> sections. + If the URI is nothing more than a local (non-proxy) <code>TRACE</code> + request, the core handles the request and returns <code>DONE</code>. + If no module answers this hook with <code>OK</code> or <code>DONE</code>, + the core will run the request filename against the <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> and <code class="directive"><a href="../mod/core.html#files"><Files></a></code> sections. If the request + 'filename' isn't an absolute, legal filename, a note is set for + later termination.</p> + + + <h3><a name="location-walk" id="location-walk">URI Location Walk</a></h3> + <p>Every request is hardened by a second + <code>ap_location_walk()</code> call. This reassures that a + translated request is still subjected to the configured + <code class="directive"><a href="../mod/core.html#location"><Location></a></code> sections. + The request again borrows some or all of the processing from its previous + <code>location_walk</code> above, so this step is almost always very + efficient unless the translated URI mapped to a substantially different + path or Virtual Host.</p> + + + <h3><a name="header_parser" id="header_parser">Hook: header_parser</a></h3> + <p>The main request then parses the client's headers. This + prepares the remaining request processing steps to better serve + the client's request.</p> + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="security" id="security">The Security Phase</a></h2> + <p>Needs Documentation. Code is:</p> + + <div class="example"><pre> +switch (ap_satisfies(r)) { +case SATISFY_ALL: +case SATISFY_NOSPEC: + if ((access_status = ap_run_access_checker(r)) != 0) { + return decl_die(access_status, "check access", r); + } + + if (ap_some_auth_required(r)) { + if (((access_status = ap_run_check_user_id(r)) != 0) + || !ap_auth_type(r)) { + return decl_die(access_status, ap_auth_type(r) + ? "check user. No user file?" + : "perform authentication. AuthType not set!", + r); + } + + if (((access_status = ap_run_auth_checker(r)) != 0) + || !ap_auth_type(r)) { + return decl_die(access_status, ap_auth_type(r) + ? "check access. No groups file?" + : "perform authentication. AuthType not set!", + r); + } + } + break; + +case SATISFY_ANY: + if (((access_status = ap_run_access_checker(r)) != 0)) { + if (!ap_some_auth_required(r)) { + return decl_die(access_status, "check access", r); + } + + if (((access_status = ap_run_check_user_id(r)) != 0) + || !ap_auth_type(r)) { + return decl_die(access_status, ap_auth_type(r) + ? "check user. No user file?" + : "perform authentication. AuthType not set!", + r); + } + + if (((access_status = ap_run_auth_checker(r)) != 0) + || !ap_auth_type(r)) { + return decl_die(access_status, ap_auth_type(r) + ? "check access. No groups file?" + : "perform authentication. AuthType not set!", + r); + } + } + break; +}</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="preparation" id="preparation">The Preparation Phase</a></h2> + <h3><a name="type_checker" id="type_checker">Hook: type_checker</a></h3> + <p>The modules have an opportunity to test the URI or filename + against the target resource, and set mime information for the + request. Both <code class="module"><a href="../mod/mod_mime.html">mod_mime</a></code> and + <code class="module"><a href="../mod/mod_mime_magic.html">mod_mime_magic</a></code> use this phase to compare the file + name or contents against the administrator's configuration and set the + content type, language, character set and request handler. Some modules + may set up their filters or other request handling parameters at this + time.</p> + + <p>If all modules <code>DECLINE</code> this phase, an error 500 is + returned to the browser, and a "couldn't find types" error is logged + automatically.</p> + + + <h3><a name="fixups" id="fixups">Hook: fixups</a></h3> + <p>Many modules are 'trounced' by some phase above. The fixups + phase is used by modules to 'reassert' their ownership or force + the request's fields to their appropriate values. It isn't + always the cleanest mechanism, but occasionally it's the only + option.</p> + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="handler" id="handler">The Handler Phase</a></h2> + <p>This phase is <strong>not</strong> part of the processing in + <code>ap_process_request_internal()</code>. Many + modules prepare one or more subrequests prior to creating any + content at all. After the core, or a module calls + <code>ap_process_request_internal()</code> it then calls + <code>ap_invoke_handler()</code> to generate the request.</p> + + <h3><a name="insert_filter" id="insert_filter">Hook: insert_filter</a></h3> + <p>Modules that transform the content in some way can insert + their values and override existing filters, such that if the + user configured a more advanced filter out-of-order, then the + module can move its order as need be. There is no result code, + so actions in this hook better be trusted to always succeed.</p> + + + <h3><a name="hook_handler" id="hook_handler">Hook: handler</a></h3> + <p>The module finally has a chance to serve the request in its + handler hook. Note that not every prepared request is sent to + the handler hook. Many modules, such as <code class="module"><a href="../mod/mod_autoindex.html">mod_autoindex</a></code>, + will create subrequests for a given URI, and then never serve the + subrequest, but simply lists it for the user. Remember not to + put required teardown from the hooks above into this module, + but register pool cleanups against the request pool to free + resources as required.</p> + +</div></div> +<div class="bottomlang"> +<p><span>Available Languages: </span><a href="../en/developer/request.html" title="English"> en </a></p> +</div><div id="footer"> +<p class="apache">Copyright 2009 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</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/rubbos/app/httpd-2.0.64/docs/manual/developer/thread_safety.html b/rubbos/app/httpd-2.0.64/docs/manual/developer/thread_safety.html new file mode 100644 index 00000000..50f07bf3 --- /dev/null +++ b/rubbos/app/httpd-2.0.64/docs/manual/developer/thread_safety.html @@ -0,0 +1,5 @@ +# GENERATED FROM XML -- DO NOT EDIT + +URI: thread_safety.html.en +Content-Language: en +Content-type: text/html; charset=ISO-8859-1 diff --git a/rubbos/app/httpd-2.0.64/docs/manual/developer/thread_safety.html.en b/rubbos/app/httpd-2.0.64/docs/manual/developer/thread_safety.html.en new file mode 100644 index 00000000..82b4e5a7 --- /dev/null +++ b/rubbos/app/httpd-2.0.64/docs/manual/developer/thread_safety.html.en @@ -0,0 +1,285 @@ +<?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 2.0 Thread Safety Issues - 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.0</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/">Documentation</a> > <a href="../">Version 2.0</a> > <a href="./">Developer Documentation</a></div><div id="page-content"><div id="preamble"><h1>Apache 2.0 Thread Safety Issues</h1> +<div class="toplang"> +<p><span>Available Languages: </span><a href="../en/developer/thread_safety.html" title="English"> en </a></p> +</div> + + <p>When using any of the threaded mpms in Apache 2.0 it is important + that every function called from Apache be thread safe. When linking in 3rd + party extensions it can be difficult to determine whether the resulting + server will be thread safe. Casual testing generally won't tell you this + either as thread safety problems can lead to subtle race conditons that + may only show up in certain conditions under heavy load.</p> +</div> +<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#variables">Global and static variables</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#errno">errno</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#functions">Common standard troublesome functions</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#commonlibs">Common 3rd Party Libraries</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#liblist">Library List</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="variables" id="variables">Global and static variables</a></h2> + <p>When writing your module or when trying to determine if a module or + 3rd party library is thread safe there are some common things to keep in + mind.</p> + + <p>First, you need to recognize that in a threaded model each individual + thread has its own program counter, stack and registers. Local variables + live on the stack, so those are fine. You need to watch out for any + static or global variables. This doesn't mean that you are absolutely not + allowed to use static or global variables. There are times when you + actually want something to affect all threads, but generally you need to + avoid using them if you want your code to be thread safe.</p> + + <p>In the case where you have a global variable that needs to be global and + accessed by all threads, be very careful when you update it. If, for + example, it is an incrementing counter, you need to atomically increment + it to avoid race conditions with other threads. You do this using a mutex + (mutual exclusion). Lock the mutex, read the current value, increment it + and write it back and then unlock the mutex. Any other thread that wants + to modify the value has to first check the mutex and block until it is + cleared.</p> + + <p>If you are using <a href="http://apr.apache.org/">APR</a>, have a look + at the <code>apr_atomic_<var>*</var></code> functions and the + <code>apr_thread_mutex_<var>*</var></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="errno" id="errno">errno</a></h2> + <p>This is a common global variable that holds the error number of the + last error that occurred. If one thread calls a low-level function that + sets errno and then another thread checks it, we are bleeding error + numbers from one thread into another. To solve this, make sure your + module or library defines <code>_REENTRANT</code> or is compiled with + <code>-D_REENTRANT</code>. This will make errno a per-thread variable + and should hopefully be transparent to the code. It does this by doing + something like this:</p> + + <div class="example"><p><code> + #define errno (*(__errno_location())) + </code></p></div> + + <p>which means that accessing errno will call + <code>__errno_location()</code> which is provided by the libc. Setting + <code>_REENTRANT</code> also forces redefinition of some other functions + to their <code><var>*</var>_r</code> equivalents and sometimes changes + the common <code>getc</code>/<code>putc</code> macros into safer function + calls. Check your libc documentation for specifics. Instead of, or in + addition to <code>_REENTRANT</code> the symbols that may affect this are + <code>_POSIX_C_SOURCE</code>, <code>_THREAD_SAFE</code>, + <code>_SVID_SOURCE</code>, and <code>_BSD_SOURCE</code>.</p> +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="functions" id="functions">Common standard troublesome functions</a></h2> + <p>Not only do things have to be thread safe, but they also have to be + reentrant. <code>strtok()</code> is an obvious one. You call it the first + time with your delimiter which it then remembers and on each subsequent + call it returns the next token. Obviously if multiple threads are + calling it you will have a problem. Most systems have a reentrant version + of of the function called <code>strtok_r()</code> where you pass in an + extra argument which contains an allocated <code>char *</code> which the + function will use instead of its own static storage for maintaining + the tokenizing state. If you are using <a href="http://apr.apache.org/">APR</a> you can use <code>apr_strtok()</code>.</p> + + <p><code>crypt()</code> is another function that tends to not be reentrant, + so if you run across calls to that function in a library, watch out. On + some systems it is reentrant though, so it is not always a problem. If + your system has <code>crypt_r()</code> chances are you should be using + that, or if possible simply avoid the whole mess by using md5 instead.</p> + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="commonlibs" id="commonlibs">Common 3rd Party Libraries</a></h2> + <p>The following is a list of common libraries that are used by 3rd party + Apache modules. You can check to see if your module is using a potentially + unsafe library by using tools such as <code>ldd(1)</code> and + <code>nm(1)</code>. For <a href="http://www.php.net/">PHP</a>, for example, + try this:</p> + + <div class="example"><p><code> + % ldd libphp4.so<br /> + libsablot.so.0 => /usr/local/lib/libsablot.so.0 (0x401f6000)<br /> + libexpat.so.0 => /usr/lib/libexpat.so.0 (0x402da000)<br /> + libsnmp.so.0 => /usr/lib/libsnmp.so.0 (0x402f9000)<br /> + libpdf.so.1 => /usr/local/lib/libpdf.so.1 (0x40353000)<br /> + libz.so.1 => /usr/lib/libz.so.1 (0x403e2000)<br /> + libpng.so.2 => /usr/lib/libpng.so.2 (0x403f0000)<br /> + libmysqlclient.so.11 => /usr/lib/libmysqlclient.so.11 (0x40411000)<br /> + libming.so => /usr/lib/libming.so (0x40449000)<br /> + libm.so.6 => /lib/libm.so.6 (0x40487000)<br /> + libfreetype.so.6 => /usr/lib/libfreetype.so.6 (0x404a8000)<br /> + libjpeg.so.62 => /usr/lib/libjpeg.so.62 (0x404e7000)<br /> + libcrypt.so.1 => /lib/libcrypt.so.1 (0x40505000)<br /> + libssl.so.2 => /lib/libssl.so.2 (0x40532000)<br /> + libcrypto.so.2 => /lib/libcrypto.so.2 (0x40560000)<br /> + libresolv.so.2 => /lib/libresolv.so.2 (0x40624000)<br /> + libdl.so.2 => /lib/libdl.so.2 (0x40634000)<br /> + libnsl.so.1 => /lib/libnsl.so.1 (0x40637000)<br /> + libc.so.6 => /lib/libc.so.6 (0x4064b000)<br /> + /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x80000000) + </code></p></div> + + <p>In addition to these libraries you will need to have a look at any + libraries linked statically into the module. You can use <code>nm(1)</code> + to look for individual symbols in the module.</p> +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="liblist" id="liblist">Library List</a></h2> + <p>Please drop a note to <a href="http://httpd.apache.org/lists.html#http-dev">dev@httpd.apache.org</a> + if you have additions or corrections to this list.</p> + + <table class="bordered"><tr class="header"><th>Library</th><th>Version</th><th>Thread Safe?</th><th>Notes</th></tr> +<tr><td><a href="http://aspell.sourceforge.net/">ASpell/PSpell</a></td> + <td> </td> + <td>?</td> + <td> </td></tr> +<tr class="odd"><td><a href="http://www.sleepycat.com/">Berkeley DB</a></td> + <td>3.x, 4.x</td> + <td>Yes</td> + <td>Be careful about sharing a connection across threads.</td></tr> +<tr><td><a href="http://sources.redhat.com/bzip2/index.html">bzip2</a></td> + <td> </td> + <td>Yes</td> + <td>Both low-level and high-level APIs are thread-safe. However, + high-level API requires thread-safe access to errno.</td></tr> +<tr class="odd"><td><a href="http://cr.yp.to/cdb.html">cdb</a></td> + <td> </td> + <td>?</td> + <td> </td></tr> +<tr><td><a href="http://www.washington.edu/imap/">C-Client</a></td> + <td> </td> + <td>Perhaps</td> + <td>c-client uses <code>strtok()</code> and + <code>gethostbyname()</code> which are not thread-safe on most C + library implementations. c-client's static data is meant to be shared + across threads. If <code>strtok()</code> and + <code>gethostbyname()</code> are thread-safe on your OS, c-client + <em>may</em> be thread-safe.</td></tr> +<tr class="odd"><td><a href="http://www.fastio.com/">cpdflib</a></td> + <td> </td> + <td>?</td> + <td> </td></tr> +<tr><td><a href="http://www.ijg.org/files/">libcrypt</a></td> + <td> </td> + <td>?</td> + <td> </td></tr> +<tr class="odd"><td><a href="http://expat.sourceforge.net/">Expat</a></td> + <td> </td> + <td>Yes</td> + <td>Need a separate parser instance per thread</td></tr> +<tr><td><a href="http://www.freetds.org/">FreeTDS</a></td> + <td> </td> + <td>?</td> + <td> </td></tr> +<tr class="odd"><td><a href="http://www.freetype.org/">FreeType</a></td> + <td> </td> + <td>?</td> + <td> </td></tr> +<tr><td><a href="http://www.boutell.com/gd/">GD 1.8.x</a></td> + <td> </td> + <td>?</td> + <td> </td></tr> +<tr class="odd"><td><a href="http://www.boutell.com/gd/">GD 2.0.x</a></td> + <td> </td> + <td>?</td> + <td> </td></tr> +<tr><td><a href="http://www.gnu.org/software/gdbm/gdbm.html">gdbm</a></td> + <td> </td> + <td>No</td> + <td>Errors returned via a static <code>gdbm_error</code> + variable</td></tr> +<tr class="odd"><td><a href="http://www.imagemagick.org/">ImageMagick</a></td> + <td>5.2.2</td> + <td>Yes</td> + <td>ImageMagick docs claim it is thread safe since version 5.2.2 (see <a href="http://www.cise.ufl.edu/depot/www/ImageMagick/www/Changelog.html">Change log</a>). + </td></tr> +<tr><td><a href="http://www.enlightenment.org/pages/imlib2.html">Imlib2</a></td> + <td> </td> + <td>?</td> + <td> </td></tr> +<tr class="odd"><td><a href="http://www.ijg.org/files/">libjpeg</a></td> + <td>v6b</td> + <td>?</td> + <td> </td></tr> +<tr><td><a href="http://mysql.com">libmysqlclient</a></td> + <td> </td> + <td>Yes</td> + <td>Use mysqlclient_r library variant to ensure thread-safety. For + more information, please read <a href="http://www.mysql.com/doc/en/Threaded_clients.html">http://www.mysql.com/doc/en/Threaded_clients.html</a>.</td></tr> +<tr class="odd"><td><a href="http://www.opaque.net/ming/">Ming</a></td> + <td>0.2a</td> + <td>?</td> + <td> </td></tr> +<tr><td><a href="http://net-snmp.sourceforge.net/">Net-SNMP</a></td> + <td>5.0.x</td> + <td>?</td> + <td> </td></tr> +<tr class="odd"><td><a href="http://www.openldap.org/">OpenLDAP</a></td> + <td>2.1.x</td> + <td>Yes</td> + <td>Use <code>ldap_r</code> library variant to ensure + thread-safety.</td></tr> +<tr><td><a href="http://www.openssl.org/">OpenSSL</a></td> + <td>0.9.6g</td> + <td>Yes</td> + <td>Requires proper usage of <code>CRYPTO_num_locks</code>, + <code>CRYPTO_set_locking_callback</code>, + <code>CRYPTO_set_id_callback</code></td></tr> +<tr class="odd"><td><a href="http://www.oracle.com/">liboci8 (Oracle 8+)</a></td> + <td>8.x,9.x</td> + <td>?</td> + <td> </td></tr> +<tr><td><a href="http://pdflib.com/">pdflib</a></td> + <td>5.0.x</td> + <td>Yes</td> + <td>PDFLib docs claim it is thread safe; changes.txt indicates it + has been partially thread-safe since V1.91: <a href="http://www.pdflib.com/products/pdflib/index.html">http://www.pdflib.com/products/pdflib/index.html</a>.</td></tr> +<tr class="odd"><td><a href="http://www.libpng.org/pub/png/libpng.html">libpng</a></td> + <td>1.0.x</td> + <td>?</td> + <td> </td></tr> +<tr><td><a href="http://www.libpng.org/pub/png/libpng.html">libpng</a></td> + <td>1.2.x</td> + <td>?</td> + <td> </td></tr> +<tr class="odd"><td><a href="http://www.postgresql.org/idocs/index.php?libpq-threading.html">libpq (PostgreSQL)</a></td> + <td>7.x</td> + <td>Yes</td> + <td>Don't share connections across threads and watch out for + <code>crypt()</code> calls</td></tr> +<tr><td><a href="http://www.gingerall.com/charlie/ga/xml/p_sab.xml">Sablotron</a></td> + <td>0.95</td> + <td>?</td> + <td /></tr> +<tr class="odd"><td><a href="http://www.gzip.org/zlib/">zlib</a></td> + <td>1.1.4</td> + <td>Yes</td> + <td>Relies upon thread-safe zalloc and zfree functions Default is to + use libc's calloc/free which are thread-safe.</td></tr> +</table> +</div></div> +<div class="bottomlang"> +<p><span>Available Languages: </span><a href="../en/developer/thread_safety.html" title="English"> en </a></p> +</div><div id="footer"> +<p class="apache">Copyright 2009 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</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 |