granicus.if.org Git - apache/blob - docs/manual/developer/API.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       -->
   8 <title>Apache 1.3 API notes - Apache HTTP Server</title>
   9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" />
  12 <script src="../style/scripts/prettify.js" type="text/javascript">
  13 </script>
  14
  15 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  16 <body id="manual-page"><div id="page-header">
  17 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  18 <p class="apache">Apache HTTP Server Version 2.5</p>
  19 <img alt="" src="../images/feather.gif" /></div>
  20 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  21 <div id="path">
  22 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.5</a> &gt; <a href="./">Developer Documentation</a></div><div id="page-content"><div id="preamble"><h1>Apache 1.3 API notes</h1>
  23 <div class="toplang">
  24 <p><span>Available Languages: </span><a href="../en/developer/API.html" title="English">&nbsp;en&nbsp;</a></p>
  25 </div>
  26
  27     <div class="warning"><h3>Warning</h3>
  28       <p>This document has not been updated to take into account changes made
  29       in the 2.0 version of the Apache HTTP Server. Some of the information may
  30       still be relevant, but please use it with care.</p>
  31     </div>
  32
  33     <p>These are some notes on the Apache API and the data structures you have
  34     to deal with, <em>etc.</em> They are not yet nearly complete, but hopefully,
  35     they will help you get your bearings. Keep in mind that the API is still
  36     subject to change as we gain experience with it. (See the TODO file for
  37     what <em>might</em> be coming). However, it will be easy to adapt modules
  38     to any changes that are made. (We have more modules to adapt than you
  39     do).</p>
  40
  41     <p>A few notes on general pedagogical style here. In the interest of
  42     conciseness, all structure declarations here are incomplete -- the real
  43     ones have more slots that I'm not telling you about. For the most part,
  44     these are reserved to one component of the server core or another, and
  45     should be altered by modules with caution. However, in some cases, they
  46     really are things I just haven't gotten around to yet. Welcome to the
  47     bleeding edge.</p>
  48
  49     <p>Finally, here's an outline, to give you some bare idea of what's coming
  50     up, and in what order:</p>
  51
  52     <ul>
  53       <li>
  54         <a href="#basics">Basic concepts.</a>
  55
  56         <ul>
  57           <li><a href="#HMR">Handlers, Modules, and
  58           Requests</a></li>
  59
  60           <li><a href="#moduletour">A brief tour of a
  61           module</a></li>
  62         </ul>
  63       </li>
  64
  65       <li>
  66         <a href="#handlers">How handlers work</a>
  67
  68         <ul>
  69           <li><a href="#req_tour">A brief tour of the
  70           <code>request_rec</code></a></li>
  71
  72           <li><a href="#req_orig">Where request_rec structures come
  73           from</a></li>
  74
  75           <li><a href="#req_return">Handling requests, declining,
  76           and returning error codes</a></li>
  77
  78           <li><a href="#resp_handlers">Special considerations for
  79           response handlers</a></li>
  80
  81           <li><a href="#auth_handlers">Special considerations for
  82           authentication handlers</a></li>
  83
  84           <li><a href="#log_handlers">Special considerations for
  85           logging handlers</a></li>
  86         </ul>
  87       </li>
  88
  89       <li><a href="#pools">Resource allocation and resource
  90       pools</a></li>
  91
  92       <li>
  93         <a href="#config">Configuration, commands and the like</a>
  94
  95         <ul>
  96           <li><a href="#per-dir">Per-directory configuration
  97           structures</a></li>
  98
  99           <li><a href="#commands">Command handling</a></li>
 100
 101           <li><a href="#servconf">Side notes --- per-server
 102           configuration, virtual servers, <em>etc</em>.</a></li>
 103         </ul>
 104       </li>
 105     </ul>
 106 </div>
 107 <div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#basics">Basic concepts</a></li>
 108 <li><img alt="" src="../images/down.gif" /> <a href="#handlers">How handlers work</a></li>
 109 <li><img alt="" src="../images/down.gif" /> <a href="#pools">Resource allocation and resource pools</a></li>
 110 <li><img alt="" src="../images/down.gif" /> <a href="#config">Configuration, commands and the like</a></li>
 111 </ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
 112 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 113 <div class="section">
 114 <h2><a name="basics" id="basics">Basic concepts</a></h2>
 115     <p>We begin with an overview of the basic concepts behind the API, and how
 116     they are manifested in the code.</p>
 117
 118     <h3><a name="HMR" id="HMR">Handlers, Modules, and Requests</a></h3>
 119       <p>Apache breaks down request handling into a series of steps, more or
 120       less the same way the Netscape server API does (although this API has a
 121       few more stages than NetSite does, as hooks for stuff I thought might be
 122       useful in the future). These are:</p>
 123
 124       <ul>
 125       <li>URI -&gt; Filename translation</li>
 126       <li>Auth ID checking [is the user who they say they are?]</li>
 127       <li>Auth access checking [is the user authorized <em>here</em>?]</li>
 128       <li>Access checking other than auth</li>
 129       <li>Determining MIME type of the object requested</li>
 130       <li>`Fixups' -- there aren't any of these yet, but the phase is intended
 131       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>
 132       <li>Actually sending a response back to the client.</li>
 133       <li>Logging the request</li>
 134       </ul>
 135
 136       <p>These phases are handled by looking at each of a succession of
 137       <em>modules</em>, looking to see if each of them has a handler for the
 138       phase, and attempting invoking it if so. The handler can typically do one
 139       of three things:</p>
 140
 141       <ul>
 142       <li><em>Handle</em> the request, and indicate that it has done so by
 143       returning the magic constant <code>OK</code>.</li>
 144
 145       <li><em>Decline</em> to handle the request, by returning the magic integer
 146       constant <code>DECLINED</code>. In this case, the server behaves in all
 147       respects as if the handler simply hadn't been there.</li>
 148
 149       <li>Signal an error, by returning one of the HTTP error codes. This
 150       terminates normal handling of the request, although an ErrorDocument may
 151       be invoked to try to mop up, and it will be logged in any case.</li>
 152       </ul>
 153
 154       <p>Most phases are terminated by the first module that handles them;
 155       however, for logging, `fixups', and non-access authentication checking,
 156       all handlers always run (barring an error). Also, the response phase is
 157       unique in that modules may declare multiple handlers for it, via a
 158       dispatch table keyed on the MIME type of the requested object. Modules may
 159       declare a response-phase handler which can handle <em>any</em> request,
 160       by giving it the key <code>*/*</code> (<em>i.e.</em>, a wildcard MIME type
 161       specification). However, wildcard handlers are only invoked if the server
 162       has already tried and failed to find a more specific response handler for
 163       the MIME type of the requested object (either none existed, or they all
 164       declined).</p>
 165
 166       <p>The handlers themselves are functions of one argument (a
 167       <code>request_rec</code> structure. vide infra), which returns an integer,
 168       as above.</p>
 169
 170
 171     <h3><a name="moduletour" id="moduletour">A brief tour of a module</a></h3>
 172       <p>At this point, we need to explain the structure of a module. Our
 173       candidate will be one of the messier ones, the CGI module -- this handles
 174       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
 175       more complicated than most modules, but if we're going to have only one
 176       example, it might as well be the one with its fingers in every place.</p>
 177
 178       <p>Let's begin with handlers. In order to handle the CGI scripts, the
 179       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
 180       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
 181       <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>ed request is typed
 182       as a CGI script).</p>
 183
 184       <p>The module needs to maintain some per (virtual) server information,
 185       namely, the <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>es in
 186       effect; the module structure therefore contains pointers to a functions
 187       which builds these structures, and to another which combines two of them
 188       (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>
 189
 190       <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
 191       module only declares one command, but there could be more, so modules have
 192       <em>command tables</em> which declare their commands, and describe where
 193       they are permitted, and how they are to be invoked.</p>
 194
 195       <p>A final note on the declared types of the arguments of some of these
 196       commands: a <code>pool</code> is a pointer to a <em>resource pool</em>
 197       structure; these are used by the server to keep track of the memory which
 198       has been allocated, files opened, <em>etc.</em>, either to service a
 199       particular request, or to handle the process of configuring itself. That
 200       way, when the request is over (or, for the configuration pool, when the
 201       server is restarting), the memory can be freed, and the files closed,
 202       <em>en masse</em>, without anyone having to write explicit code to track
 203       them all down and dispose of them. Also, a <code>cmd_parms</code>
 204       structure contains various information about the config file being read,
 205       and other status information, which is sometimes of use to the function
 206       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
 207       module itself:</p>
 208
 209       <div class="example"><p><code>
 210         /* Declarations of handlers. */<br />
 211         <br />
 212         int translate_scriptalias (request_rec *);<br />
 213         int type_scriptalias (request_rec *);<br />
 214         int cgi_handler (request_rec *);<br />
 215         <br />
 216         /* Subsidiary dispatch table for response-phase <br />
 217         &nbsp;* handlers, by MIME type */<br />
 218         <br />
 219         handler_rec cgi_handlers[] = {<br />
 220         <span class="indent">
 221           { "application/x-httpd-cgi", cgi_handler },<br />
 222           { NULL }<br />
 223         </span>
 224         };<br />
 225         <br />
 226         /* Declarations of routines to manipulate the <br />
 227         &nbsp;* module's configuration info.  Note that these are<br />
 228         &nbsp;* returned, and passed in, as void *'s; the server<br />
 229         &nbsp;* core keeps track of them, but it doesn't, and can't,<br />
 230         &nbsp;* know their internal structure.<br />
 231         &nbsp;*/<br />
 232         <br />
 233         void *make_cgi_server_config (pool *);<br />
 234         void *merge_cgi_server_config (pool *, void *, void *);<br />
 235         <br />
 236         /* Declarations of routines to handle config-file commands */<br />
 237         <br />
 238         extern char *script_alias(cmd_parms *, void *per_dir_config, char *fake,
 239                                   char *real);<br />
 240         <br />
 241         command_rec cgi_cmds[] = {<br />
 242         <span class="indent">
 243           { "ScriptAlias", script_alias, NULL, RSRC_CONF, TAKE2,<br />
 244           <span class="indent">"a fakename and a realname"},<br /></span>
 245           { NULL }<br />
 246         </span>
 247         };<br />
 248         <br />
 249         module cgi_module = {
 250 </code></p><pre>  STANDARD_MODULE_STUFF,
 251   NULL,                     /* initializer */
 252   NULL,                     /* dir config creator */
 253   NULL,                     /* dir merger */
 254   make_cgi_server_config,   /* server config */
 255   merge_cgi_server_config,  /* merge server config */
 256   cgi_cmds,                 /* command table */
 257   cgi_handlers,             /* handlers */
 258   translate_scriptalias,    /* filename translation */
 259   NULL,                     /* check_user_id */
 260   NULL,                     /* check auth */
 261   NULL,                     /* check access */
 262   type_scriptalias,         /* type_checker */
 263   NULL,                     /* fixups */
 264   NULL,                     /* logger */
 265   NULL                      /* header parser */
 266 };</pre></div>
 267
 268 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 269 <div class="section">
 270 <h2><a name="handlers" id="handlers">How handlers work</a></h2>
 271     <p>The sole argument to handlers is a <code>request_rec</code> structure.
 272     This structure describes a particular request which has been made to the
 273     server, on behalf of a client. In most cases, each connection to the
 274     client generates only one <code>request_rec</code> structure.</p>
 275
 276     <h3><a name="req_tour" id="req_tour">A brief tour of the request_rec</a></h3>
 277       <p>The <code>request_rec</code> contains pointers to a resource pool
 278       which will be cleared when the server is finished handling the request;
 279       to structures containing per-server and per-connection information, and
 280       most importantly, information on the request itself.</p>
 281
 282       <p>The most important such information is a small set of character strings
 283       describing attributes of the object being requested, including its URI,
 284       filename, content-type and content-encoding (these being filled in by the
 285       translation and type-check handlers which handle the request,
 286       respectively).</p>
 287
 288       <p>Other commonly used data items are tables giving the MIME headers on
 289       the client's original request, MIME headers to be sent back with the
 290       response (which modules can add to at will), and environment variables for
 291       any subprocesses which are spawned off in the course of servicing the
 292       request. These tables are manipulated using the <code>ap_table_get</code>
 293       and <code>ap_table_set</code> routines.</p>
 294
 295       <div class="note">
 296         <p>Note that the <code>Content-type</code> header value <em>cannot</em>
 297         be set by module content-handlers using the <code>ap_table_*()</code>
 298         routines. Rather, it is set by pointing the <code>content_type</code>
 299         field in the <code>request_rec</code> structure to an appropriate
 300         string. <em>e.g.</em>,</p>
 301         <div class="example"><p><code>
 302           r-&gt;content_type = "text/html";
 303         </code></p></div>
 304       </div>
 305
 306       <p>Finally, there are pointers to two data structures which, in turn,
 307       point to per-module configuration structures. Specifically, these hold
 308       pointers to the data structures which the module has built to describe
 309       the way it has been configured to operate in a given directory (via
 310       <code>.htaccess</code> files or <code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code> sections), for private data it has built in the
 311       course of servicing the request (so modules' handlers for one phase can
 312       pass `notes' to their handlers for other phases). There is another such
 313       configuration vector in the <code>server_rec</code> data structure pointed
 314       to by the <code>request_rec</code>, which contains per (virtual) server
 315       configuration data.</p>
 316
 317       <p>Here is an abridged declaration, giving the fields most commonly
 318       used:</p>
 319
 320       <div class="example"><p><code>
 321         struct request_rec {<br />
 322         <br />
 323         pool *pool;<br />
 324         conn_rec *connection;<br />
 325         server_rec *server;<br />
 326         <br />
 327         /* What object is being requested */<br />
 328         <br />
 329         char *uri;<br />
 330         char *filename;<br />
 331         char *path_info;
 332 </code></p><pre>char *args;           /* QUERY_ARGS, if any */
 333 struct stat finfo;    /* Set by server core;
 334                        * st_mode set to zero if no such file */</pre><p><code>
 335         char *content_type;<br />
 336         char *content_encoding;<br />
 337         <br />
 338         /* MIME header environments, in and out. Also, <br />
 339         &nbsp;* an array containing environment variables to<br />
 340         &nbsp;* be passed to subprocesses, so people can write<br />
 341         &nbsp;* modules to add to that environment.<br />
 342         &nbsp;*<br />
 343         &nbsp;* The difference between headers_out and <br />
 344         &nbsp;* err_headers_out is that the latter are printed <br />
 345         &nbsp;* even on error, and persist across internal<br />
 346         &nbsp;* redirects (so the headers printed for <br />
 347         &nbsp;* <code class="directive"><a href="../mod/core.html#errordocument">ErrorDocument</a></code> handlers will have
 348          them).<br />
 349         &nbsp;*/<br />
 350          <br />
 351         table *headers_in;<br />
 352         table *headers_out;<br />
 353         table *err_headers_out;<br />
 354         table *subprocess_env;<br />
 355         <br />
 356         /* Info about the request itself... */<br />
 357         <br />
 358 </code></p><pre>int header_only;     /* HEAD request, as opposed to GET */
 359 char *protocol;      /* Protocol, as given to us, or HTTP/0.9 */
 360 char *method;        /* GET, HEAD, POST, <em>etc.</em> */
 361 int method_number;   /* M_GET, M_POST, <em>etc.</em> */
 362
 363 </pre><p><code>
 364         /* Info for logging */<br />
 365         <br />
 366         char *the_request;<br />
 367         int bytes_sent;<br />
 368         <br />
 369         /* A flag which modules can set, to indicate that<br />
 370         &nbsp;* the data being returned is volatile, and clients<br />
 371         &nbsp;* should be told not to cache it.<br />
 372         &nbsp;*/<br />
 373         <br />
 374         int no_cache;<br />
 375         <br />
 376         /* Various other config info which may change<br />
 377         &nbsp;* with .htaccess files<br />
 378         &nbsp;* These are config vectors, with one void*<br />
 379         &nbsp;* pointer for each module (the thing pointed<br />
 380         &nbsp;* to being the module's business).<br />
 381         &nbsp;*/<br />
 382         <br />
 383 </code></p><pre>void *per_dir_config;   /* Options set in config files, <em>etc.</em> */
 384 void *request_config;   /* Notes on *this* request */</pre><p><code>
 385         <br />
 386         };
 387       </code></p></div>
 388
 389
 390     <h3><a name="req_orig" id="req_orig">Where request_rec structures come from</a></h3>
 391       <p>Most <code>request_rec</code> structures are built by reading an HTTP
 392       request from a client, and filling in the fields. However, there are a
 393       few exceptions:</p>
 394
 395       <ul>
 396       <li>If the request is to an imagemap, a type map (<em>i.e.</em>, a
 397       <code>*.var</code> file), or a CGI script which returned a local
 398       `Location:', then the resource which the user requested is going to be
 399       ultimately located by some URI other than what the client originally
 400       supplied. In this case, the server does an <em>internal redirect</em>,
 401       constructing a new <code>request_rec</code> for the new URI, and
 402       processing it almost exactly as if the client had requested the new URI
 403       directly.</li>
 404
 405       <li>If some handler signaled an error, and an <code>ErrorDocument</code>
 406       is in scope, the same internal redirect machinery comes into play.</li>
 407
 408       <li><p>Finally, a handler occasionally needs to investigate `what would
 409       happen if' some other request were run. For instance, the directory
 410       indexing module needs to know what MIME type would be assigned to a
 411       request for each directory entry, in order to figure out what icon to
 412       use.</p>
 413
 414       <p>Such handlers can construct a <em>sub-request</em>, using the
 415       functions <code>ap_sub_req_lookup_file</code>,
 416       <code>ap_sub_req_lookup_uri</code>, and <code>ap_sub_req_method_uri</code>;
 417       these construct a new <code>request_rec</code> structure and processes it
 418       as you would expect, up to but not including the point of actually sending
 419       a response. (These functions skip over the access checks if the
 420       sub-request is for a file in the same directory as the original
 421       request).</p>
 422
 423       <p>(Server-side includes work by building sub-requests and then actually
 424       invoking the response handler for them, via the function
 425       <code>ap_run_sub_req</code>).</p>
 426       </li>
 427       </ul>
 428
 429
 430     <h3><a name="req_return" id="req_return">Handling requests, declining, and returning
 431     error codes</a></h3>
 432       <p>As discussed above, each handler, when invoked to handle a particular
 433       <code>request_rec</code>, has to return an <code>int</code> to indicate
 434       what happened. That can either be</p>
 435
 436       <ul>
 437       <li><code>OK</code> -- the request was handled successfully. This may or
 438       may not terminate the phase.</li>
 439
 440       <li><code>DECLINED</code> -- no erroneous condition exists, but the module
 441       declines to handle the phase; the server tries to find another.</li>
 442
 443       <li>an HTTP error code, which aborts handling of the request.</li>
 444       </ul>
 445
 446       <p>Note that if the error code returned is <code>REDIRECT</code>, then
 447       the module should put a <code>Location</code> in the request's
 448       <code>headers_out</code>, to indicate where the client should be
 449       redirected <em>to</em>.</p>
 450
 451
 452     <h3><a name="resp_handlers" id="resp_handlers">Special considerations for response
 453     handlers</a></h3>
 454       <p>Handlers for most phases do their work by simply setting a few fields
 455       in the <code>request_rec</code> structure (or, in the case of access
 456       checkers, simply by returning the correct error code). However, response
 457       handlers have to actually send a request back to the client.</p>
 458
 459       <p>They should begin by sending an HTTP response header, using the
 460       function <code>ap_send_http_header</code>. (You don't have to do anything
 461       special to skip sending the header for HTTP/0.9 requests; the function
 462       figures out on its own that it shouldn't do anything). If the request is
 463       marked <code>header_only</code>, that's all they should do; they should
 464       return after that, without attempting any further output.</p>
 465
 466       <p>Otherwise, they should produce a request body which responds to the
 467       client as appropriate. The primitives for this are <code>ap_rputc</code>
 468       and <code>ap_rprintf</code>, for internally generated output, and
 469       <code>ap_send_fd</code>, to copy the contents of some <code>FILE *</code>
 470       straight to the client.</p>
 471
 472       <p>At this point, you should more or less understand the following piece
 473       of code, which is the handler which handles <code>GET</code> requests
 474       which have no more specific handler; it also shows how conditional
 475       <code>GET</code>s can be handled, if it's desirable to do so in a
 476       particular response handler -- <code>ap_set_last_modified</code> checks
 477       against the <code>If-modified-since</code> value supplied by the client,
 478       if any, and returns an appropriate code (which will, if nonzero, be
 479       USE_LOCAL_COPY). No similar considerations apply for
 480       <code>ap_set_content_length</code>, but it returns an error code for
 481       symmetry.</p>
 482
 483       <div class="example"><p><code>
 484         int default_handler (request_rec *r)<br />
 485         {<br />
 486         <span class="indent">
 487           int errstatus;<br />
 488           FILE *f;<br />
 489           <br />
 490           if (r-&gt;method_number != M_GET) return DECLINED;<br />
 491           if (r-&gt;finfo.st_mode == 0) return NOT_FOUND;<br />
 492           <br />
 493           if ((errstatus = ap_set_content_length (r, r-&gt;finfo.st_size))<br />
 494           &nbsp;&nbsp;&nbsp;&nbsp;||
 495              (errstatus = ap_set_last_modified (r, r-&gt;finfo.st_mtime)))<br />
 496           return errstatus;<br />
 497           <br />
 498           f = fopen (r-&gt;filename, "r");<br />
 499           <br />
 500           if (f == NULL) {<br />
 501           <span class="indent">
 502             log_reason("file permissions deny server access", r-&gt;filename, r);<br />
 503             return FORBIDDEN;<br />
 504           </span>
 505           }<br />
 506           <br />
 507           register_timeout ("send", r);<br />
 508           ap_send_http_header (r);<br />
 509           <br />
 510           if (!r-&gt;header_only) send_fd (f, r);<br />
 511           ap_pfclose (r-&gt;pool, f);<br />
 512           return OK;<br />
 513         </span>
 514         }
 515       </code></p></div>
 516
 517       <p>Finally, if all of this is too much of a challenge, there are a few
 518       ways out of it. First off, as shown above, a response handler which has
 519       not yet produced any output can simply return an error code, in which
 520       case the server will automatically produce an error response. Secondly,
 521       it can punt to some other handler by invoking
 522       <code>ap_internal_redirect</code>, which is how the internal redirection
 523       machinery discussed above is invoked. A response handler which has
 524       internally redirected should always return <code>OK</code>.</p>
 525
 526       <p>(Invoking <code>ap_internal_redirect</code> from handlers which are
 527       <em>not</em> response handlers will lead to serious confusion).</p>
 528
 529
 530     <h3><a name="auth_handlers" id="auth_handlers">Special considerations for authentication
 531     handlers</a></h3>
 532       <p>Stuff that should be discussed here in detail:</p>
 533
 534       <ul>
 535       <li>Authentication-phase handlers not invoked unless auth is
 536       configured for the directory.</li>
 537
 538       <li>Common auth configuration stored in the core per-dir
 539       configuration; it has accessors <code>ap_auth_type</code>,
 540       <code>ap_auth_name</code>, and <code>ap_requires</code>.</li>
 541
 542       <li>Common routines, to handle the protocol end of things, at
 543       least for HTTP basic authentication
 544       (<code>ap_get_basic_auth_pw</code>, which sets the
 545       <code>connection-&gt;user</code> structure field
 546       automatically, and <code>ap_note_basic_auth_failure</code>,
 547       which arranges for the proper <code>WWW-Authenticate:</code>
 548       header to be sent back).</li>
 549       </ul>
 550
 551
 552     <h3><a name="log_handlers" id="log_handlers">Special considerations for logging
 553     handlers</a></h3>
 554       <p>When a request has internally redirected, there is the question of
 555       what to log. Apache handles this by bundling the entire chain of redirects
 556       into a list of <code>request_rec</code> structures which are threaded
 557       through the <code>r-&gt;prev</code> and <code>r-&gt;next</code> pointers.
 558       The <code>request_rec</code> which is passed to the logging handlers in
 559       such cases is the one which was originally built for the initial request
 560       from the client; note that the <code>bytes_sent</code> field will only be
 561       correct in the last request in the chain (the one for which a response was
 562       actually sent).</p>
 563
 564 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 565 <div class="section">
 566 <h2><a name="pools" id="pools">Resource allocation and resource pools</a></h2>
 567     <p>One of the problems of writing and designing a server-pool server is
 568     that of preventing leakage, that is, allocating resources (memory, open
 569     files, <em>etc.</em>), without subsequently releasing them. The resource
 570     pool machinery is designed to make it easy to prevent this from happening,
 571     by allowing resource to be allocated in such a way that they are
 572     <em>automatically</em> released when the server is done with them.</p>
 573
 574     <p>The way this works is as follows: the memory which is allocated, file
 575     opened, <em>etc.</em>, to deal with a particular request are tied to a
 576     <em>resource pool</em> which is allocated for the request. The pool is a
 577     data structure which itself tracks the resources in question.</p>
 578
 579     <p>When the request has been processed, the pool is <em>cleared</em>. At
 580     that point, all the memory associated with it is released for reuse, all
 581     files associated with it are closed, and any other clean-up functions which
 582     are associated with the pool are run. When this is over, we can be confident
 583     that all the resource tied to the pool have been released, and that none of
 584     them have leaked.</p>
 585
 586     <p>Server restarts, and allocation of memory and resources for per-server
 587     configuration, are handled in a similar way. There is a <em>configuration
 588     pool</em>, which keeps track of resources which were allocated while reading
 589     the server configuration files, and handling the commands therein (for
 590     instance, the memory that was allocated for per-server module configuration,
 591     log files and other files that were opened, and so forth). When the server
 592     restarts, and has to reread the configuration files, the configuration pool
 593     is cleared, and so the memory and file descriptors which were taken up by
 594     reading them the last time are made available for reuse.</p>
 595
 596     <p>It should be noted that use of the pool machinery isn't generally
 597     obligatory, except for situations like logging handlers, where you really
 598     need to register cleanups to make sure that the log file gets closed when
 599     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
 600     underlying file descriptor to be closed before any child processes, such as
 601     for CGI scripts, are <code>exec</code>ed), or in case you are using the
 602     timeout machinery (which isn't yet even documented here). However, there are
 603     two benefits to using it: resources allocated to a pool never leak (even if
 604     you allocate a scratch string, and just forget about it); also, for memory
 605     allocation, <code>ap_palloc</code> is generally faster than
 606     <code>malloc</code>.</p>
 607
 608     <p>We begin here by describing how memory is allocated to pools, and then
 609     discuss how other resources are tracked by the resource pool machinery.</p>
 610
 611     <h3>Allocation of memory in pools</h3>
 612       <p>Memory is allocated to pools by calling the function
 613       <code>ap_palloc</code>, which takes two arguments, one being a pointer to
 614       a resource pool structure, and the other being the amount of memory to
 615       allocate (in <code>char</code>s). Within handlers for handling requests,
 616       the most common way of getting a resource pool structure is by looking at
 617       the <code>pool</code> slot of the relevant <code>request_rec</code>; hence
 618       the repeated appearance of the following idiom in module code:</p>
 619
 620       <div class="example"><p><code>
 621         int my_handler(request_rec *r)<br />
 622         {<br />
 623         <span class="indent">
 624           struct my_structure *foo;<br />
 625           ...<br />
 626           <br />
 627           foo = (foo *)ap_palloc (r-&gt;pool, sizeof(my_structure));<br />
 628         </span>
 629         }
 630       </code></p></div>
 631
 632       <p>Note that <em>there is no <code>ap_pfree</code></em> --
 633       <code>ap_palloc</code>ed memory is freed only when the associated resource
 634       pool is cleared. This means that <code>ap_palloc</code> does not have to
 635       do as much accounting as <code>malloc()</code>; all it does in the typical
 636       case is to round up the size, bump a pointer, and do a range check.</p>
 637
 638       <p>(It also raises the possibility that heavy use of
 639       <code>ap_palloc</code> could cause a server process to grow excessively
 640       large. There are two ways to deal with this, which are dealt with below;
 641       briefly, you can use <code>malloc</code>, and try to be sure that all of
 642       the memory gets explicitly <code>free</code>d, or you can allocate a
 643       sub-pool of the main pool, allocate your memory in the sub-pool, and clear
 644       it out periodically. The latter technique is discussed in the section
 645       on sub-pools below, and is used in the directory-indexing code, in order
 646       to avoid excessive storage allocation when listing directories with
 647       thousands of files).</p>
 648
 649
 650     <h3>Allocating initialized memory</h3>
 651       <p>There are functions which allocate initialized memory, and are
 652       frequently useful. The function <code>ap_pcalloc</code> has the same
 653       interface as <code>ap_palloc</code>, but clears out the memory it
 654       allocates before it returns it. The function <code>ap_pstrdup</code>
 655       takes a resource pool and a <code>char *</code> as arguments, and
 656       allocates memory for a copy of the string the pointer points to, returning
 657       a pointer to the copy. Finally <code>ap_pstrcat</code> is a varargs-style
 658       function, which takes a pointer to a resource pool, and at least two
 659       <code>char *</code> arguments, the last of which must be
 660       <code>NULL</code>. It allocates enough memory to fit copies of each of
 661       the strings, as a unit; for instance:</p>
 662
 663       <div class="example"><p><code>
 664         ap_pstrcat (r-&gt;pool, "foo", "/", "bar", NULL);
 665       </code></p></div>
 666
 667       <p>returns a pointer to 8 bytes worth of memory, initialized to
 668       <code>"foo/bar"</code>.</p>
 669
 670
 671     <h3><a name="pools-used" id="pools-used">Commonly-used pools in the Apache Web
 672     server</a></h3>
 673       <p>A pool is really defined by its lifetime more than anything else.
 674       There are some static pools in http_main which are passed to various
 675       non-http_main functions as arguments at opportune times. Here they
 676       are:</p>
 677
 678       <dl>
 679       <dt><code>permanent_pool</code></dt>
 680       <dd>never passed to anything else, this is the ancestor of all pools</dd>
 681
 682       <dt><code>pconf</code></dt>
 683       <dd>
 684         <ul>
 685           <li>subpool of permanent_pool</li>
 686
 687           <li>created at the beginning of a config "cycle"; exists
 688           until the server is terminated or restarts; passed to all
 689           config-time routines, either via cmd-&gt;pool, or as the
 690           "pool *p" argument on those which don't take pools</li>
 691
 692           <li>passed to the module init() functions</li>
 693         </ul>
 694       </dd>
 695
 696       <dt><code>ptemp</code></dt>
 697       <dd>
 698         <ul>
 699           <li>sorry I lie, this pool isn't called this currently in
 700           1.3, I renamed it this in my pthreads development. I'm
 701           referring to the use of ptrans in the parent... contrast
 702           this with the later definition of ptrans in the
 703           child.</li>
 704
 705           <li>subpool of permanent_pool</li>
 706
 707           <li>created at the beginning of a config "cycle"; exists
 708           until the end of config parsing; passed to config-time
 709           routines <em>via</em> cmd-&gt;temp_pool. Somewhat of a
 710           "bastard child" because it isn't available everywhere.
 711           Used for temporary scratch space which may be needed by
 712           some config routines but which is deleted at the end of
 713           config.</li>
 714         </ul>
 715       </dd>
 716
 717       <dt><code>pchild</code></dt>
 718       <dd>
 719         <ul>
 720           <li>subpool of permanent_pool</li>
 721
 722           <li>created when a child is spawned (or a thread is
 723           created); lives until that child (thread) is
 724           destroyed</li>
 725
 726           <li>passed to the module child_init functions</li>
 727
 728           <li>destruction happens right after the child_exit
 729           functions are called... (which may explain why I think
 730           child_exit is redundant and unneeded)</li>
 731         </ul>
 732       </dd>
 733
 734       <dt><code>ptrans</code></dt>
 735       <dd>
 736         <ul>
 737           <li>should be a subpool of pchild, but currently is a
 738           subpool of permanent_pool, see above</li>
 739
 740           <li>cleared by the child before going into the accept()
 741           loop to receive a connection</li>
 742
 743           <li>used as connection-&gt;pool</li>
 744         </ul>
 745       </dd>
 746
 747       <dt><code>r-&gt;pool</code></dt>
 748       <dd>
 749         <ul>
 750           <li>for the main request this is a subpool of
 751           connection-&gt;pool; for subrequests it is a subpool of
 752           the parent request's pool.</li>
 753
 754           <li>exists until the end of the request (<em>i.e.</em>,
 755           ap_destroy_sub_req, or in child_main after
 756           process_request has finished)</li>
 757
 758           <li>note that r itself is allocated from r-&gt;pool;
 759           <em>i.e.</em>, r-&gt;pool is first created and then r is
 760           the first thing palloc()d from it</li>
 761         </ul>
 762       </dd>
 763       </dl>
 764
 765       <p>For almost everything folks do, <code>r-&gt;pool</code> is the pool to
 766       use. But you can see how other lifetimes, such as pchild, are useful to
 767       some modules... such as modules that need to open a database connection
 768       once per child, and wish to clean it up when the child dies.</p>
 769
 770       <p>You can also see how some bugs have manifested themself, such as
 771       setting <code>connection-&gt;user</code> to a value from
 772       <code>r-&gt;pool</code> -- in this case connection exists for the
 773       lifetime of <code>ptrans</code>, which is longer than
 774       <code>r-&gt;pool</code> (especially if <code>r-&gt;pool</code> is a
 775       subrequest!). So the correct thing to do is to allocate from
 776       <code>connection-&gt;pool</code>.</p>
 777
 778       <p>And there was another interesting bug in <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>
 779       / <code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code>. You'll see in those that they do this test
 780       to decide if they should use <code>r-&gt;pool</code> or
 781       <code>r-&gt;main-&gt;pool</code>. In this case the resource that they are
 782       registering for cleanup is a child process. If it were registered in
 783       <code>r-&gt;pool</code>, then the code would <code>wait()</code> for the
 784       child when the subrequest finishes. With <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> this
 785       could be any old <code>#include</code>, and the delay can be up to 3
 786       seconds... and happened quite frequently. Instead the subprocess is
 787       registered in <code>r-&gt;main-&gt;pool</code> which causes it to be
 788       cleaned up when the entire request is done -- <em>i.e.</em>, after the
 789       output has been sent to the client and logging has happened.</p>
 790
 791
 792     <h3><a name="pool-files" id="pool-files">Tracking open files, etc.</a></h3>
 793       <p>As indicated above, resource pools are also used to track other sorts
 794       of resources besides memory. The most common are open files. The routine
 795       which is typically used for this is <code>ap_pfopen</code>, which takes a
 796       resource pool and two strings as arguments; the strings are the same as
 797       the typical arguments to <code>fopen</code>, <em>e.g.</em>,</p>
 798
 799       <div class="example"><p><code>
 800         ...<br />
 801         FILE *f = ap_pfopen (r-&gt;pool, r-&gt;filename, "r");<br />
 802         <br />
 803         if (f == NULL) { ... } else { ... }<br />
 804       </code></p></div>
 805
 806       <p>There is also a <code>ap_popenf</code> routine, which parallels the
 807       lower-level <code>open</code> system call. Both of these routines arrange
 808       for the file to be closed when the resource pool in question is
 809       cleared.</p>
 810
 811       <p>Unlike the case for memory, there <em>are</em> functions to close files
 812       allocated with <code>ap_pfopen</code>, and <code>ap_popenf</code>, namely
 813       <code>ap_pfclose</code> and <code>ap_pclosef</code>. (This is because, on
 814       many systems, the number of files which a single process can have open is
 815       quite limited). It is important to use these functions to close files
 816       allocated with <code>ap_pfopen</code> and <code>ap_popenf</code>, since to
 817       do otherwise could cause fatal errors on systems such as Linux, which
 818       react badly if the same <code>FILE*</code> is closed more than once.</p>
 819
 820       <p>(Using the <code>close</code> functions is not mandatory, since the
 821       file will eventually be closed regardless, but you should consider it in
 822       cases where your module is opening, or could open, a lot of files).</p>
 823
 824
 825     <h3>Other sorts of resources -- cleanup functions</h3>
 826       <p>More text goes here. Describe the cleanup primitives in terms of
 827       which the file stuff is implemented; also, <code>spawn_process</code>.</p>
 828
 829       <p>Pool cleanups live until <code>clear_pool()</code> is called:
 830       <code>clear_pool(a)</code> recursively calls <code>destroy_pool()</code>
 831       on all subpools of <code>a</code>; then calls all the cleanups for
 832       <code>a</code>; then releases all the memory for <code>a</code>.
 833       <code>destroy_pool(a)</code> calls <code>clear_pool(a)</code> and then
 834       releases the pool structure itself. <em>i.e.</em>,
 835       <code>clear_pool(a)</code> doesn't delete <code>a</code>, it just frees
 836       up all the resources and you can start using it again immediately.</p>
 837
 838
 839     <h3>Fine control -- creating and dealing with sub-pools, with
 840     a note on sub-requests</h3>
 841       <p>On rare occasions, too-free use of <code>ap_palloc()</code> and the
 842       associated primitives may result in undesirably profligate resource
 843       allocation. You can deal with such a case by creating a <em>sub-pool</em>,
 844       allocating within the sub-pool rather than the main pool, and clearing or
 845       destroying the sub-pool, which releases the resources which were
 846       associated with it. (This really <em>is</em> a rare situation; the only
 847       case in which it comes up in the standard module set is in case of listing
 848       directories, and then only with <em>very</em> large directories.
 849       Unnecessary use of the primitives discussed here can hair up your code
 850       quite a bit, with very little gain).</p>
 851
 852       <p>The primitive for creating a sub-pool is <code>ap_make_sub_pool</code>,
 853       which takes another pool (the parent pool) as an argument. When the main
 854       pool is cleared, the sub-pool will be destroyed. The sub-pool may also be
 855       cleared or destroyed at any time, by calling the functions
 856       <code>ap_clear_pool</code> and <code>ap_destroy_pool</code>, respectively.
 857       (The difference is that <code>ap_clear_pool</code> frees resources
 858       associated with the pool, while <code>ap_destroy_pool</code> also
 859       deallocates the pool itself. In the former case, you can allocate new
 860       resources within the pool, and clear it again, and so forth; in the
 861       latter case, it is simply gone).</p>
 862
 863       <p>One final note -- sub-requests have their own resource pools, which are
 864       sub-pools of the resource pool for the main request. The polite way to
 865       reclaim the resources associated with a sub request which you have
 866       allocated (using the <code>ap_sub_req_...</code> functions) is
 867       <code>ap_destroy_sub_req</code>, which frees the resource pool. Before
 868       calling this function, be sure to copy anything that you care about which
 869       might be allocated in the sub-request's resource pool into someplace a
 870       little less volatile (for instance, the filename in its
 871       <code>request_rec</code> structure).</p>
 872
 873       <p>(Again, under most circumstances, you shouldn't feel obliged to call
 874       this function; only 2K of memory or so are allocated for a typical sub
 875       request, and it will be freed anyway when the main request pool is
 876       cleared. It is only when you are allocating many, many sub-requests for a
 877       single main request that you should seriously consider the
 878       <code>ap_destroy_...</code> functions).</p>
 879
 880 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 881 <div class="section">
 882 <h2><a name="config" id="config">Configuration, commands and the like</a></h2>
 883     <p>One of the design goals for this server was to maintain external
 884     compatibility with the NCSA 1.3 server --- that is, to read the same
 885     configuration files, to process all the directives therein correctly, and
 886     in general to be a drop-in replacement for NCSA. On the other hand, another
 887     design goal was to move as much of the server's functionality into modules
 888     which have as little as possible to do with the monolithic server core. The
 889     only way to reconcile these goals is to move the handling of most commands
 890     from the central server into the modules.</p>
 891
 892     <p>However, just giving the modules command tables is not enough to divorce
 893     them completely from the server core. The server has to remember the
 894     commands in order to act on them later. That involves maintaining data which
 895     is private to the modules, and which can be either per-server, or
 896     per-directory. Most things are per-directory, including in particular access
 897     control and authorization information, but also information on how to
 898     determine file types from suffixes, which can be modified by
 899     <code class="directive"><a href="../mod/mod_mime.html#addtype">AddType</a></code> and <code class="directive"><a href="../mod/core.html#forcetype">ForceType</a></code> directives, and so forth. In general,
 900     the governing philosophy is that anything which <em>can</em> be made
 901     configurable by directory should be; per-server information is generally
 902     used in the standard set of modules for information like
 903     <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
 904     request is tied to a particular place in the underlying file system.</p>
 905
 906     <p>Another requirement for emulating the NCSA server is being able to handle
 907     the per-directory configuration files, generally called
 908     <code>.htaccess</code> files, though even in the NCSA server they can
 909     contain directives which have nothing at all to do with access control.
 910     Accordingly, after URI -&gt; filename translation, but before performing any
 911     other phase, the server walks down the directory hierarchy of the underlying
 912     filesystem, following the translated pathname, to read any
 913     <code>.htaccess</code> files which might be present. The information which
 914     is read in then has to be <em>merged</em> with the applicable information
 915     from the server's own config files (either from the <code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code> sections in
 916     <code>access.conf</code>, or from defaults in <code>srm.conf</code>, which
 917     actually behaves for most purposes almost exactly like <code>&lt;Directory
 918     /&gt;</code>).</p>
 919
 920     <p>Finally, after having served a request which involved reading
 921     <code>.htaccess</code> files, we need to discard the storage allocated for
 922     handling them. That is solved the same way it is solved wherever else
 923     similar problems come up, by tying those structures to the per-transaction
 924     resource pool.</p>
 925
 926     <h3><a name="per-dir" id="per-dir">Per-directory configuration structures</a></h3>
 927       <p>Let's look out how all of this plays out in <code>mod_mime.c</code>,
 928       which defines the file typing handler which emulates the NCSA server's
 929       behavior of determining file types from suffixes. What we'll be looking
 930       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
 931       <code>.htaccess</code> files, so they must be handled in the module's
 932       private per-directory data, which in fact, consists of two separate
 933       tables for MIME types and encoding information, and is declared as
 934       follows:</p>
 935
 936       <div class="example"><pre>typedef struct {
 937     table *forced_types;      /* Additional AddTyped stuff */
 938     table *encoding_types;    /* Added with AddEncoding... */
 939 } mime_dir_config;</pre></div>
 940
 941       <p>When the server is reading a configuration file, or <code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code> section, which includes
 942       one of the MIME module's commands, it needs to create a
 943       <code>mime_dir_config</code> structure, so those commands have something
 944       to act on. It does this by invoking the function it finds in the module's
 945       `create per-dir config slot', with two arguments: the name of the
 946       directory to which this configuration information applies (or
 947       <code>NULL</code> for <code>srm.conf</code>), and a pointer to a
 948       resource pool in which the allocation should happen.</p>
 949
 950       <p>(If we are reading a <code>.htaccess</code> file, that resource pool
 951       is the per-request resource pool for the request; otherwise it is a
 952       resource pool which is used for configuration data, and cleared on
 953       restarts. Either way, it is important for the structure being created to
 954       vanish when the pool is cleared, by registering a cleanup on the pool if
 955       necessary).</p>
 956
 957       <p>For the MIME module, the per-dir config creation function just
 958       <code>ap_palloc</code>s the structure above, and a creates a couple of
 959       tables to fill it. That looks like this:</p>
 960
 961       <div class="example"><p><code>
 962         void *create_mime_dir_config (pool *p, char *dummy)<br />
 963         {<br />
 964         <span class="indent">
 965           mime_dir_config *new =<br />
 966           <span class="indent">
 967            (mime_dir_config *) ap_palloc (p, sizeof(mime_dir_config));<br />
 968           </span>
 969           <br />
 970           new-&gt;forced_types = ap_make_table (p, 4);<br />
 971           new-&gt;encoding_types = ap_make_table (p, 4);<br />
 972           <br />
 973           return new;<br />
 974         </span>
 975         }
 976       </code></p></div>
 977
 978       <p>Now, suppose we've just read in a <code>.htaccess</code> file. We
 979       already have the per-directory configuration structure for the next
 980       directory up in the hierarchy. If the <code>.htaccess</code> file we just
 981       read in didn't have any <code class="directive"><a href="../mod/mod_mime.html#addtype">AddType</a></code>
 982       or <code class="directive"><a href="../mod/mod_mime.html#addencoding">AddEncoding</a></code> commands, its
 983       per-directory config structure for the MIME module is still valid, and we
 984       can just use it. Otherwise, we need to merge the two structures
 985       somehow.</p>
 986
 987       <p>To do that, the server invokes the module's per-directory config merge
 988       function, if one is present. That function takes three arguments: the two
 989       structures being merged, and a resource pool in which to allocate the
 990       result. For the MIME module, all that needs to be done is overlay the
 991       tables from the new per-directory config structure with those from the
 992       parent:</p>
 993
 994       <div class="example"><p><code>
 995         void *merge_mime_dir_configs (pool *p, void *parent_dirv, void *subdirv)<br />
 996         {<br />
 997         <span class="indent">
 998           mime_dir_config *parent_dir = (mime_dir_config *)parent_dirv;<br />
 999           mime_dir_config *subdir = (mime_dir_config *)subdirv;<br />
1000           mime_dir_config *new =<br />
1001           <span class="indent">
1002             (mime_dir_config *)ap_palloc (p, sizeof(mime_dir_config));<br />
1003           </span>
1004           <br />
1005           new-&gt;forced_types = ap_overlay_tables (p, subdir-&gt;forced_types,<br />
1006           <span class="indent">
1007             parent_dir-&gt;forced_types);<br />
1008           </span>
1009           new-&gt;encoding_types = ap_overlay_tables (p, subdir-&gt;encoding_types,<br />
1010           <span class="indent">
1011             parent_dir-&gt;encoding_types);<br />
1012           </span>
1013           <br />
1014           return new;<br />
1015         </span>
1016         }
1017       </code></p></div>
1018
1019       <p>As a note -- if there is no per-directory merge function present, the
1020       server will just use the subdirectory's configuration info, and ignore
1021       the parent's. For some modules, that works just fine (<em>e.g.</em>, for
1022       the includes module, whose per-directory configuration information
1023       consists solely of the state of the <code>XBITHACK</code>), and for those
1024       modules, you can just not declare one, and leave the corresponding
1025       structure slot in the module itself <code>NULL</code>.</p>
1026
1027
1028     <h3><a name="commands" id="commands">Command handling</a></h3>
1029       <p>Now that we have these structures, we need to be able to figure out how
1030       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
1031       the module's command table. That table contains information on how many
1032       arguments the commands take, and in what formats, where it is permitted,
1033       and so forth. That information is sufficient to allow the server to invoke
1034       most command-handling functions with pre-parsed arguments. Without further
1035       ado, let's look at the <code class="directive"><a href="../mod/mod_mime.html#addtype">AddType</a></code>
1036       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
1037       shown here):</p>
1038
1039       <div class="example"><p><code>
1040         char *add_type(cmd_parms *cmd, mime_dir_config *m, char *ct, char *ext)<br />
1041         {<br />
1042         <span class="indent">
1043           if (*ext == '.') ++ext;<br />
1044           ap_table_set (m-&gt;forced_types, ext, ct);<br />
1045           return NULL;<br />
1046         </span>
1047         }
1048       </code></p></div>
1049
1050       <p>This command handler is unusually simple. As you can see, it takes
1051       four arguments, two of which are pre-parsed arguments, the third being the
1052       per-directory configuration structure for the module in question, and the
1053       fourth being a pointer to a <code>cmd_parms</code> structure. That
1054       structure contains a bunch of arguments which are frequently of use to
1055       some, but not all, commands, including a resource pool (from which memory
1056       can be allocated, and to which cleanups should be tied), and the (virtual)
1057       server being configured, from which the module's per-server configuration
1058       data can be obtained if required.</p>
1059
1060       <p>Another way in which this particular command handler is unusually
1061       simple is that there are no error conditions which it can encounter. If
1062       there were, it could return an error message instead of <code>NULL</code>;
1063       this causes an error to be printed out on the server's
1064       <code>stderr</code>, followed by a quick exit, if it is in the main config
1065       files; for a <code>.htaccess</code> file, the syntax error is logged in
1066       the server error log (along with an indication of where it came from), and
1067       the request is bounced with a server error response (HTTP error status,
1068       code 500).</p>
1069
1070       <p>The MIME module's command table has entries for these commands, which
1071       look like this:</p>
1072
1073       <div class="example"><p><code>
1074         command_rec mime_cmds[] = {<br />
1075         <span class="indent">
1076           { "AddType", add_type, NULL, OR_FILEINFO, TAKE2,<br />
1077           <span class="indent">"a mime type followed by a file extension" },<br /></span>
1078           { "AddEncoding", add_encoding, NULL, OR_FILEINFO, TAKE2,<br />
1079           <span class="indent">
1080           "an encoding (<em>e.g.</em>, gzip), followed by a file extension" },<br />
1081           </span>
1082           { NULL }<br />
1083         </span>
1084         };
1085       </code></p></div>
1086
1087       <p>The entries in these tables are:</p>
1088       <ul>
1089       <li>The name of the command</li>
1090       <li>The function which handles it</li>
1091       <li>a <code>(void *)</code> pointer, which is passed in the
1092       <code>cmd_parms</code> structure to the command handler ---
1093       this is useful in case many similar commands are handled by
1094       the same function.</li>
1095
1096       <li>A bit mask indicating where the command may appear. There
1097       are mask bits corresponding to each
1098       <code>AllowOverride</code> option, and an additional mask
1099       bit, <code>RSRC_CONF</code>, indicating that the command may
1100       appear in the server's own config files, but <em>not</em> in
1101       any <code>.htaccess</code> file.</li>
1102
1103       <li>A flag indicating how many arguments the command handler
1104       wants pre-parsed, and how they should be passed in.
1105       <code>TAKE2</code> indicates two pre-parsed arguments. Other
1106       options are <code>TAKE1</code>, which indicates one
1107       pre-parsed argument, <code>FLAG</code>, which indicates that
1108       the argument should be <code>On</code> or <code>Off</code>,
1109       and is passed in as a boolean flag, <code>RAW_ARGS</code>,
1110       which causes the server to give the command the raw, unparsed
1111       arguments (everything but the command name itself). There is
1112       also <code>ITERATE</code>, which means that the handler looks
1113       the same as <code>TAKE1</code>, but that if multiple
1114       arguments are present, it should be called multiple times,
1115       and finally <code>ITERATE2</code>, which indicates that the
1116       command handler looks like a <code>TAKE2</code>, but if more
1117       arguments are present, then it should be called multiple
1118       times, holding the first argument constant.</li>
1119
1120       <li>Finally, we have a string which describes the arguments
1121       that should be present. If the arguments in the actual config
1122       file are not as required, this string will be used to help
1123       give a more specific error message. (You can safely leave
1124       this <code>NULL</code>).</li>
1125       </ul>
1126
1127       <p>Finally, having set this all up, we have to use it. This is ultimately
1128       done in the module's handlers, specifically for its file-typing handler,
1129       which looks more or less like this; note that the per-directory
1130       configuration structure is extracted from the <code>request_rec</code>'s
1131       per-directory configuration vector by using the
1132       <code>ap_get_module_config</code> function.</p>
1133
1134       <div class="example"><p><code>
1135         int find_ct(request_rec *r)<br />
1136         {<br />
1137         <span class="indent">
1138           int i;<br />
1139           char *fn = ap_pstrdup (r-&gt;pool, r-&gt;filename);<br />
1140           mime_dir_config *conf = (mime_dir_config *)<br />
1141           <span class="indent">
1142             ap_get_module_config(r-&gt;per_dir_config, &amp;mime_module);<br />
1143           </span>
1144           char *type;<br />
1145           <br />
1146           if (S_ISDIR(r-&gt;finfo.st_mode)) {<br />
1147           <span class="indent">
1148             r-&gt;content_type = DIR_MAGIC_TYPE;<br />
1149             return OK;<br />
1150           </span>
1151           }<br />
1152           <br />
1153           if((i=ap_rind(fn,'.')) &lt; 0) return DECLINED;<br />
1154           ++i;<br />
1155           <br />
1156           if ((type = ap_table_get (conf-&gt;encoding_types, &amp;fn[i])))<br />
1157           {<br />
1158           <span class="indent">
1159             r-&gt;content_encoding = type;<br />
1160             <br />
1161             /* go back to previous extension to try to use it as a type */<br />
1162             fn[i-1] = '\0';<br />
1163             if((i=ap_rind(fn,'.')) &lt; 0) return OK;<br />
1164             ++i;<br />
1165           </span>
1166           }<br />
1167           <br />
1168           if ((type = ap_table_get (conf-&gt;forced_types, &amp;fn[i])))<br />
1169           {<br />
1170           <span class="indent">
1171             r-&gt;content_type = type;<br />
1172           </span>
1173           }<br />
1174           <br />
1175           return OK;
1176         </span>
1177         }
1178       </code></p></div>
1179
1180
1181     <h3><a name="servconf" id="servconf">Side notes -- per-server configuration,
1182     virtual servers, <em>etc</em>.</a></h3>
1183       <p>The basic ideas behind per-server module configuration are basically
1184       the same as those for per-directory configuration; there is a creation
1185       function and a merge function, the latter being invoked where a virtual
1186       server has partially overridden the base server configuration, and a
1187       combined structure must be computed. (As with per-directory configuration,
1188       the default if no merge function is specified, and a module is configured
1189       in some virtual server, is that the base configuration is simply
1190       ignored).</p>
1191
1192       <p>The only substantial difference is that when a command needs to
1193       configure the per-server private module data, it needs to go to the
1194       <code>cmd_parms</code> data to get at it. Here's an example, from the
1195       alias module, which also indicates how a syntax error can be returned
1196       (note that the per-directory configuration argument to the command
1197       handler is declared as a dummy, since the module doesn't actually have
1198       per-directory config data):</p>
1199
1200       <div class="example"><p><code>
1201         char *add_redirect(cmd_parms *cmd, void *dummy, char *f, char *url)<br />
1202         {<br />
1203         <span class="indent">
1204           server_rec *s = cmd-&gt;server;<br />
1205           alias_server_conf *conf = (alias_server_conf *)<br />
1206           <span class="indent">
1207             ap_get_module_config(s-&gt;module_config,&amp;alias_module);<br />
1208           </span>
1209           alias_entry *new = ap_push_array (conf-&gt;redirects);<br />
1210           <br />
1211           if (!ap_is_url (url)) return "Redirect to non-URL";<br />
1212           <br />
1213           new-&gt;fake = f; new-&gt;real = url;<br />
1214           return NULL;<br />
1215         </span>
1216         }
1217       </code></p></div>
1218
1219 </div></div>
1220 <div class="bottomlang">
1221 <p><span>Available Languages: </span><a href="../en/developer/API.html" title="English">&nbsp;en&nbsp;</a></p>
1222 </div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&amp;A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
1223 <script type="text/javascript"><!--//--><![CDATA[//><!--
1224 var comments_shortname = 'httpd';
1225 var comments_identifier = 'http://httpd.apache.org/docs/trunk/developer/API.html';
1226 (function(w, d) {
1227     if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
1228         d.write('<div id="comments_thread"><\/div>');
1229         var s = d.createElement('script');
1230         s.type = 'text/javascript';
1231         s.async = true;
1232         s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
1233         (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
1234     }
1235     else {
1236         d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
1237     }
1238 })(window, document);
1239 //--><!]]></script></div><div id="footer">
1240 <p class="apache">Copyright 2013 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>
1241 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
1242 if (typeof(prettyPrint) !== 'undefined') {
1243     prettyPrint();
1244 }
1245 //--><!]]></script>
1246 </body></html>