diff options
author | Martin Kraemer <martin@apache.org> | 1998-04-15 10:50:37 +0200 |
---|---|---|
committer | Martin Kraemer <martin@apache.org> | 1998-04-15 10:50:37 +0200 |
commit | dd10c03f0371795550d89cc2dd92b5cd33f1d470 (patch) | |
tree | 44794985d711736a16dfde8069b4afde2b839a76 /docs/manual/misc/API.html | |
parent | Document renamed functions instead of old names (diff) | |
download | apache2-dd10c03f0371795550d89cc2dd92b5cd33f1d470.tar.xz apache2-dd10c03f0371795550d89cc2dd92b5cd33f1d470.zip |
Oops: csubst missed a couple of old names.
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@80920 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to '')
-rw-r--r-- | docs/manual/misc/API.html | 90 |
1 files changed, 45 insertions, 45 deletions
diff --git a/docs/manual/misc/API.html b/docs/manual/misc/API.html index 12a6dffc2e..33ec861dad 100644 --- a/docs/manual/misc/API.html +++ b/docs/manual/misc/API.html @@ -240,10 +240,10 @@ the client's original request, MIME headers to be sent back with the response (which modules can add to at will), and environment variables for any subprocesses which are spawned off in the course of servicing the request. These tables are manipulated using the -<CODE>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 @@ checkers, simply by returning the correct error code). However, 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 @@ At this point, you should more or less understand the following piece of code, which is the handler which handles <CODE>GET</CODE> requests which have no more specific handler; it also shows how conditional <CODE>GET</CODE>s can be handled, if it's desirable to do so in a -particular response handler --- <CODE>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 @@ int default_handler (request_rec *r) if (r->method_number != M_GET) return DECLINED; if (r->finfo.st_mode == 0) return NOT_FOUND; - if ((errstatus = set_content_length (r, r->finfo.st_size)) - || (errstatus = set_last_modified (r, r->finfo.st_mtime))) + if ((errstatus = ap_set_content_length (r, r->finfo.st_size)) + || (errstatus = ap_set_last_modified (r, r->finfo.st_mtime))) return errstatus; f = fopen (r->filename, "r"); @@ -443,10 +443,10 @@ int default_handler (request_rec *r) } register_timeout ("send", r); - send_http_header (r); + ap_send_http_header (r); if (!r->header_only) send_fd (f, r); - pfclose (r->pool, f); + ap_pfclose (r->pool, f); return OK; } </PRE> @@ -456,11 +456,11 @@ ways out of it. First off, as shown above, a response handler which has not yet produced any output can simply return an error code, in which case the server will automatically produce an error response. Secondly, it can punt to some other handler by invoking -<CODE>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 @@ Stuff that should be discussed here in detail: <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->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 @@ in case you are using the timeout machinery (which isn't yet even documented here). However, there are two benefits to using it: resources allocated to a pool never leak (even if you allocate a scratch string, and just forget about it); also, for memory -allocation, <CODE>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 @@ machinery. <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 @@ int my_handler(request_rec *r) struct my_structure *foo; ... - foo = (foo *)palloc (r->pool, sizeof(my_structure)); + foo = (foo *)ap_palloc (r->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 @@ thousands of files). <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->pool, "foo", "/", "bar", NULL); + ap_pstrcat (r->pool, "foo", "/", "bar", NULL); </PRE> returns a pointer to 8 bytes worth of memory, initialized to @@ -608,29 +608,29 @@ returns a pointer to 8 bytes worth of memory, initialized to 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->pool, r->filename, "r"); + FILE *f = ap_pfopen (r->pool, r->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 @@ which the file stuff is implemented; also, <CODE>spawn_process</CODE>. <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 @@ module set is in case of listing directories, and then only with 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 @@ latter case, it is simply gone). <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>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 @@ 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>destroy...</CODE> functions). +<CODE>ap_destroy...</CODE> functions). <H2><A name="config">Configuration, commands and the like</A></H2> @@ -809,11 +809,11 @@ void *merge_mime_dir_configs (pool *p, void *parent_dirv, void *subdirv) 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->forced_types = overlay_tables (p, subdir->forced_types, + new->forced_types = ap_overlay_tables (p, subdir->forced_types, parent_dir->forced_types); - new->encoding_types = overlay_tables (p, subdir->encoding_types, + new->encoding_types = ap_overlay_tables (p, subdir->encoding_types, parent_dir->encoding_types); return new; |