coar 98/05/02 18:24:11
Added: apidoc README dict-ap_cpystrn.html
dict-ap_destroy_pool.html
dict-ap_make_sub_pool.html
Log:
Some initial population for the API docco development directory.
Seeds as it were..
Revision Changes Path
1.1 apache-devsite/apidoc/README
Index: README
===================================================================
This directory (apidoc) is the development area for an effort to document
the Apache Web server API (Application Programing Interface). In its
current incarnation, there are four types of files here:
. a data file (api.list) that contains a record for each API entity; this
file is internally documented as to format
. a template file (api-dict.html) which is used as the basis for the
assembled documentation
. HTML fragment files (e.g., dict-ap_destroy_pool.html), one per API
entity, that contain the actual documentation for the entities
. a Perl script (mkapi) which puts all of these together to generate a
single monolithic documentation file
There are currently four types of API entities defined: routines, constants,
structures, and global data cells.
The assembled output file labels each entity as a link target; the name
of the target is the entity name (e.g., HREF="#OK", HREF="ap_die").
Entity references in specifications and examples are automatically linked
to the appropriate definitions (e.g., the 'request_rec' text in the example
"ap_child_terminate(rerquest_rec *r)" is automatically a link to the
definition of the request_rec structure).
Documentation fragment files should look like this (leading whitespace
included):
<P>
..entity documentation..
</P>
<P>
..more docco..
</P>
1.1 apache-devsite/apidoc/dict-ap_cpystrn.html
Index: dict-ap_cpystrn.html
===================================================================
<P>
Copies at most <SAMP>numbytes</SAMP> of <SAMP>str</SAMP> to
<SAMP>buf</SAMP>.
Differs from <SAMP>strncpy()</SAMP> in that <SAMP>buf</SAMP> is
<EM>always</EM> null terminated, but is <EM>not</EM> null filled.
Therefore, <SAMP>buf</SAMP> should always be at least
<SAMP>numbytes + 1</SAMP> bytes long.
Returns a pointer to the terminating <SAMP>'\0</SAMP>'.
</P>
1.1 apache-devsite/apidoc/dict-ap_destroy_pool.html
Index: dict-ap_destroy_pool.html
===================================================================
<P>
This function will recursively destroy the specified
<A HREF="#pool">pool</A> allocation area and any sub-pools of it,
making any memory allocated to them available for use elsewhere.
</P>
1.1 apache-devsite/apidoc/dict-ap_make_sub_pool.html
Index: dict-ap_make_sub_pool.html
===================================================================
<P>
This function creates a new <A HREF="#pool">pool area</A>
for memory allocation. The
new area is considered to be a "child" of the pool
passed to the routine; this permits a hierarchy of related storage
areas. When a pool is destroyed (see
<A HREF="#ap_destroy_pool"><SAMP>ap_destroy_pool</SAMP></A>),
any sub-pools it may have are also destroyed recursively.
</P>
<P>
An example of when this hierarchy concept is useful can be found in the
<A HREF="http://www.apache.org/docs/mod/mod_autoindex.html";
>automatic directory listing module</A>. Since the module can't
tell in advance how many files it will have to list, nor how long the
names will be, nor what other functions might need to allocate memory
to process the request, it creates a sub-pool of the one associated
with the request, does the <em>per</EM>-filename processing in
it, and clears it for each new file.
</P>
<P>
If the pointer passed to <SAMP>ap_make_sub_pool</SAMP> is <CODE>NULL</CODE>,
a new top-level (<EM>i.e.</EM>, parentless) pool is created. This
is generally not recommended, however, since the only record of a
pool's existence is the pointer returned - a simple logic error can
result in pools being created and lost, along with any allocations
made in them. Most pools are created to deal with <EM>per</EM>-request
processing, and hence should be sub-pools of the request's pool
(<A HREF="#request_rec"><SAMP>r->pool</SAMP></A>) to ensure that
they are properly cleaned up on request completion.
</P>
