Return-Path: Delivered-To: apache-cvs-archive@hyperreal.org Received: (qmail 4201 invoked by uid 6000); 15 Apr 1998 08:50:40 -0000 Received: (qmail 4195 invoked by alias); 15 Apr 1998 08:50:38 -0000 Delivered-To: apache-1.3-cvs@hyperreal.org Received: (qmail 4193 invoked by uid 177); 15 Apr 1998 08:50:38 -0000 Date: 15 Apr 1998 08:50:38 -0000 Message-ID: <19980415085038.4192.qmail@hyperreal.org> From: martin@hyperreal.org To: apache-1.3-cvs@hyperreal.org Subject: cvs commit: apache-1.3/htdocs/manual/misc API.html Sender: apache-cvs-owner@apache.org Precedence: bulk Reply-To: new-httpd@apache.org 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 -table_get and table_set routines.

+ap_table_get and ap_table_set routines.

Note that the Content-type header value cannot be - set by module content-handlers using the table_*() + set by module content-handlers using the ap_table_*() routines. Rather, it is set by pointing the content_type field in the request_rec structure to an appropriate string. E.g., @@ -397,7 +397,7 @@ response handlers have to actually send a request back to the client.

They should begin by sending an HTTP response header, using the -function send_http_header. (You don't have to do +function ap_send_http_header. (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 header_only, that's all they should @@ -414,11 +414,11 @@ of code, which is the handler which handles GET requests which have no more specific handler; it also shows how conditional GETs can be handled, if it's desirable to do so in a -particular response handler --- set_last_modified checks +particular response handler --- ap_set_last_modified checks against the If-modified-since 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 -set_content_length, but it returns an error code for +ap_set_content_length, but it returns an error code for symmetry.

  @@ -430,8 +430,8 @@
       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 @@
       }
   
       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;
   }
@@ -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 -internal_redirect, which is how the internal redirection +ap_internal_redirect, which is how the internal redirection machinery discussed above is invoked. A response handler which has internally redirected should always return OK.

-(Invoking internal_redirect from handlers which are +(Invoking ap_internal_redirect from handlers which are not response handlers will lead to serious confusion).

Special considerations for authentication handlers

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

    We begin here by describing how memory is allocated to pools, and then @@ -547,7 +547,7 @@

    Allocation of memory in pools

    Memory is allocated to pools by calling the function -palloc, which takes two arguments, one being a pointer to +ap_palloc, which takes two arguments, one being a pointer to a resource pool structure, and the other being the amount of memory to allocate (in chars). 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->pool, sizeof(my_structure)); + foo = (foo *)ap_palloc (r->pool, sizeof(my_structure)); } -Note that there is no pfree --- -palloced memory is freed only when the associated -resource pool is cleared. This means that palloc does not +Note that there is no ap_pfree --- +ap_palloced memory is freed only when the associated +resource pool is cleared. This means that ap_palloc does not have to do as much accounting as malloc(); all it does in the typical case is to round up the size, bump a pointer, and do a range check.

    -(It also raises the possibility that heavy use of palloc +(It also raises the possibility that heavy use of ap_palloc 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 malloc, and try to be sure that all of the memory @@ -586,19 +586,19 @@

    Allocating initialized memory

    There are functions which allocate initialized memory, and are -frequently useful. The function pcalloc has the same -interface as palloc, but clears out the memory it -allocates before it returns it. The function pstrdup +frequently useful. The function ap_pcalloc has the same +interface as ap_palloc, but clears out the memory it +allocates before it returns it. The function ap_pstrdup takes a resource pool and a char * as arguments, and allocates memory for a copy of the string the pointer points to, -returning a pointer to the copy. Finally pstrcat is a +returning a pointer to the copy. Finally ap_pstrcat is a varargs-style function, which takes a pointer to a resource pool, and at least two char * arguments, the last of which must be NULL. It allocates enough memory to fit copies of each of the strings, as a unit; for instance: 
      -     pstrcat (r->pool, "foo", "/", "bar", NULL);
  +     ap_pstrcat (r->pool, "foo", "/", "bar", NULL);
    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 pfopen, which +routine which is typically used for this is ap_pfopen, which takes a resource pool and two strings as arguments; the strings are the same as the typical arguments to fopen, e.g., 
            ...
  -     FILE *f = pfopen (r->pool, r->filename, "r");
  +     FILE *f = ap_pfopen (r->pool, r->filename, "r");
   
        if (f == NULL) { ... } else { ... }
    -There is also a popenf routine, which parallels the +There is also a ap_popenf routine, which parallels the lower-level open system call. Both of these routines arrange for the file to be closed when the resource pool in question is cleared.

    Unlike the case for memory, there are functions to close -files allocated with pfopen, and popenf, -namely pfclose and pclosef. (This is +files allocated with ap_pfopen, and ap_popenf, +namely ap_pfclose and ap_pclosef. (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 pfopen and -popenf, since to do otherwise could cause fatal errors on +functions to close files allocated with ap_pfopen and +ap_popenf, since to do otherwise could cause fatal errors on systems such as Linux, which react badly if the same FILE* is closed more than once.

    @@ -646,7 +646,7 @@

    Fine control --- creating and dealing with sub-pools, with a note on sub-requests

    -On rare occasions, too-free use of palloc() and the +On rare occasions, too-free use of ap_palloc() and the associated primitives may result in undesirably profligate resource allocation. You can deal with such a case by creating a sub-pool, 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).

    -The primitive for creating a sub-pool is make_sub_pool, +The primitive for creating a sub-pool is ap_make_sub_pool, 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 -clear_pool and destroy_pool, respectively. -(The difference is that clear_pool frees resources -associated with the pool, while destroy_pool also +ap_clear_pool and ap_destroy_pool, respectively. +(The difference is that ap_clear_pool frees resources +associated with the pool, while ap_destroy_pool 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).

    @@ -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 sub_req_lookup_... functions) -is destroy_sub_request, which frees the resource pool. +have allocated (using the ap_sub_req_lookup_... functions) +is ap_destroy_sub_req, 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 -destroy... functions). +ap_destroy... functions).

    Configuration, commands and the like

    @@ -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->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;