CONTENTS

Appendix A. The Apache 1.x API

•  A.1 Pools
•  A.2 Per-Server Configuration
•  A.3 Per-Directory Configuration
•  A.4 Per-Request Information
•  A.5 Access to Configuration and Request Information
•  A.6 Functions

Apache 1.x provides an Application Programming Interface (API) to modules to insulate them from the mechanics of the HTTP protocol and from each other. In this appendix, we explore the main concepts of the API and provide a detailed listing of the functions available to the module author targeting Apache 1.x.

A.1 Pools

The most important thing to understand about the Apache API is the idea of a pool. This is a grouped collection of resources (i.e., file handles, memory, child programs, sockets, pipes, and so on) that are released when the pool is destroyed. Almost all resources used within Apache reside in pools, and their use should only be avoided with careful thought.

An interesting feature of pool resources is that many of them can be released only by destroying the pool. Pools may contain subpools, and subpools may contain subsubpools, and so on. When a pool is destroyed, all its subpools are destroyed with it.

Naturally enough, Apache creates a pool at startup, from which all other pools are derived. Configuration information is held in this pool (so it is destroyed and created anew when the server is restarted with a kill). The next level of pool is created for each connection Apache receives and is destroyed at the end of the connection. Since a connection can span several requests, a new pool is created (and destroyed) for each request. In the process of handling a request, various modules create their own pools, and some also create subrequests, which are pushed through the API machinery as if they were real requests. Each of these pools can be accessed through the corresponding structures (i.e., the connect structure, the request structure, and so on).

With this in mind, we can more clearly state when you should not use a pool: when the lifetime of the resource in question does not match the lifetime of a pool. If you need temporary storage (or files, etc.), you can create a subpool of a convenient pool (the request pool is the most likely candidate) and destroy it when you are done, so having a lifetime that is shorter than the pool's is not normally a good enough excuse. The only example we can think of where there is no appropriate pool is the code for handling listeners (copy_listeners( ) and close_unused_listeners( ) in http_main.c), which have a lifetime longer than the topmost pool!

There are a number of advantages to this approach, the most obvious being that modules can use resources without having to worry about when and how to release them. This is particularly useful when Apache handles an error condition. It simply bails out, destroying the pool associated with the erroneous request, confident that everything will be neatly cleaned up. Since each instance of Apache may handle many requests, this functionality is vital to the reliability of the server. Unsurprisingly, pools come into almost every aspect of Apache's API, as we shall see in this chapter. They are defined in alloc.h :

typedef struct pool pool;

The actual definition of struct pool can be found in alloc.c, but no module should ever need to use it. All modules ever see of a pool is a pointer to it, which they then hand on to the pool APIs.

Like many other aspects of Apache, pools are configurable, in the sense that you can add your own resource management to a pool, mainly by registering cleanup functions (see the pool API later in this chapter).

A.2 Per-Server Configuration

Since a single instance of Apache may be called on to handle a request for any of the configured virtual hosts (or the main host), a structure is defined that holds the information related to each host. This structure, server_rec, is defined in httpd.h:

struct server_rec {
    server_rec *next;

    /* Description of where the definition came from */
    const char *defn_name;
    unsigned defn_line_number;

    /* Full locations of server config info */

    char *srm_confname;
    char *access_confname;

    /* Contact information */

    char *server_admin;
    char *server_hostname;
    unsigned short port;        /* For redirects, etc. */

    /* Log files --- note that transfer log is now in the modules... */

    char *error_fname;
    FILE *error_log;
    int loglevel;

    /* Module-specific configuration for server, and defaults... */
    int is_virtual;             /* True if this is the virtual server */
    void *module_config;        /* Config vector containing pointers to
                                 * modules' per-server config structures.
                                 */
    void *lookup_defaults;      /* MIME type info, etc., before we start
                                 * checking per-directory info.
                                 */
    /* Transaction handling */
    server_addr_rec *addrs;
    int timeout;                /* Timeout, in seconds, before we give up */
    int keep_alive_timeout;     /* Seconds we'll wait for another request */
    int keep_alive_max;         /* Maximum requests per connection */
    int keep_alive;             /* Maximum requests per connection */
    int send_buffer_size;       /* Size of TCP send buffer (in bytes) */

    char *path;                 /* Pathname for ServerPath */
    int pathlen;                /* Length of path */
    char *names;                /* Normal names for ServerAlias servers */
    array_header *wild_names;   /* Wildcarded names for ServerAlias servers
                                 */

    uid_t server_uid;    /* Effective user ID when calling exec wrapper */
    gid_t server_gid;    /* Effective group ID when calling exec wrapper */
};

Most of this structure is used by the Apache core, but each module can also have a per-server configuration, which is accessed via the module_config member, using ap_get_module_config( ). Each module creates this per-module configuration structure itself, so it has complete control over its size and contents.

A.3 Per-Directory Configuration

It is also possible for modules to be configured on a per-directory, per-URL, or per-file basis. Again, each module optionally creates its own per-directory configuration (the same structure is used for all three cases). This configuration is made available to modules either directly (during configuration) or indirectly (once the server is running, through the request_rec structure, detailed in the next section).

A.4 Per-Request Information

The core ensures that the right information is available to the modules at the right time by matching requests to the appropriate virtual server and directory information before invoking the various functions in the modules. This, and other information, is packaged in a request_rec structure, defined in httpd.h:

struct request_rec {
  ap_pool *pool;
  conn_rec *connection;
  server_rec *server;

  request_rec *next;          /* If we wind up getting redirected,
                               * pointer to the request we redirected to.
                               */
  request_rec *prev;          /* If this is an internal redirect,
                               * pointer to where we redirected *from*.
                               */
  
  request_rec *main;          /* If this is a subrequest (see request.h), 
                               * pointer back to the main request.
                               */
  /* Info about the request itself... we begin with stuff that only
   * protocol.c should ever touch...
   */
  
  char *the_request;          /* First line of request, so we can log it */
  int assbackwards;           /* HTTP/0.9, "simple" request */
  int proxyreq;               /* A proxy request (calculated during
                               * post_read_request or translate_name) */
  int header_only;            /* HEAD request, as opposed to GET */
  char *protocol;             /* Protocol, as given to us, or HTTP/0.9 */
  int proto_num;              /* Number version of protocol; 1.1 = 1001 */
  const char *hostname;       /* Host, as set by full URI or Host: */

  time_t request_time;        /* When the request started */

  char *status_line;          /* Status line, if set by script */
  int status;                 /* In any case */
  
 /* Request method, two ways; also, protocol, etc. Outside of protocol.c,
  * look, but don't touch.
  */
  
  char *method;              /* GET, HEAD, POST, etc. */
  int method_number;         /* M_GET, M_POST, etc. */

  /*
    allowed is a bitvector of the allowed methods.
    A handler must ensure that the request method is one that
    it is capable of handling. Generally modules should DECLINE
    any request methods they do not handle. Prior to aborting the
    handler like this, the handler should set r->allowed to the list
    of methods that it is willing to handle. This bitvector is used
    to construct the "Allow:" header required for OPTIONS requests,
    and METHOD_NOT_ALLOWED and NOT_IMPLEMENTED status codes.
    Since the default_handler deals with OPTIONS, all modules can
    usually decline to deal with OPTIONS. TRACE is always allowed;
    modules don't need to set it explicitly.
    Since the default_handler will always handle a GET, a
    module which does *not* implement GET should probably return
    METHOD_NOT_ALLOWED. Unfortunately, this means that a Script GET
    handler can't be installed by mod_actions.
  */
  int allowed;                /* Allowed methods - for 405, OPTIONS, etc. */

  int sent_bodyct;            /* Byte count in stream is for body */
  long bytes_sent;            /* Body byte count, for easy access */
  time_t mtime;               /* Time the resource was last modified */

  /* HTTP/1.1 connection-level features */

  int chunked;                /* Sending chunked transfer-coding */
  int byterange;              /* Number of byte ranges */
  char *boundary;             /* Multipart/byteranges boundary */
  const char *range;          /* The Range: header */
  long clength;               /* The "real" content length */

  long remaining;             /* Bytes left to read */
  long read_length;           /* Bytes that have been read */
  int read_body;              /* How the request body should be read */
  int read_chunked;           /* Reading chunked transfer-coding */

 /* MIME header environments, in and out. Also, an array containing
  * environment variables to be passed to subprocesses, so people can
  * write modules to add to that environment.
  *
  * The difference between headers_out and err_headers_out is that the
  * latter are printed even on error and persist across internal redirects
  * (so the headers printed for ErrorDocument handlers will have them).
  *
  * The 'notes' table is for notes from one module to another, with no
  * other set purpose in mind...
  */
  
  table *headers_in;
  table *headers_out;
  table *err_headers_out;
  table *subprocess_env;
  table *notes;

  /* content_type, handler, content_encoding, content_language, and all
   * content_languages MUST be lowercased strings. They may be pointers
   * to static strings; they should not be modified in place.
   */
  char *content_type;         /* Break these out --- we dispatch on 'em */
  char *handler;              /* What we *really* dispatch on           */

