api.html

这个是我在web培训时老师提供的手册

          loop to receive a connection</li>

          <li>used as connection-&gt;pool</li>
        </ul>
      </dd>

      <dt><code>r-&gt;pool</code></dt>
      <dd>
        <ul>
          <li>for the main request this is a subpool of
          connection-&gt;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-&gt;pool;
          <em>i.e.</em>, r-&gt;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-&gt;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-&gt;user</code> to a value from
      <code>r-&gt;pool</code> -- in this case connection exists for the
      lifetime of <code>ptrans</code>, which is longer than
      <code>r-&gt;pool</code> (especially if <code>r-&gt;pool</code> is a
      subrequest!). So the correct thing to do is to allocate from
      <code>connection-&gt;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-&gt;pool</code> or
      <code>r-&gt;main-&gt;pool</code>. In this case the resource that they are
      registering for cleanup is a child process. If it were registered in
      <code>r-&gt;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-&gt;main-&gt;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>, 例如，</p>

      <div class="example"><p><code>
        ...<br />
        FILE *f = ap_pfopen (r-&gt;pool, r-&gt;filename, "r");<br />
        <br />
        if (f == NULL) { ... } else { ... }<br />
      </code></p></div>

      <p>There is also a <code>ap_popenf</code> routine, which parallels the
      lower-level <code>open</code> system call. Both of these routines arrange
      for the file to be closed when the resource pool in question is
      cleared.</p>

      <p>Unlike the case for memory, there <em>are</em> functions to close files
      allocated with <code>ap_pfopen</code>, and <code>ap_popenf</code>, namely
      <code>ap_pfclose</code> and <code>ap_pclosef</code>. (This is because, on
      many systems, the number of files which a single process can have open is
      quite limited). It is important to use these functions to close files
      allocated with <code>ap_pfopen</code> and <code>ap_popenf</code>, since to
      do otherwise could cause fatal errors on systems such as Linux, which
      react badly if the same <code>FILE*</code> is closed more than once.</p>

      <p>(Using the <code>close</code> functions is not mandatory, since the
      file will eventually be closed regardless, but you should consider it in
      cases where your module is opening, or could open, a lot of files).</p>
    

    <h3>Other sorts of resources -- cleanup functions</h3>
      <p>More text goes here. Describe the the cleanup primitives in terms of
      which the file stuff is implemented; also, <code>spawn_process</code>.</p>

      <p>Pool cleanups live until <code>clear_pool()</code> is called:
      <code>clear_pool(a)</code> recursively calls <code>destroy_pool()</code>
      on all subpools of <code>a</code>; then calls all the cleanups for
      <code>a</code>; then releases all the memory for <code>a</code>.
      <code>destroy_pool(a)</code> calls <code>clear_pool(a)</code> and then
      releases the pool structure itself. <em>i.e.</em>,
      <code>clear_pool(a)</code> doesn't delete <code>a</code>, it just frees
      up all the resources and you can start using it again immediately.</p>
    

    <h3>Fine control -- creating and dealing with sub-pools, with
    a note on sub-requests</h3>
      <p>On rare occasions, too-free use of <code>ap_palloc()</code> and the
      associated primitives may result in undesirably profligate resource
      allocation. You can deal with such a case by creating a <em>sub-pool</em>,
      allocating within the sub-pool rather than the main pool, and clearing or
      destroying the sub-pool, which releases the resources which were
      associated with it. (This really <em>is</em> a rare situation; the only
      case in which it comes up in the standard module set is in case of listing
      directories, and then only with <em>very</em> large directories.
      Unnecessary use of the primitives discussed here can hair up your code
      quite a bit, with very little gain).</p>

      <p>The primitive for creating a sub-pool is <code>ap_make_sub_pool</code>,
      which takes another pool (the parent pool) as an argument. When the main
      pool is cleared, the sub-pool will be destroyed. The sub-pool may also be
      cleared or destroyed at any time, by calling the functions
      <code>ap_clear_pool</code> and <code>ap_destroy_pool</code>, respectively.
      (The difference is that <code>ap_clear_pool</code> frees resources
      associated with the pool, while <code>ap_destroy_pool</code> also
      deallocates the pool itself. In the former case, you can allocate new
      resources within the pool, and clear it again, and so forth; in the
      latter case, it is simply gone).</p>

      <p>One final note -- sub-requests have their own resource pools, which are
      sub-pools of the resource pool for the main request. The polite way to
      reclaim the resources associated with a sub request which you have
      allocated (using the <code>ap_sub_req_...</code> functions) is
      <code>ap_destroy_sub_req</code>, which frees the resource pool. Before
      calling this function, be sure to copy anything that you care about which
      might be allocated in the sub-request's resource pool into someplace a
      little less volatile (for instance, the filename in its
      <code>request_rec</code> structure).</p>

      <p>(Again, under most circumstances, you shouldn't feel obliged to call
      this function; only 2K of memory or so are allocated for a typical sub
      request, and it will be freed anyway when the main request pool is
      cleared. It is only when you are allocating many, many sub-requests for a
      single main request that you should seriously consider the
      <code>ap_destroy_...</code> functions).</p>
    
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="config" id="config">Configuration, commands and the like</a></h2>
    <p>One of the design goals for this server was to maintain external
    compatibility with the NCSA 1.3 server --- that is, to read the same
    configuration files, to process all the directives therein correctly, and
    in general to be a drop-in replacement for NCSA. On the other hand, another
    design goal was to move as much of the server's functionality into modules
    which have as little as possible to do with the monolithic server core. The
    only way to reconcile these goals is to move the handling of most commands
    from the central server into the modules.</p>

    <p>However, just giving the modules command tables is not enough to divorce
    them completely from the server core. The server has to remember the
    commands in order to act on them later. That involves maintaining data which
    is private to the modules, and which can be either per-server, or
    per-directory. Most things are per-directory, including in particular access
    control and authorization information, but also information on how to
    determine file types from suffixes, which can be modified by
    <code class="directive"><a href="../mod/mod_mime.html#addtype">AddType</a></code> and <code class="directive"><a href="../mod/core.html#defaulttype">DefaultType</a></code> directives, and so forth. In general,
    the governing philosophy is that anything which <em>can</em> be made
    configurable by directory should be; per-server information is generally
    used in the standard set of modules for information like
    <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code>es and <code class="directive"><a href="../mod/mod_alias.html#redirect">Redirect</a></code>s which come into play before the
    request is tied to a particular place in the underlying file system.</p>

    <p>Another requirement for emulating the NCSA server is being able to handle
    the per-directory configuration files, generally called
    <code>.htaccess</code> files, though even in the NCSA server they can
    contain directives which have nothing at all to do with access control.
    Accordingly, after URI -&gt; 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">&lt;Directory&gt;</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>&lt;Directory
    /&gt;</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">&lt;Directory&gt;</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-&gt;forced_types = ap_make_table (p, 4);<br />
          new-&gt;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