Mailing List Archive

martin 98/04/15 01:50:37

Modified: htdocs/manual/misc API.html
Log:
Oops: csubst missed a couple of old names.

Revision Changes Path
1.14 +45 -45 apache-1.3/htdocs/manual/misc/API.html

Index: API.html
===================================================================
RCS file: /home/cvs/apache-1.3/htdocs/manual/misc/API.html,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -u -r1.13 -r1.14
--- API.html 1998/04/15 08:31:24 1.13
+++ API.html 1998/04/15 08:50:37 1.14
@@ -240,10 +240,10 @@
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>table_get</CODE> and <CODE>table_set</CODE> routines. <P>
+<CODE>ap_table_get</CODE> and <CODE>ap_table_set</CODE> routines. <P>
<BLOCKQUOTE>
Note that the <SAMP>Content-type</SAMP> header value <EM>cannot</EM> be
- set by module content-handlers using the <SAMP>table_*()</SAMP>
+ set by module content-handlers using the <SAMP>ap_table_*()</SAMP>
routines. Rather, it is set by pointing the <SAMP>content_type</SAMP>
field in the <SAMP>request_rec</SAMP> structure to an appropriate
string. <EM>E.g.</EM>,
@@ -397,7 +397,7 @@
response handlers have to actually send a request back to the client. <P>

They should begin by sending an HTTP response header, using the
-function <CODE>send_http_header</CODE>. (You don't have to do
+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
@@ -414,11 +414,11 @@
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>set_last_modified</CODE> checks
+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>set_content_length</CODE>, but it returns an error code for
+<CODE>ap_set_content_length</CODE>, but it returns an error code for
symmetry.<P>

<PRE>
@@ -430,8 +430,8 @@
if (r-&gt;method_number != M_GET) return DECLINED;
if (r-&gt;finfo.st_mode == 0) return NOT_FOUND;

- if ((errstatus = set_content_length (r, r-&gt;finfo.st_size))
- || (errstatus = set_last_modified (r, r-&gt;finfo.st_mtime)))
+ if ((errstatus = ap_set_content_length (r, r-&gt;finfo.st_size))
+ || (errstatus = ap_set_last_modified (r, r-&gt;finfo.st_mtime)))
return errstatus;

f = fopen (r-&gt;filename, "r");
@@ -443,10 +443,10 @@
}

register_timeout ("send", r);
- send_http_header (r);
+ ap_send_http_header (r);

if (!r-&gt;header_only) send_fd (f, r);
- pfclose (r-&gt;pool, f);
+ ap_pfclose (r-&gt;pool, f);
return OK;
}
</PRE>
@@ -456,11 +456,11 @@
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>internal_redirect</CODE>, which is how the internal redirection
+<CODE>ap_internal_redirect</CODE>, which is how the internal redirection
machinery discussed above is invoked. A response handler which has
internally redirected should always return <CODE>OK</CODE>. <P>