  char *content_encoding;
  char *content_language;
  array_header *content_languages;	/* Array of (char*) */

  int no_cache;
  int no_local_copy;

  /* What object is being requested (either directly, or via include
   * or content-negotiation mapping).
   */
  char *unparsed_uri;         /* The URI without any parsing performed */
  char *uri;                  /* The path portion of the URI */
  char *filename;
  char *path_info;
  char *args;                 /* QUERY_ARGS, if any */
  struct stat finfo;          /* ST_MODE set to zero if no such file */
  uri_components parsed_uri;  /* Components of URI, dismantled */
  
  /* Various other config info, which may change with .htaccess files.
   * These are config vectors, with one void* pointer for each module
   * (the thing pointed to being the module's business).
   */
  
  void *per_dir_config;       /* Options set in config files, etc. */
  void *request_config;       /* Notes on *this* request */
/*
 * A linked list of the configuration directives in the .htaccess files
 * accessed by this request.
 * N.B. Always add to the head of the list, _never_ to the end.
 * That way, a subrequest's list can (temporarily) point to a parent's
 * list.
 */
  const struct htaccess_result *htaccess;
};

A.5 Access to Configuration and Request Information

All this sounds horribly complicated, and, to be honest, it is. But unless you plan to mess around with the guts of Apache (which this book does not encourage you to do), all you really need to know is that these structures exist and that your module can get access to them at the appropriate moments. Each function exported by a module gets access to the appropriate structure to enable it to function. The appropriate structure depends on the function, of course, but it is always either a server_rec, the module's per-directory configuration structure (or two), or a request_rec. As we saw earlier, if you have a server_rec, you can get access to your per-server configuration, and if you have a request_rec, you can get access to both your per-server and your per-directory configurations.

A.6 Functions

Now that we have covered the main structures used by modules, we can detail the functions available to use and manipulate those structures.

A.6.1 Pool Functions

pool *ap_make_sub_pool(pool *p)

Creates a subpool within a pool. The subpool is destroyed automatically when the pool p is destroyed, but can also be destroyed earlier with destroy_pool or cleared with clear_pool. Returns the new pool.

void ap_clear_pool(pool *p)

Clears a pool, destroying all its subpools with destroy_pool and running cleanups. This leaves the pool itself empty but intact, and therefore available for reuse.

void ap_destroy_pool(pool *p)

Destroys a pool, running cleanup methods for the contents and also destroying all subpools. The subpools are destroyed before the pool's cleanups are run.

long ap_bytes_in_pool(pool *p)

Returns the number of bytes currently allocated to a pool.

long ap_bytes_in_free_blocks(void)

Returns the number of bytes currently in free blocks for all pools.

void *ap_palloc(pool *p, int size)

Allocates memory of at least size bytes. The memory is destroyed when the pool is destroyed. Returns a pointer to the new block of memory.

void *ap_pcalloc(pool *p, int size)

Allocates memory of at least size bytes. The memory is initialized to zero. The memory is destroyed when the pool is destroyed. Returns a pointer to the new block of memory.

char *ap_pstrdup(pool *p,const char *s)

Duplicates a string within a pool. The memory is destroyed when the pool is destroyed. If s is NULL, the return value is NULL; otherwise, it is a pointer to the new copy of the string.

char *ap_pstrndup(pool *p, const char *s, int n)

Allocates n+1 bytes of memory and copies up to n characters from s, NULL- terminating the result. The memory is destroyed when the pool is destroyed. Returns a pointer to the new block of memory, or NULL if s is NULL

char *ap_pstrcat(pool *p, ...)

Concatenates the NULL-terminated list of strings together in a new block of memory. The memory is destroyed when the pool is destroyed. Returns a pointer to the new block of memory. For example:

pstrcat(p,"Hello,","world!",NULL);

returns a block of memory containing Hello, world!

A.6.2 Array Functions

array_header *ap_make_array(pool *p, int nelts, int elt_size)

Allocates memory to contain nelts elements of size elt_size. The array can grow to contain as many elements as needed. The array is destroyed when the pool is destroyed. Returns a pointer to the new array.

void *ap_push_array(array_header *arr)

Returns a pointer to the next element of the array arr, allocating more memory to accommodate it if necessary.

void ap_array_cat(array_header *dst, const array_header *src)

Appends the array src to the array dst. The dst array is allocated more memory if necessary to accommodate the extra elements. Although this operation only makes sense if the two arrays have the same element size, there is no check for this.

array_header *ap_copy_array(pool *p, const array_header *arr)

Creates a new copy of the array arr in the pool p. The new array is destroyed when the pool is destroyed. Returns a pointer to the new array.

array_header *ap_copy_array_hdr(pool *p, const array_header *arr)

Copies the array arr into the pool p without immediately copying the array's storage. If the array is extended with push_array, the original array is copied to the new array before the extension takes place. Returns a pointer to the new array.

There are at least two pitfalls with this function. First, if the array is not extended, its memory is destroyed when the original array is destroyed; second, any changes made to the original array may also affect the new array if they occur before the new array is extended.

array_header *ap_append_arrays(pool *p, const array_header *first, 
const array_header *second)

Creates a new array consisting of the elements of second appended to the elements of first. If second is empty, the new array shares memory with first until a new element is appended. (This is a consequence of using ap_copy_array_hdr( ) to create the new array; see the warning in that function.) Returns a pointer to the new array.

A.6.3 Table Functions

A table is an association between two strings known as the key and the value, accessible by the key.

table *ap_make_table(pool *p, int nelts)

Creates a new table with sufficient initial storage for nelts elements. Returns a pointer to the table.

table *ap_copy_table(pool *p, const table *t)

Returns a pointer to a copy of the table.

array_header *ap_table_elts(table *t)

Returns the array upon which the table is based.

int ap_is_empty_table(table *t)

Returns nonzero if the table is empty.

void ap_table_set(table *t, const char *key, const char *value)

If key already has an associated value in t, it is replaced with a copy of value; otherwise, a new entry is created in the table. Note that the key and value are duplicated with ap_pstrdup( ).

void ap_table_setn(table *t, const char *key, const char *value)

This is similar to ap_table_set( ), except that the key and value are not duplicated. This is normally used to copy a value from a pool to a subpool.

void ap_table_merge(table *t, const char *key, const char *value)

If an entry already exists for key in the table, value is appended to the existing value, separated by a comma and a space. Otherwise, a new entry is created, as in table_set. Note that if multiple instances of key exist in the table, only the first is affected.

pool *p;			/* Assumed to be set elsewhere */
table *t;
char *v;

t=make_table(1);
table_set(t,"somekey","Hello");
table_merge(t,"somekey","world!");
v=table_get(t,"somekey");	/* v now contains "Hello, world!" */

void ap_table_mergen(table *t, const char *key, const char *value)

This is similar to ap_table_merge( ), except that if a new key/value pair is created, it is not duplicated. This is normally used to merge a value from a pool into a subpool.

void ap_table_add(table *t, const char *key, const char *value)

Adds a new entry to the table, associating key with value. Note that a new entry is created regardless of whether the key already exists in the table. The key and value stored are duplicated using ap_pstrdup( ).

void ap_table_addn(table *t, const char *key, const char *value)

Adds a new entry to the table, associating key with value. Note that a new entry is created regardless of whether the key already exists in the table. The key and value stored are not duplicated, so care must be taken to ensure they are not changed. This function is normally used to copy a table element from a pool into a subpool.

void ap_table_unset(table *t, const char *key)

Removes the entry in the table corresponding to key. It is not an error to remove an entry that does not exist.

const char *ap_table_ get(const table *t, const char *key)

Returns the value corresponding to key in the table t. Note that you may not modify the returned value.

void ap_table_do(int (*comp) (void *, const char *, const char *), void *rec, 
const table *t,...)

If the NULL-terminated vararg list is empty, traverses the whole table and runs the function comp(rec,key,value) on each key/value pair. If the vararg list is nonempty, traverses the matching keys (strcasecmp( ) is used to determine a match) and runs the same function. Each traversal is terminated if the function comp returns the value 0.

In either case it may happen that the comp( ) function is called multiple times for the same key. The table may again contain various entries of the same key; if the vararg list is nonempty, the traversal is repeated for any vararg item, even if they are equal.

table *ap_overlay_tables(pool *p, const table *overlay, const table *base)

Creates a new table consisting of the two tables overlay and base concatenated — overlay first. No attempt is made to merge or override existing keys in either table, but since overlay comes first, any retrieval done with table_get on the new table gets the entry from overlay if it exists. Returns a pointer to the new table.

API_EXPORT(void) ap_clear_table(table *t)