-(Invoking <CODE>internal_redirect</CODE> from handlers which are
+(Invoking <CODE>ap_internal_redirect</CODE> from handlers which are
<EM>not</EM> response handlers will lead to serious confusion).

<H3><A name="auth_handlers">Special considerations for authentication handlers</A></H3>
@@ -471,12 +471,12 @@
<LI> Authentication-phase handlers not invoked unless auth is
configured for the directory.
<LI> Common auth configuration stored in the core per-dir
- configuration; it has accessors <CODE>auth_type</CODE>,
- <CODE>auth_name</CODE>, and <CODE>requires</CODE>.
+ configuration; it has accessors <CODE>ap_auth_type</CODE>,
+ <CODE>ap_auth_name</CODE>, and <CODE>ap_requires</CODE>.
<LI> Common routines, to handle the protocol end of things, at least
- for HTTP basic authentication (<CODE>get_basic_auth_pw</CODE>,
+ for HTTP basic authentication (<CODE>ap_get_basic_auth_pw</CODE>,
which sets the <CODE>connection-&gt;user</CODE> structure field
- automatically, and <CODE>note_basic_auth_failure</CODE>, which
+ automatically, and <CODE>ap_note_basic_auth_failure</CODE>, which
arranges for the proper <CODE>WWW-Authenticate:</CODE> header
to be sent back).
</UL>
@@ -537,7 +537,7 @@
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>palloc</CODE> is generally faster than
+allocation, <CODE>ap_palloc</CODE> is generally faster than
<CODE>malloc</CODE>.<P>

We begin here by describing how memory is allocated to pools, and then
@@ -547,7 +547,7 @@
<H3>Allocation of memory in pools</H3>

Memory is allocated to pools by calling the function
-<CODE>palloc</CODE>, which takes two arguments, one being a pointer to
+<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
@@ -561,18 +561,18 @@
struct my_structure *foo;
...

- foo = (foo *)palloc (r-&gt;pool, sizeof(my_structure));
+ foo = (foo *)ap_palloc (r-&gt;pool, sizeof(my_structure));
}
</PRE>

-Note that <EM>there is no <CODE>pfree</CODE></EM> ---
-<CODE>palloc</CODE>ed memory is freed only when the associated
-resource pool is cleared. This means that <CODE>palloc</CODE> does not
+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>

-(It also raises the possibility that heavy use of <CODE>palloc</CODE>
+(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
@@ -586,19 +586,19 @@
<H3>Allocating initialized memory</H3>

There are functions which allocate initialized memory, and are
-frequently useful. The function <CODE>pcalloc</CODE> has the same
-interface as <CODE>palloc</CODE>, but clears out the memory it
-allocates before it returns it. The function <CODE>pstrdup</CODE>
+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>pstrcat</CODE> is a
+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:

<PRE>
- pstrcat (r-&gt;pool, "foo", "/", "bar", NULL);
+ ap_pstrcat (r-&gt;pool, "foo", "/", "bar", NULL);
</PRE>

returns a pointer to 8 bytes worth of memory, initialized to
@@ -608,29 +608,29 @@

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>pfopen</CODE>, which
+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>, e.g.,

<PRE>
...
- FILE *f = pfopen (r-&gt;pool, r-&gt;filename, "r");
+ FILE *f = ap_pfopen (r-&gt;pool, r-&gt;filename, "r");

if (f == NULL) { ... } else { ... }
</PRE>

-There is also a <CODE>popenf</CODE> routine, which parallels the
+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>

Unlike the case for memory, there <EM>are</EM> functions to close
-files allocated with <CODE>pfopen</CODE>, and <CODE>popenf</CODE>,
-namely <CODE>pfclose</CODE> and <CODE>pclosef</CODE>. (This is
+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>pfopen</CODE> and
-<CODE>popenf</CODE>, since to do otherwise could cause fatal errors on
+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>

@@ -646,7 +646,7 @@
<H3>Fine control --- creating and dealing with sub-pools, with a note
on sub-requests</H3>

-On rare occasions, too-free use of <CODE>palloc()</CODE> and the
+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
@@ -658,13 +658,13 @@
discussed here can hair up your code quite a bit, with very little
gain). <P>

-The primitive for creating a sub-pool is <CODE>make_sub_pool</CODE>,
+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>clear_pool</CODE> and <CODE>destroy_pool</CODE>, respectively.
-(The difference is that <CODE>clear_pool</CODE> frees resources
-associated with the pool, while <CODE>destroy_pool</CODE> also
+<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>
@@ -672,8 +672,8 @@
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>sub_req_lookup_...</CODE> functions)
-is <CODE>destroy_sub_request</CODE>, which frees the resource pool.
+have allocated (using the <CODE>ap_sub_req_lookup_...</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
@@ -684,7 +684,7 @@
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>destroy...</CODE> functions).
+<CODE>ap_destroy...</CODE> functions).

<H2><A name="config">Configuration, commands and the like</A></H2>

@@ -809,11 +809,11 @@
mime_dir_config *parent_dir = (mime_dir_config *)parent_dirv;
mime_dir_config *subdir = (mime_dir_config *)subdirv;
mime_dir_config *new =
- (mime_dir_config *)palloc (p, sizeof(mime_dir_config));
+ (mime_dir_config *)ap_palloc (p, sizeof(mime_dir_config));

- new-&gt;forced_types = overlay_tables (p, subdir-&gt;forced_types,
+ new-&gt;forced_types = ap_overlay_tables (p, subdir-&gt;forced_types,
parent_dir-&gt;forced_types);
- new-&gt;encoding_types = overlay_tables (p, subdir-&gt;encoding_types,
+ new-&gt;encoding_types = ap_overlay_tables (p, subdir-&gt;encoding_types,
parent_dir-&gt;encoding_types);

return new;