Clears the table. None of the elements are destroyed (since the pool mechanism doesn't permit it, anyway), but they become unavailable.

A.6.4 Cleanup Functions

An important part of the pool is the cleanup functions that are run when the pool is destroyed. These functions deal with those cleanup functions.

void ap_register_cleanup(pool *p, void *data, void (*plain_cleanup)(void *), 
void (*child_cleanup)(void *))

Registers a pair of functions to be called when the pool is destroyed. Pools can be destroyed for two reasons: first, because the server has finished with that pool, in which case it destroys it and calls the plain_cleanup function, or second, because the server has forked and is preparing to exec some other program, in which case the child_cleanup function is called. In either case, data is passed as the only argument to the cleanup function. If either of these cleanups is not required, use ap_null_cleanup.

void ap_kill_cleanup(pool *p, void *data, void (*plain_cleanup)(void *))

Removes the previously registered cleanup function from the pool. The cleanup function is identified by the plain_cleanup function and the data pointer previously registered with register_cleanup. Note that the data pointer must point to the same memory as was used in register_cleanup.

void ap_cleanup_for_exec(void)

Destroys all pools using the child_cleanup methods. Needless to say, this should only be done after forking and before running a (nonserver) child. Calling this in a running server certainly stops it from working! Note that on Win32 this actually does nothing on the slightly dubious grounds that we aren't forked. Unfortunately, there isn't really much alternative.

void ap_note_cleanups_for_fd(pool *p, int fd)

Registers a cleanup function that will close the file descriptor when the pool is destroyed. Normally one of the file-opening functions does this for you, but it is occasionally necessary to do it "by hand." Note that sockets have their own cleanup functions.

void ap_kill_cleanups_for_fd(pool *p, int fd)

Kills cleanups for a file descriptor registered using popenf( ), pfopen( ), pfdopen( ), or note_cleanups_for_fd( ). Normally this is taken care of when the file is closed, but occasionally it is necessary to call it directly.

void ap_note_cleanups_for_socket(pool *p, int fd)

Registers a cleanup function that will close the socket when the pool is destroyed. This is distinct from ap_note_cleanups_for_fd( ) because sockets and file descriptors are not equivalent on Win32.

void ap_kill_cleanups_for_socket(pool *p, int sock)

Removes the cleanup function for the socket sock. This is normally done for you when the socket is closed by ap_pclosesocket( ), but it may occasionally be necessary to call it directly.

void ap_note_cleanups_for_file(pool *p, FILE *f)

Registers a cleanup function to close the stream when the pool is destroyed. Strangely, there isn't an ap_kill_cleanups_for_file( ).

void ap_run_cleanup(pool *p, void *data, void (*cleanup)(void *))

Runs a cleanup function, passing data to it, with alarms blocked. It isn't usually necessary to call this, since cleanups are run automatically, but it can be used for any custom cleanup code. The cleanup function is removed from p.

A.6.5 File and Socket Functions

These functions are used to open and close files and sockets with automatic cleanup registration and killing.

int ap_popenf(pool *p, const char *name, int flg, int mode)

The equivalent to the standard C-function open( ), except that it ensures that the file is closed when the pool is destroyed. Returns the file descriptor for the opened file or -1 on error.

int ap_pclosef(pool *p, int fd)

Closes a file previously opened with ap_popenf( ). The return value is whatever close( ) returns. The file's cleanup function is destroyed.

FILE *ap_pfopen(pool *p, const char *name, const char *mode)

Equivalent to fopen( ), except that it ensures that the stream is closed when the pool is destroyed. Returns a pointer to the new stream or NULL on error.

FILE *ap_pfdopen(pool *p, int fd, const char *mode)

Equivalent to fdopen( ), except that it ensures the stream is closed when the pool is destroyed. Returns a pointer to the new stream or NULL on error.

int ap_pfclose(pool *p, FILE *fd)

Closes the stream with fclose( ), removing its cleanup function from the pool. Returns whatever fclose( ) returns.

int ap_psocket(pool *p, int domain, int type, int protocol)

Opens a socket, using socket( ), registering a cleanup function to close the socket when the pool is destroyed.

int ap_pclosesocket(pool *a, int sock)

Closes the socket, using closesocket( ), removing the cleanup function from the pool. Returns whatever closesocket( ) returns.

A.6.6 Regular Expression Functions

Note that only the functions that allocate memory are wrapped by Apache API functions.

regex_t *ap_pregcomp(pool *p, const char *pattern, int cflags)

Equivalent to regcomp( ), except that memory used is automatically freed when the pool is destroyed and that the regex_t * argument to regcomp( ) is created in the pool and returned, rather than being passed as a parameter.

char *ap_pregsub(pool *p, const char *input, const char *source, size_t nmatch,
regmatch_t pmatch[])

Substitutes for $0-$9 in input, using source as the source of the substitutions and pmatch to determine from where to substitute. nmatch, pmatch, and source should be the same as passed to regexec( ). Returns the substituted version of input in memory allocated from p.

void ap_pregfree(pool *p, regex_t * reg)

Frees the regular expression with regfree( ), removing its cleanup function from the pool.

int ap_os_is_path_absolute(const char *file)

Returns 1 if file is an absolute path, 0 otherwise.

A.6.7 Process and CGI Functions

void ap_note_subprocess(pool *p, int pid, enum kill_conditions how)

Registers a subprocess to be killed on pool destruction. Exactly how it is killed depends on how :

kill_never

Don't kill the process or wait for it. This is normally used internally.

kill_after_timeout

Send the process a SIGTERM, wait three seconds, send a SIGKILL, and wait for the process to die.

kill_always

Send the process a SIGKILL and wait for the process to die.

just_wait

Don't send the process any kind of kill.

kill_only_once

Send a SIGTERM, then wait.

Note that all three-second delays are carried out at once, rather than one after the other.

int ap_spawn_child(pool *p, void(*func)(void *,child_info *), void *data, enum kill_
conditions kill_how, FILE **pipe_in, FILE **pipe_out, FILE **pipe_err)

This function should not be used, as it is known to expose bugs in Microsoft's libraries on Win32. You should use ap_bspawn_child( ) instead. This function was called spawn_child_err in previous versions of Apache.

int ap_bspawn_child(pool *p, int (*func) (void *, child_info *), void *data, enum 
kill_conditions kill_how, BUFF **pipe_in, BUFF **pipe_out, BUFF **pipe_err)

Spawns a child process with pipes optionally connected to its standard input, output, and error. This function takes care of the details of forking (if the platform supports it) and setting up the pipes. func is called with data and a child_info structure as its arguments in the child process. The child_info structure carries information needed to spawn the child under Win32; it is normally passed straight on to ap_call_exec( ). If func( ) wants cleanup to occur, it calls cleanup_for_exec. func( ) will normally execute the child process with ap_call_exec( ). If any of pipe_in, pipe_out, or pipe_err are NULL, those pipes aren't created; otherwise, they are filled in with pointers to BUFFs that are connected to the subprocesses' standard input, output, and error, respectively. Note that on Win32, the pipes use Win32 native handles rather than C-file handles. This function only returns in the parent. Returns the PID of the child process or -1 on error. This function was called spawn_child_err_buff in previous versions of Apache.

int ap_call_exec(request_rec *r, child_info *pinfo, char *argv0, char **env, 
int shellcmd

Calls exec( ) (or an appropriate spawning function on nonforking platforms) or the setuid wrapper, depending on whether setuid wrappers are enabled. argv0 is the name of the program to run; env is a NULL-terminated array of strings to be used as the environment of the execed program. If shellcmd is nonzero, the command is run via a shell. If r->args is set and does not contain an equal sign, it is passed as a command-line argument. pinfo should be the structure passed by ap_bspawn_child( ). This function should not return on forking platforms. On nonforking platforms it returns the PID of the new process.

int ap_can_exec(const struct stat *finfo)

Given a struct stat (from stat( ), etc.), returns nonzero if the file described by finfo can be executed.

void ap_add_cgi_vars(request_rec *r

Adds the environment variables required by the CGI specification (apart from those added by ap_add_common_vars( )). Call this before actually exec( )ing a CGI. ap_add_common_vars( ) should also be called.

void ap_add_common_vars(request_rec *r)

Adds the environment variables common to all subprograms run as a result of a request. Usually, ap_add_cgi_vars( ) should be called as well. The only exception we are aware of is ISAPI programs.

int ap_scan_script_header_err(request_rec *r, FILE *f, char *buffer)

Read the headers arriving from a CGI on f, checking them for correctness. Most headers are simply stored in r->headers_out, which means they'll ultimately be sent to the client, but a few are dealt with specially:

Status

If this is set, it is used as the HTTP response code.

Location

If this is set, the result is a redirect to the URL specified.

If buffer is provided (it can be NULL), then — should the script send an illegal header — it will be left in buffer, which must be at least MAX_STRING_LEN bytes long. The return value is HTTP_OK, the status set by the script, or SERVER_ERROR if an error occurred.

int ap_scan_script_header_err_buff(request_rec *r, BUFF *fb, char *buffer)

This is similar to ap_scan_script_header_err( ), except that the CGI is connected with a BUFF * instead of a FILE *.

int ap_scan_script_header(request_rec *r, FILE *f)

This is similar to ap_scan_script_header_err( ), except that no error buffer is passed.

A.6.8 MD5 Functions

char *ap_md5(pool *p, unsigned char *string)

Calculates the MD5 hash of string, returning the ASCII hex representation of the hash (which is 33 bytes, including terminating NUL), allocated in the pool p.

char *ap_md5contextTo64(pool *a, AP_MD5_CTX * context)

Take the MD5 hash in context (which must not have had ap_MD5Final run) and make a base-64 representation of it in the pool a.

char *ap_md5digest(pool *p, FILE *infile)

Reads the file infile from its current position to the end, returning a base-64 MD5 digest allocated in the pool p. The file is rewound to the beginning after calculating the digest.

void ap_MD5Init(AP_MD5_CTX *context)

Initializes context in preparation for an MD5 digest.

void ap_MD5Final(unsigned char digest[16], AP_MD5_CTX *context)

Finishes the MD5 operation, writing the digest to digest and zeroing context.

void ap_MD5Update(AP_MD5_CTX * context, const unsigned char *input, unsigned int 
inputLen)

Processes inputLen bytes of input, adding them to the digest being calculated in context.

A.6.9 Synchronization and Thread Functions

These functions hide operating system-dependent functions. On platforms that do not use threads for Apache, these functions exist but do not do anything; they simulate success if called.

Note that of these functions, only the mutex functions are actually implemented. The rest are documented for completeness (and in case they get implemented).

A.6.9.1 Mutex functions

mutex *ap_create_mutex(char *name)

Creates a mutex object with the name name. Returns NULL if the operation fails.

mutex *ap_open_mutex(char *name)

Opens an existing mutex with the name name. Returns NULL if the operation fails.

int ap_acquire_mutex(mutex *mutex_id)

Locks the open mutex mutex_id. Blocks until the lock is available. Returns MULTI_OK or MULTI_ERR.

int ap_release_mutex(mutex *mutex_id)

Unlocks the open mutex mutex_id. Blocks until the lock is available. Returns MULTI_OK or MULTI_ERR.

void ap_destroy_mutex(mutex *mutex_id);

Destroys the mutex mutex_id.

A.6.9.2 Semaphore functions

semaphore *create_semaphore(int initial)

Creates a semaphore with an initial value of initial.

int acquire_semaphore(semaphore *semaphore_id)

Acquires the semaphore semaphore_id. Blocks until it is available. Returns MULTI_OK or MULTI_ERR.

int release_semaphore(semaphore *semaphore_id)

Releases the semaphore semaphore_id. Returns MULTI_OK or MULTI_ERR.

void destroy_semaphore(semaphore *semaphore_id)

Destroys the semaphore semaphore_id.

A.6.9.3 Event functions

event *create_event(int manual, int initial, char *name)

Creates an event named name with an initial state of initial. If manual is true, the event must be reset manually. If not, setting the event immediately resets it. Returns NULL on failure.

event *open_event(char *name)

Opens an existing event named name. Returns NULL on failure.

int acquire_event(event *event_id)

Waits for the event event_id to be signaled. Returns MULTI_OK or MULTI_ERR.

int set_event(event *event_id)

Signals the event event_id. Returns MULTI_OK or MULTI_ERR.

int reset_event(event *event_id)

Clears the event event_id. Returns MULTI_OK or MULTI_ERR.

void destroy_event(event *event_id)

Destroys the event event_id .

A.6.9.4 Thread functions

thread *create_thread(void (thread_fn) (void *thread_arg), void *thread_arg)

Creates a thread, calling thread_fn with the argument thread_arg in the newly created thread. Returns NULL on failure.

int kill_thread(thread *thread_id)

Kills the thread thread_id. Since this may leave a thread's resources in an unknown state, it should only be used with caution.

int await_thread(thread *thread_id, int sec_to_wait)

Waits for the thread thread_id to complete or for sec_to_wait seconds to pass, whichever comes first. Returns MULTI_OK, MULTI_TIMEOUT, or MULTI_ERR.

void exit_thread(int status)

Exits the current thread, returning status as the thread's status.

void free_thread(thread *thread_id)

Frees the resources associated with the thread thread_id. Should only be done after the thread has terminated.

A.6.10 Time and Date Functions

char *ap_ get_time(void)

Uses ctime to format the current time and removes the trailing newline. Returns a pointer to a string containing the time.

char *ap_ht_time(pool *p, time_t t, const char *fmt, int gmt)

Formats the time using strftime and returns a pool-allocated copy of it. If gmt is nonzero, the time is formatted as GMT; otherwise, it is formatted as local time. Returns a pointer to the string containing the time.

char *ap_ gm_timestr_822(pool *p, time_t t)

Formats the time as specified by RFC 822 (Standard for the Format of ARPA Internet Text Messages).^[1] The time is always formatted as GMT. Returns a pointer to the string containing the time.

struct tm *ap_ get_ gmtoff(long *tz)

Returns the current local time, and tz is filled in with the offset of the local time zone from GMT, in seconds.

time_t ap_tm2sec(const struct tm *t)

Returns the time in t as the time in seconds since 1 Jan 1970 00:00 GMT. t is assumed to be in GMT.

time_t ap_parseHTTPdate(const char *date)

Parses a date in one of three formats, returning the time in seconds since 1 Jan 1970 00:00 GMT. The three formats are as follows:

• Sun, 06 Nov 1994 08:49:37 GMT (RFC 822, updated by RFC 1123)

• Sunday, 06-Nov-94 08:49:37 GMT (RFC 850, made obsolete by RFC 1036)

• Sun Nov 6 08:49:37 1994 (ANSI C asctime( ) format)

Note that since HTTP requires dates to be in GMT, this routine ignores the time-zone field.

A.6.11 String Functions

int ap_strcmp_match(const char *str, const char *exp)

Matches str to exp, except that * and ? can be used in exp to mean "any number of characters" and "any character," respectively. You should probably use the newer and more powerful regular expressions for new code. Returns 1 for success, 0 for failure, and -1 for abort.

int ap_strcasecmp_match(const char *str, const char *exp)

Similar to strcmp_match, except matching is case blind.

int ap_is_matchexp(const char *exp)

Returns 1 if exp contains * or ?; 0 otherwise.

char *ap_ getword(pool *p, const char **line, char stop)
char *ap_ getword_nc(pool *p, char **line, char stop)

Looks for the first occurrence of stop in *line and copies everything before it to a new buffer, which it returns. If *line contains no stops, the whole of *line is copied. *line is updated to point after the occurrence of stop, skipping multiple instances of stop if present. ap_ getword_nc( ) is a version of ap_ getword( ) that takes a nonconstant pointer. This is because some C compilers complain if a char ** is passed to a function expecting a const char **.

char *ap_ getword_white(pool *p, const char **line)
char *ap_ getword_white_nc(pool *p, char **line)

Works like ap_ getword( ), except the words are separated by whitespace (as determined by isspace).

char *ap_ getword_nulls(pool *p, const char **line, char stop)
char *ap_ getword_nulls_nc(pool *p, char **line, char stop)

Works like ap_ getword( ), except that multiple occurrences of stop are not skipped, so null entries are correctly processed.

char *ap_ getword_conf(pool *p, const char **line)
char *ap_ getword_conf_nc(pool *p, char **line)

Works like ap_ getword( ), except that words can be separated by whitespace and can use quotes and backslashes to escape characters. The quotes and backslashes are stripped.

char *ap_ get_token(pool *p, const char **line, int accept_white)

Extracts a token from *line, skipping leading whitespace. The token is delimited by a comma or a semicolon. If accept_white is zero, it can also be delimited by whitespace. The token can also include delimiters if they are enclosed in double quotes, which are stripped in the result. Returns a pointer to the extracted token, which has been allocated in the pool p.

int ap_find_token(pool *p, const char *line, const char *tok)

Looks for tok in line. Returns nonzero if found. The token must exactly match (case blind) and is delimited by control characters (determined by iscntrl), tabs, spaces, or one of these characters:

( )<>@,;\\/[]?={}

This corresponds to the definition of a token in RFC 2068.

int ap_find_last_token(pool *p, const char *line, const char *tok)

Checks whether the end of line matches tok and whether tok is preceded by a space or a comma. Returns 1 if so, 0 otherwise.

char *ap_escape_shell_cmd(pool *p, const char *s)

Prefixes dangerous characters in s with a backslash, returning the new version. The current set of dangerous characters is as follows:

&;`'\"|*?~<>^( )[]{}$\\\n

Under OS/2, & is converted to a space.^[2]

char *ap_uudecode(pool *p, const char *coded)

Returns a decoded version of coded allocated in p.

char *ap_escape_html(pool *p, const char *s)

Escapes HTML so that the characters <, >, and & are displayed correctly. Returns a pointer to the escaped HTML.

int ap_checkmask(const char *data, const char *mask)

Checks whether data conforms to the mask in mask. mask is composed of the following characters:

@

An uppercase letter

$

A lowercase letter

&

A hexadecimal digit

#

A decimal digit

~

A decimal digit or a space

*

Any number of any character

Anything else

Itself

data is arbitrarily limited to 256 characters. It returns 1 for a match, 0 if not. For example, the following code checks for RFC 1123 date format:

if(ap_checkmask(date, "## @$$ #### ##:##:## *"))
    ...

void ap_str_tolower(char *str)

Converts str to lowercase, in place.

char *ap_psprintf(pool *p, const char *fmt, ...)

Much the same as the standard function sprintf( ) except that no buffer is supplied; instead, the new string is allocated in p. This makes this function completely immune from buffer overflow. Also see ap_vformatter( ).

char *ap_pvsprintf(pool *p, const char *fmt, va_list ap)

Similar to ap_psprintf( ), except that varargs are used.

int ap_ind(const char *s, char c)

Returns the offset of the first occurrence of c in s, or -1 if c is not in s.

int ap_rind(const char *s, char c)

Returns the offset of the last occurrence of c in s, or -1 if c is not in s.

A.6.12 Path, Filename, and URL Manipulation Functions

void ap_ getparents(char *name)

Removes ".." and "." segments from a path, as specified in RFC 1808 (Relative Uniform Resource Locators). This is important not only for security but also to allow correct matching of URLs. Note that Apache should never be presented with a path containing such things, but it should behave correctly when it is.

void ap_no2slash(char *name)

Removes double slashes from a path. This is important for correct matching of URLs.

char *ap_make_dirstr(pool *p, const char *path, int n)

Makes a copy of path guaranteed to end with a slash. It will truncate the path at the nth slash. Returns a pointer to the copy, which was allocated in the pool p.

char * ap_make_dirstr_parent(pool *p, const char *s)

Make a new string in p with the path of s's parent directory with a trailing slash.

char *ap_make_dirstr_prefix(char *d, const char *s, int n)

Copy the first n path elements from s to d or the whole of s if there are less than n path elements. Note that a leading slash counts as a path element.

int ap_count_dirs(const char *path)

Returns the number of slashes in a path.

void ap_chdir_file(const char *file)

Performs a chdir( ) to the directory containing file. This is done by finding the last slash in the file and changing to the directory preceding it. If there are no slashes in the file, it attempts a chdir to the whole of file. It does not check that the directory is valid, nor that the chdir succeeds.

int ap_unescape_url(char *url)

Converts escape sequences (%xx) in a URL back to the original character. The conversion is done in place. Returns 0 if successful, BAD_REQUEST if a bad escape sequence is found, and NOT_FOUND if %2f (which converts to "/" ) or %00 is found.

char *ap_construct_server(pool *p, const char *hostname, int port, request_rec *r)

Makes the server part of a URL by appending :<port> to hostname if port is not the default port for the scheme used to make the request.

char *ap_construct_url(pool *p, const char *uri, const request_rec *r)

Makes a URL by prefixing the scheme used by r to the server name and port extracted from r and by appending uri. Returns a pointer to the URL.

char *ap_escape_path_segment(pool *p, const char *segment)

Returns an escaped version of segment, as per RFC 1808.

char *ap_os_escape_path(pool *p, const char *path, int partial)

Returns an escaped version of path, per RFC 1808. If partial is nonzero, the path is assumed to be a trailing partial path (so that a "./" is not used to hide a ":").

int ap_is_directory(const char *path)

Returns nonzero if path is a directory.

char *ap_make_full_path(pool *p, const char *path1, const char *path2)

Appends path2 to path1, ensuring that there is only one slash between them. Returns a pointer to the new path.

int ap_is_url(const char *url)

Returns nonzero if url is a URL. A URL is defined, for this purpose, to be "<any string of numbers, letters, +, -, or . (dot)>:<anything>."

int ap_fnmatch(const char *pattern, const char *string, int flags)

Matches string against pattern, returning 0 for a match and FNM_NOMATCH otherwise. pattern consists of the following:

?

Match a single character.

*

Match any number of characters.

[...]

Represents a closure, as in regular expressions. A leading caret (^) inverts the closure.

\

If FNM_NOESCAPE is not set, removes any special meaning from next character.

flags is a combination of the following:

FNM_NOESCAPE

Treat a "\" as a normal character.

FNM_PATHNAME

*, ?, and [...] don't match "/.".

FNM_PERIOD

*, ?, and [...] don't match leading dots. "Leading" means either at the beginning of the string or after a "/" if FNM_PATHNAME is set.

int ap_is_fnmatch(const char *pattern)

Returns 1 if pattern contains ?, *, or [...]; 0 otherwise.

char *ap_server_root_relative(pool *p, char *file)

If file is not an absolute path, append it to the server root, in the pool p. If it is absolute, simply return it (not a copy).

char *ap_os_canonical_filename(pool *pPool, const char *szFile)

Returns a canonical form of a filename. This is needed because some operating systems will accept more than one string for the same file. Win32, for example, is case blind, ignores trailing dots and spaces, and so on.^[3] This function is generally used before checking a filename against a pattern or other similar operations.

A.6.13 User and Group Functions

uid_t ap_uname2id(const char *name)

If name starts with a "#," returns the number following it; otherwise, looks it up using getpwnam( ) and returns the UID. Under Win32, this function always returns 1.

gid_t ap_ gname2id(const char *name)

If name starts with a "#," returns the number following it; otherwise, looks it up using getgrnam( ) and returns the GID. Under Win32, this function always returns 1.

A.6.14 TCP/IP and I/O Functions

unsigned long ap_ get_virthost_addr(const char *hostname, short *ports)

Converts a hostname of the form name[:port] to an IP address in network order, which it returns. *ports is filled in with the port number if it is not NULL. If name is missing or "*", INADDR_ANY is returned. If port is missing or "*", *ports is set to 0.

If the host has multiple IP addresses, an error message is printed, and exit( ) is called.

char *ap_ get_local_host(pool *p)

Returns a pointer to the fully qualified domain name for the local host. If it fails, an error message is printed, and exit( ) is called.

const char *ap_ get_remote_host(conn_rec *conn, void *dir_config, int type)

Returns the hostname or IP address (as a string) of the client. dir_config is the per_dir_config member of the current request or NULL. type is one of the following:

REMOTE_HOST

Returns the hostname or NULL (if it either couldn't be found or hostname lookups are disabled with the HostnameLookups directive).

REMOTE_NAME

Returns the hostname or, if it can't be found, returns the IP address.

REMOTE_NOLOOKUP

Similar to REMOTE_NAME, except that a DNS lookup is not performed. (Note that the name can still be returned if a previous call did do a DNS lookup.)

REMOTE_DOUBLE_REV

Does a double-reverse lookup (that is, look up the hostname from the IP address, then look up the IP address from the name). If the double reverse works and the IP addresses match, return the name; otherwise, return a NULL.

long ap_send_fd(FILE *f, request_rec *r)

Copies the stream f to the client. Returns the number of bytes sent.

long ap_send_fd_length(FILE *f, request_rec *r, long length)

Copies no more than length bytes from f to the client. If length is less than 0, copies the whole file. Returns the number of bytes sent.

long ap_send_fb(BUFF *fb, request_rec *r)

Similar to ap_send_fd( ) except that it sends a BUFF * instead of a FILE *.

long ap_send_fb_length(BUFF *fb, request_rec *r, long length)

Similar to ap_send_fd_length( ), except that it sends a BUFF * instead of a FILE *.

size_t ap_send_mmap(void *mm, request_rec *r, size_t offset, size_t length)

Copies length bytes from mm+offset to the client. The data is copied MMAP_SEGMENT_SIZE bytes at a time, with the timeout reset in between each one. Although this can be used for any memory buffer, it is really intended for use with memory mapped files (which may give performance advantages over other means of sending files on some platforms).

int ap_rwrite(const void *buf, int nbyte, request_rec *r)

Writes nbyte bytes from buf to the client. Returns the number of bytes written or -1 on an error.

int ap_rputc(int c, request_rec *r)

Sends the character c to the client. Returns c or EOF if the connection has been closed.

int ap_rputs(const char *s, request_rec *r)

Sends the string s to the client. Returns the number of bytes sent or -1 if there is an error.

int ap_rvputs(request_rec *r, ...)

Sends the NULL-terminated list of strings to the client. Returns the number of bytes sent or -1 if there is an error.

int ap_rprintf(request_rec *r, const char *fmt,...)

Formats the extra arguments according to fmt (as they would be formatted by printf( )) and sends the resulting string to the client. Returns the number of bytes sent or -1 if there is an error.

int ap_rflush(request_rec *r)

Causes any buffered data to be sent to the client. Returns 0 on success or -1 on an error.

int ap_setup_client_block(request_rec *r, int read_policy)

Prepares to receive (or not receive, depending on read_policy) data from the client, typically because the client made a PUT or POST request. Checks that all is well to do the receive. Returns OK if all is well or a status code if not. Note that this routine still returns OK if the request does not include data from the client. This should be called before ap_should_client_block( ).

read_policy is one of the following:

REQUEST_NO_BODY

Return HTTP_REQUEST_ENTITY_TOO_LARGE if the request has any body.

REQUEST_CHUNKED_ERROR

If the Transfer-Encoding is chunked, return HTTP_BAD_REQUEST if there is a Content-Length header or HTTP_LENGTH_REQUIRED if not.^[4]

REQUEST_CHUNKED_DECHUNK

Handle chunked encoding in ap_ get_client_block( ), returning just the data.

REQUEST_CHUNKED_PASS

Handle chunked encoding in ap_ get_client_block( ), returning the data and the chunk headers.

int ap_should_client_block(request_rec *r)

Checks whether the client will send data and invites it to continue, if necessary (by sending a 100 Continue response if the client is HTTP 1.1 or higher). Returns 1 if the client should send data; 0 if not. ap_setup_client_block( ) should be called before this function, and this function should be called before ap_ get_client_block( ). This function should only be called once. It should also not be called until we are ready to receive data from the client.

long ap_ get_client_block(request_rec *r, char *buffer, int bufsiz)

Reads up to bufsiz characters into buffer from the client. Returns the number of bytes read, 0 if there is no more data, or -1 if an error occurs. ap_setup_client_block( ) and ap_should_client_block( ) should be called before this. Note that the buffer should be at least big enough to hold a chunk-size header line (because it may be used to store one temporarily). Since a chunk-size header line is simply a number in hex, 50 bytes should be plenty.

void ap_send_http_header(request_rec *r)

Sends the headers (mostly from r->headers_out) to the client. It is essential to call this in a request handler before sending the content.

void ap_send_size(size_t size, request_rec *r)

Sends size to the client, rounding it to the nearest thousand, million, or whatever. If size is -1, prints a minus sign only.

A.6.15 Request-Handling Functions

request_rec *ap_sub_req_lookup_uri(const char *new_uri, const request_rec *r)

Feeds new_uri into the system to produce a new request_rec, which has been processed to just before the point at which the request handler would be called. If the URI is relative, it is resolved relative to the URI of r. Returns the new request_rec. The status member of the new request_rec contains any error code.

request_rec *ap_sub_req_lookup_file(const char *new_file, const request_rec *r)

Similar to ap_sub_req_lookup_uri( ) except that it looks up a file, so it therefore doesn't call the name translators or match against <Location> sections.

int ap_run_sub_req(request_rec *r)

Runs a subrequest prepared with ap_sub_req_lookup_file( ) or ap_sub_req_lookup_uri( ). Returns the status code of the request handler.

void ap_destroy_sub_req(request_rec *r)

Destroys a subrequest created with ap_sub_req_lookup_file( ) or ap_sub_req_lookup_uri( ) and releases the memory associated with it. Needless to say, you should copy anything you want from a subrequest before destroying it.

void ap_internal_redirect(const char *uri, request_rec *r)

Internally redirects a request to uri. The request is processed immediately, rather than returning a redirect to the client.

void ap_internal_redirect_handler(const char *uri, request_rec *r)

Similar to ap_internal_redirect( ), but uses the handler specified by r.

A.6.16 Timeout and Alarm Functions

void ap_hard_timeout(char *name, request_rec *r)

Sets an alarm to go off when the server's configured timeout expires. When the alarm goes off, the current request is aborted by doing a longjmp( ) back to the top level and destroying all pools for the request r. The string name is logged to the error log.

void ap_keepalive_timeout(char *name, request_rec *r)

Works like ap_hard_timeout( ) except that if the request is kept alive, the keepalive timeout is used instead of the server timeout. This should normally be used only when awaiting a request from the client, and thus it is used only in http_protocol.c but is included here for completeness.

void ap_soft_timeout(char *name, request_rec *r)

Similar to ap_hard_timeout( ), except that the request that is destroyed is not set. The parameter r is not used (it is there for historical reasons).

void ap_reset_timeout(request_rec *r)

Resets the hard or soft timeout to what it originally was. The effect is as if you had called ap_hard_timeout( ) or ap_soft_timeout( ) again.

void ap_kill_timeout(request_rec *r)

Clears the current timeout on the request r.

void ap_block_alarms(void)

Temporarily blocks any pending timeouts. Protects critical sections of code that would leak resources (or would go wrong in some other way) if a timeout occurred during their execution. Calls to this function can be nested, but each call must be matched by a call to ap_unblock_alarms( ).

void ap_unblock_alarms(void)

Remove a block placed by ap_block_alarms( ).

int ap_check_alarm(void)

Since Win32 has no alarm( ) function, it is necessary to check alarms "by hand." This function does that, calling the alarm function set with one of the timeout functions. Returns -1 if the alarm has gone off, the number of seconds left before the alarm does go off, or 0 if no alarm is set.

A.6.17 Configuration Functions

configfile_t *ap_pcfg_openfile(pool *p, const char *name)

Opens name as a file (using fopen( )), returning NULL if the open fails or a pointer to a configuration if the open succeeds.

configfile_t *ap_pcfg_open_custom(pool *p, const char *descr, void *param,
int(*getch)(void *param), void *(*getstr) (void *buf, size_t bufsiz, void *param),
int(*close_func)(void *param))

Creates a custom configuration. The function getch( ) should read a character from the configuration, returning it or EOF if the configuration is finished. The function getstr( ) (if supplied — it can be NULL, in which case getch( ) will be used instead) should read a whole line into buf, terminating with NUL. It should return buf or NULL if the configuration is finished. close_func( ) (if supplied — it can be NULL) should close the configuration, returning 0 or more on success. All the functions are passed param when called.

int ap_cfg_ getc(configfile_t *cfp)

Reads a single character from cfp. If the character is LF, the line number is incremented. Returns the character or EOF if the configuration has completed.

int ap_cfg_ getline(char *s, int n, configfile_t *cfp)

Reads a line (up to n characters) from cfp into s, stripping leading and trailing whitespace and converting internal whitespace to single spaces. Continuation lines (indicated by a backslash immediately before the newline) are concatenated. Returns 0 normally; 1 if EOF has been reached.

int ap_cfg_closefile(configfile_t *cfp)

Close the configuration cfp. Return is less than zero on error.

const char *ap_check_cmd_context(cmd_parms *cmd, unsigned forbidden)

Checks whether cmd is permitted in the current configuration context, according to the value of forbidden. Returns NULL if it is or an appropriate error message if not. forbidden must be a combination of the following:

NOT_IN_VIRTUALHOST

Command cannot appear in a <VirtualHost> section.

NOT_IN_LIMIT

Command cannot occur in a <Limit> section.

NOT_IN_DIRECTORY

Command cannot occur in a <Directory> section.

NOT_IN_LOCATION

Command cannot occur in a <Location> section.

NOT_IN_FILES

Command cannot occur in a <Files> section.

NOT_IN_DIR_LOC_FILE

Shorthand for NOT_IN_DIRECTORY|NOT_IN_LOCATION|NOT_IN_FILES.

GLOBAL_ONLY

Shorthand for NOT_IN_VIRTUALHOST|NOT_IN_LIMIT|NOT_IN_DIR_LOC_FILE.

const char *ap_set_file_slot(cmd_parms *cmd, char *struct_ptr, char *arg)

Designed to be used in a command_rec to set a string for a file. It expects to be used with a TAKE1 command. If the file is not absolute, it is made relative to the server root. Obviously, the corresponding structure member should be a char *.

const char * ap_set_flag_slot(cmd_parms *cmd, char *struct_ptr, int arg)

Designed to be used in a command_rec to set a flag. It expects to be used with a FLAG command. The corresponding structure member should be an int, and it will be set to 0 or 1.

const char *ap_set_string_slot(cmd_parms *cmd, char *struct_ptr, char *arg)

Designed to be used in a command_rec to set a string. It expects to be used with a TAKE1 command. Obviously, the corresponding structure member should be a char *.

const char *ap_set_string_slot_lower(cmd_parms *cmd, char *struct_ptr, char *arg)

Similar to ap_set_string_slot( ), except the string is made lowercase.

A.6.18 Configuration Information Functions

Modules may need to know how some things have been configured. These functions give access to that information.

int ap_allow_options (request_rec *r)

Returns the option set for the request r. This is a bitmap composed of the bitwise OR of the following:

OPT_NONE

No options set.

OPT_INDEXES

The Indexes option.

OPT_INCLUDES

The Includes option.

OPT_SYM_LINKS

The FollowSymLinks option.

OPT_EXECCGI

The ExecCGI option.

OPT_INCNOEXEC

The IncludesNOEXEC option.

OPT_SYM_OWNER

The FollowSymLinksIfOwnerMatch option.

OPT_MULTI

The MultiViews option.

int ap_allow_overrides (request_rec *r)

Returns the overrides permitted for the request r. These are the bitwise OR of the following:

OR_NONE

No overrides are permitted.

OR_LIMIT

The Limit override.

OR_OPTIONS

The Options override.

OR_FILEINFO

The FileInfo override.

OR_AUTHCFG

The AuthConfig override.

OR_INDEXES

The Indexes override.

const char *ap_auth_type (request_rec *r)

Returns the authentication type (as set by the AuthType directive) for the request r. Currently this should only be Basic, Digest, or NULL.

const char *ap_auth_name (request_rec *r)

Returns the authentication domain name (as set by the AuthName directive) for the request r.

const array_header *ap_requires (request_rec *r)

Returns the array of require_lines that correspond to the require directive for the request r. require_line is defined as follows:

typedef struct {
    int method_mask;
    char *requirement;
} require_line;

method_mask is the bitwise OR of:

1 << M_GET
1 << M_PUT
1 << M_POST
1 << M_DELETE
1 << M_CONNECT
1 << M_OPTIONS
1 << M_TRACE
1 << M_INVALID

as set by a Limit directive.

int ap_satisfies (request_rec *r)

Returns the setting of satisfy for the request r. This is one of the following:

SATISFY_ALL

Must satisfy all authentication requirements (satisfy all).

SATISFY_ANY

Can satisfy any one of the authentication requirements (satisfy any).

A.6.19 Server Information Functions

const char *ap_ get_server_built(void)

Returns a string containing the date and time the server was built. Since this uses the C preprocessor _ _DATE_ _ and _ _TIME_ _ variables, the format is somewhat system dependent. If the preprocessor doesn't support _ _DATE_ _ or _ _TIME_ _, the string is set to "unknown."

const char *ap_ get_server_version( )

Returns a string containing Apache's version (plus any module version strings that have been added).

void ap_add_version_component(const char *component)

Adds a string to the server-version string. This function only has an effect during startup, after which the version string is locked. Version strings should take the form module name / version number, e.g., MyModule/1.3. Most modules do not add a version string.

A.6.20 Logging Functions

void ap_error_log2stderr (server_rec *s)

Makes stderr the error log for the server s. Useful when running a subprocess.

void ap_log_error (const char *file, int line, int level, const server_rec *s, 
const char *fmt, ...)

Logs an error (if level is higher than the level set with the LogLevel directive). file and line are only logged if level is APLOG_DEBUG. file and line are normally set by calling ap_log_error( ) like so:

ap_log_error(APLOG_MARK, APLOG_ERR, server_conf,"some error");

APLOG_MARK is a #define that uses _ _FILE_ _ and _ _LINE_ _ to generate the filename and line number of the call.

level is a combination of one of the following:

APLOG_EMERG

Unusable system.

APLOG_ALERT

Action to be taken immediately.

APLOG_CRIT

Critical conditions.

APLOG_ERR

Error conditions.

APLOG_WARNING

Warnings.

APLOG_NOTICE

Normal but significant condition.

APLOG_INFO

Informational.

APLOG_DEBUG

Debugging messages.

These can be optionally ORed with the following:

APLOG_NOERRNO

Do not log errno.

APLOG_WIN32ERROR

On Win32, use GetLastError( ) instead of errno.

void ap_log_reason (const char *reason, const char *file, request_rec *r)

Logs a message of the form "access to file failed for remotehost, reason: reason." The remote host is extracted from r. The message is logged with ap_log_error( ) at level APLOG_ERR.

A.6.21 Piped Log Functions

Apache provides functions to manage reliable piped logs. These are logs that are piped to another program. Apache restarts the program if it dies. This functionality is disabled if NO_RELIABLE_PIPED_LOGS is defined. The functions still exist and work, but the "reliability" is disabled.

piped_log *ap_open_piped_log (pool *p, const char *program)

The program program is launched with appropriate pipes. program may include arguments.

void ap_close_piped_log (piped_log *pl)

Closes pl. Doesn't kill the spawned child.

int ap_piped_log_write_fd(piped_log *pl)

Returns the file descriptor of an open piped log.

A.6.22 Buffering Functions

Apache provides its own I/O buffering interface. This allows chunked transfers to be done transparently and hides differences between files and sockets under Win32.

BUFF *ap_bcreate(pool *p, int flags)

Creates a new buffered stream in p. The stream is not associated with any file or socket at this point. flags are a combination of one of the following:

B_RD

Reading is buffered.

B_WR

Writing is buffered.

B_RDWR

Reading and writing are buffered.

B_SOCKET (optional)

The stream will be buffering a socket. Note that this flag also enables ASCII/EBCDIC translation on platforms that use EBCDIC (see ap_bsetflag( )).

void ap_bpushfd(BUFF *fb, int fd_in, int fd_out)

Sets the read file descriptor to fd_in and the write file descriptor to fd_out. Use -1 for file descriptors you don't want to set. Note that these descriptors must be readable with read( ) and writable with write( ).

void ap_bpushh(BUFF *fb, HANDLE hFH)

Sets a Win32 file handle for both input and output. The handle will be written with WriteFile( ) and read with ReadFile( ). Note that this function should not be used for a socket, even though a socket is a Win32 handle. ap_bpushfd( ) should be used for sockets.

int ap_bsetopt(BUFF *fb, int optname, const void *optval)

Sets the option optname to the value pointed at by optval. There is currently only one option, which is the count of bytes sent to the stream,^[5] set with BO_BYTECT. In this case, optval should point to a long. This function is used for logging and statistics and is not normally called by modules. Its main use, when it is called, is to zero the count after sending headers to a client. Returns 0 on success or -1 on failure.

int ap_bgetopt(BUFF *fb, int optname, void *optval)

Gets the value of the option optname in the location pointed at by optval. The only supported option is BO_BYTECT (see ap_bsetopt( )).

int ap_bsetflag(BUFF *fb, int flag, int value)

If value is 0, clear flag; otherwise, set it. flag is one of the following:

B_EOUT

Prevent further I/O.

B_CHUNK

Use chunked writing.

B_SAFEREAD

Force an ap_bflush( ) if a read would block.

B_ASCII2EBCDIC

Convert ASCII to EBCDIC when reading. Only available on systems that support EBCDIC.

B_EBCDIC2ASCII

Convert EBCDIC to ASCII when writing. Only available on systems that support EBCDIC.

int ap_bgetflag(BUFF *fb, int flag)

Returns 0 if flag is not set; nonzero otherwise. See ap_bsetflag( ) for a list of flags.

void ap_bonerror(BUFF *fb, void (*error) (BUFF *, int, void *),void *data)

When an error occurs on fb, error( ) is called with fb, the direction (B_RD or B_WR), and data.

int ap_bnonblock(BUFF *fb, int direction)

direction is one of B_RD or B_WR. Sets the corresponding file descriptor to be nonblocking. Returns whatever fcntl( ) returns.

int ap_bfileno(BUFF *fb, int direction)

direction is one of B_RD or B_WR. Returns the corresponding file descriptor.

int ap_bread(BUFF *fb, void *buf, int nbyte)

Reads up to nbyte bytes into buf. Returns the number of bytes read, 0 on end of file (EOF), or -1 for an error. Only reads the data currently available.

int ap_bgetc(BUFF *fb)

Reads a single character from fb. Returns the character on success and returns EOF on error or end of file. If the EOF is the result of an end of file, errno will be zero.

int ap_bgets(char *buff, int n, BUFF *fb)

Reads up to n-1 bytes into buff until an LF is seen or the end of file is reached. If LF is preceded by CR, the CR is deleted. The buffer is then terminated with a NUL (leaving the LF as the character before the NUL). Returns the number of bytes stored in the buffer, excluding the terminating NUL.

int ap_blookc(char *buff, BUFF *fb)

Places the next character in the stream in *buff, without removing it from the stream. Returns 1 on success, 0 on EOF, and -1 on error.

int ap_bskiplf(BUFF *fb)

Discards input until an LF is read. Returns 1 on success, 0 on EOF, and -1 on an error. The stream must be read-buffered (i.e., in B_RD or B_RDWR mode).

int ap_bwrite(BUFF *fb, const void *buf, int nbyte)

Writes nbyte bytes from buf to fb. Returns the number of bytes written. This can only be less than nbyte if an error occurred. Takes care of chunked encoding if the B_CHUNK flag is set.

int ap_bputc(char c, BUFF *fb)

Writes c to fb, returning 0 on success or -1 on an error.

int ap_bputs(const char *buf, BUFF *fb)

Writes the contents of buf up to, but not including, the first NUL. Returns the number of bytes written or -1 on an error.

int ap_bvputs(BUFF *fb,...)

Writes the contents of a list of buffers in the same manner as ap_bputs( ). The list of buffers is terminated with a NULL. Returns the total number of bytes written or -1 on an error. For example:

if(ap_bvputs(fb,buf1,buf2,buf3,NULL) < 0)
	...

int ap_bprintf(BUFF *fb, const char *fmt, ...)

Write formatted output, as defined by fmt, to fb. Returns the number of bytes sent to the stream.

int ap_vbprintf(BUFF *fb, const char *fmt, va_list ap)

Similar to ap_bprintf( ), except it uses a va_list instead of "...".

int ap_bflush(BUFF *fb)

Flush fb's output buffers. Returns 0 on success and -1 on error. Note that the file must be write-buffered (i.e., in B_WR or B_RDWR mode).

int ap_bclose(BUFF *fb)

Flushes the output buffer and closes the underlying file descriptors/handle/socket. Returns 0 on success and -1 on error.

A.6.23 URI Functions

Some of these functions use the uri_components structure:

typedef struct {
    char *scheme;     /* scheme ("http"/"ftp"/...) */
    char *hostinfo;   /* combined [user[:password]@]host[:port] */
    char *user;       /* username, as in http://user:passwd@host:port/ */
    char *password;   /* password, as in http://user:passwd@host:port/ */
    char *hostname;   /* hostname from URI (or from Host: header) */
    char *port_str;   /* port string (integer representation is in "port") */
    char *path;       /* The request path (or "/" if only scheme://host was 
                      /* given) */
    char *query;      /* Everything after a '?' in the path, if present */
    char *fragment;   /* Trailing "#fragment" string, if present */
    struct hostent *hostent;
    unsigned short port;	
                      /* The port number, numeric, valid only if
                      /* port_str != NULL */

    unsigned is_initialized:1;
    unsigned dns_looked_up:1;
    unsigned dns_resolved:1;
} uri_components;

int ap_parse_uri_components(pool *p, const char *uri, uri_components *uptr)

Dissects the URI uri into its components, which are placed in uptr. Each component is allocated in p. Any missing components are set to NULL. uptr->is_initialized is set to 1.

int ap_parse_hostinfo_components(pool *p, const char *hostinfo, uri_components 
*uptr)

Occasionally, it is necessary to parse host:port — for example, when handling a CONNECT request. This function does that, setting uptr->hostname, uptr->port_str, and uptr->port (if the port component is present). All other elements are set to NULL.

char *ap_unparse_uri_components(pool *p, const uri_components *uptr, unsigned flags)

Takes a filled-in uri_components, uptr, and makes a string containing the corresponding URI. The string is allocated in p. flags is a combination of none or more of the following:

UNP_OMITSITEPART

Leave out scheme://user:password@site:port.

UNP_OMITUSER

Leave out the user.

UNP_OMITPASSWORD

Leave out the password.

UNP_OMITUSERINFO

Shorthand for UNP_OMITUSER|UNP_OMITPASSWORD.

UNP_REVEALPASSWORD

Show the password (instead of replacing it with XXX).

struct hostent *ap_pgethostbyname(pool *p, const char *hostname)

Essentially does the same as the standard function gethostbyname( ), except that the result is allocated in p instead of being temporary.

struct hostent *ap_pduphostent(pool *p, const struct hostent *hp)

Duplicates hp (and everything it points at) in the pool p.

A.6.24 Miscellaneous Functions

void ap_child_terminate(request_rec *r)

Makes this instance of Apache terminate after the current request has completed. If the connection is a keepalive connection, keepalive is canceled.

unsigned short ap_default_port(request_rec *r)

Returns the default port number for the type of request handled by r. In standard Apache this is always an HTTP request, so the return is always 80; but in Apache-SSL, for example, it depends on whether HTTP or HTTPS is in use.

int ap_is_default_port(int port, request_rec *r)

Returns 1 if port is the default port for r or 0 if not.

unsigned short ap_default_port_for_scheme(const char *scheme_str)

Returns the default port for the scheme scheme.

const char *ap_http_method(request_rec *r)

Returns the default scheme for the type of request handled by r. In standard Apache this is always an HTTP request, so the return is always http; but in Apache-SSL, for example, it depends on whether HTTP or HTTPS is in use.

const char *ap_default_type(request_rec *r)

Returns the default content type for the request r. This is either set by the DefaultType directive or is text/plain.

int ap_ get_basic_auth_pw(request_rec *r, const char **pw)

If a password has been set for basic authentication (by the client), its address is put in *pw. Otherwise, an appropriate error is returned:

DECLINED

If the request does not require basic authentication

SERVER_ERROR

If no authentication domain name has been set (with AuthName)

AUTH_REQUIRED

If authentication is required but has not been sent by the client

OK

If the password has been put in *pw

void *ap_ get_module_config(void *conf_vector, module *m)

Gets the module-specific configuration set up by the module during startup. conf_vector is usually either the per_dir_config from a request_rec or module_config from a server_rec. See Chapter 21 for more information.

const char *ap_ get_remote_logname(request_rec *r)

Returns the login name of the client's user if it can be found and if the facility has been enabled with the IdentityCheck directive. Returns NULL otherwise.

const char *ap_ get_server_name(const request_rec *r)

Gets the name of the server that is handling r. If the UseCanonicalName directive is on, then it returns the name configured in the configuration file. If UseCanonicalName is off, it returns the hostname used in the request — if there was one, or the configured name if not.

unsigned ap_ get_server_port(const request_rec *r)

If UseCanonicalName is on, then returns the port configured for the server that is handling r. If UseCanonicalName is off, returns the port of the connection if the request included a hostname; otherwise the configured port.^[6]

int ap_is_initial_req(request_rec *r)

Returns 1 if r is the main request_rec (as opposed to a subrequest or internal redirect) and 0 otherwise.

int ap_matches_request_vhost(request_rec *r, const char *host, unsigned port)

Returns 1 if host:port matches the virtual host that is handling r; 0 otherwise.

void *ap_os_dso_load(const char *path)

Loads the dynamic shared object (that is, DLL, shared library, etc.) specified by path. This has a different underlying implementation according to platform. The return value is a handle that can be used by other DSO functions. Returns NULL if path cannot be loaded.

void ap_os_dso_unload(void *handle)

Unloads the dynamic shared object described by handle.

void *ap_os_dso_sym(void *handle, const char *symname)

Returns the address of symname in the dynamic shared object referred to by handle. If the platform mangles symbols in some way (for example, by prepending an underscore), this function does the same mangling before lookup. Returns NULL if symname cannot be found or an error occurs.

const char *ap_os_dso_error(void)

If an error occurs with a DSO function, this function returns a string describing the error. If no error has occurred, returns NULL.

DIR *ap_popendir(pool *p, const char *name)

Essentially the same as the standard function opendir( ), except that it registers a cleanup function that will do a closedir( ). A DIR created with this function should be closed with ap_pclosedir( ) (or left for the cleanup to close). Apart from that, the standard functions should be used.

void ap_pclosedir(pool *p, DIR * d)

Does a closedir( ) and cancels the cleanup registered by ap_popendir( ). This function should only be called on a DIR created with ap_popendir( ).

const char *ap_psignature(const char *prefix, request_rec *r)

Creates a "signature" for the server handling r. This can be nothing, the server name and port, or the server name and port hot-linked to the administrator's email address, depending on the setting of the ServerSignature directive. Unless ServerSignature is off, the returned string has prefix prepended.

int ap_vformatter(int (*flush_func)(ap_vformatter_buff *), 
ap_vformatter_buff *vbuff, const char *fmt, va_list ap)

Because Apache has several requirements for formatting functions (e.g., ap_bprintf( ), ap_psprintf( )) and it is actually not possible to implement them safely using standard functions, Apache has its own printf( )-style routines. This function is the interface to them. It takes a buffer-flushing function as an argument and an ap_vformatter_buff structure, which looks like this:

typedef struct {
    char *curpos;
    char *endpos;
} ap_vformatter_buff;

It also takes the usual format string, fmt, and varargs list, ap. ap_vformatter( ) fills the buffer (at vbuff->curpos) until vbuff->curpos == vbuff->endpos; then flush_func( ) is called with vbuff as the argument. flush_func( ) should empty the buffer and reset the values in vbuff to allow the formatting to proceed. flush_func( ) is not called when formatting is complete (unless it happens to fill the buffer). It is the responsibility of the function that calls ap_vformatter( ) to finish things off.

Since flush_func( ) almost always needs more information than that found in vbuff, the following ghastly hack is frequently employed. First, a structure with an ap_vformatter_buff as its first element is defined:^[7]

struct extra_data {
    ap_vformatter_buff vbuff;
    int some_extra_data;
    ...
};

Next, the printf( )-style routine calls ap_vformatter with an instance of this structure:

    struct extra_data mine;
    ...
    mine.some_extra_data=123;
    ap_vformatter(my_flush,&mine.vbuff,fmt,ap);
    ...

Finally, my_flush( ) does this:

API_EXPORT(int) my_flush(ap_vformatter_buff *vbuff)
{
    struct extra_data *pmine=(struct extra_data *)vbuff;
    assert(pmine->some_extra_data == 123);
    ...

As you can probably guess, we don't entirely approve of this technique, but it works.

ap_vformatter( ) does all the usual formatting, except that %p has been changed to %pp, %pA formats a struct in_addr * as a.b.c.d , and %pI formats a struct sockaddr_in * as a.b.c.d:port. The reason for these strange-looking formats is to take advantage of gcc 's format-string checking, which will make sure a %p corresponds to a pointer.

[1]  Or, in other words, mail. Since HTTP has elements borrowed from MIME and MIME is for mail, you can see the connection.

[2]  Don't think that using this function makes shell scripts safe: it doesn't. See Chapter 11.

[3]  In fact, exactly what Windows does with filenames is very poorly documented and is a seemingly endless source of security holes.

[4]  This may seem perverse, but the idea is that by asking for a Content-Length, we are implicitly requesting that there is no Transfer-Encoding (at least, not a chunked one). Getting both is an error.

[5]  Not really an option, in our view, but we didn't name the function.

[6]  Though what practical difference this makes is somewhat mysterious to us.

[7]  Of course, if you don't mind the hack being even more ghastly, it doesn't have to be first.

CONTENTS