home | O'Reilly's CD bookshelfs | FreeBSD | Linux | Cisco | Cisco Exam  

Book HomeApache: The Definitive GuideSearch this book

14.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.

14.6.1. Pool Functions

ap_make_sub_poolcreate a subpool

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.

ap_clear_poolclear a pool without destroying it

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.

ap_destroy_pooldestroy a pool and all its contents

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.

ap_bytes_in_poolreport the size of a pool

long ap_bytes_in_pool(pool *p)
Returns the number of bytes currently allocated to a pool.

ap_bytes_in_free_blocksreport the total size of free blocks in the pool system

long ap_bytes_in_free_blocks(void)
Returns the number of bytes currently in free blocks for all pools.

ap_pallocallocate memory within a pool

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.

ap_pcallocallocate and clear memory within a pool

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.

ap_pstrdupduplicate a string in a pool

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.

ap_pstrndupduplicate a string in a pool with limited length

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.

ap_pstrcatconcatenate and duplicate a list of strings

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:


returns a block of memory containing Hello, world!

14.6.2. Array Functions

ap_make_arrayallocate an array of arbitrary-size elements

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.

ap_push_arrayadd a new element to an 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.

ap_array_catconcatenate two arrays

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.

ap_copy_arraycreate a copy of an array

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.

ap_copy_array_hdrcreate a copy of an array with copy-on-write

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.

ap_append_arraysconcatenate two arrays into a new array

array_header*ap_append_arrays(pool*p, const array_haeder*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.

14.6.3. Table Functions

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

ap_make_tablecreate a new table

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.

ap_copy_tablecopy a table

table *ap_copy_table(pool *p, const table *t)
Returns a pointer to a copy of the table.

ap_table_eltsaccess the array that underlies a table

array_header *ap_table_elts(table *t)
Returns the array upon which the table is based.

ap_is_empty_tabletest whether a table is empty

int ap_is_empty_table(table *t)
Returns nonzero if the table is empty.

ap_table_setcreate or replace an entry in a table

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().

ap_table_setncreate or replace an entry in a table without duplication

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.

ap_table_mergemerge a new value into a table

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;

v=table_get(t,"somekey");     /* v now contains "Hello, world!" */
ap_table_mergenmerge a new value into a table without duplication

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.

ap_table_addadd a new key/value pair to a table

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 whether or not the key already exists in the table. The key and value stored are duplicated using ap_pstrdup().

ap_table_addnadd a new key/value pair to a table without duplication

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 whether or not 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.

ap_table_unsetremove an entry from a table

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.

ap_table_getfind the value in a table corresponding to a key

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.

ap_table_doapply a function to each element of a table

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 non-empty, 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; and if the vararg list is non-empty, the traversal is repeated for any vararg item, even if they are equal.

ap_overlay_tablesconcatenate two tables to give a new table

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.

14.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.

ap_register_cleanupregister a cleanup function

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.

ap_kill_cleanupremove a cleanup function

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.

ap_cleanup_for_execclear all pools in preparation for an exec

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!

Figure 14.3 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.

ap_note_cleanups_for_fdregister a cleanup for a file descriptor

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.

ap_kill_cleanups_for_fdremove the cleanup for a file descriptor

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.

ap_note_cleanups_for_socketregister a cleanup for a socket

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.

ap_kill_cleanups_for_socketremove the cleanup for a socket

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.

ap_note_cleanups_for_fileregister a cleanup for a FILE *

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().

14.6.5. File and Socket Functions

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

ap_popenfopen a file with automatic cleanup

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.

ap_pclosefclose a file opened with popenf

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.

ap_pfopenopen a stream with automatic cleanup

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.

ap_pfdopenopen a stream from a file descriptor with automatic cleanup

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.

ap_pfcloseclose a stream opened with pfopen( ) or pfdopen( )

int ap_pfclose(pool *p, FILE *fd)
Closes the stream with fclose(), removing its cleanup function from the pool. Returns whatever fclose() returns.

ap_psocketopen a socket with automatic cleanup

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.

14.6.7. Process and CGI Functions

ap_note_subprocessregister a subprocess for killing on pool destruction

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:


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


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


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


Don't send the process any kind of kill.


Send a SIGTERM, then wait.

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

ap_spawn_childspawn a child process

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.

ap_bspawn_childspawn a child process

int ap_bspawn_child(pool *p, int (*func) (void *, child_info *), void
 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.

Figure 14.3 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 actually 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.

ap_call_execexec, spawn, or call setuid wrapper

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 exec'd 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 command-line arguments. 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.

ap_can_execcheck whether a path can be executed

int ap_can_exec(const struct stat *finfo)
Given a struct stat (from stat() et al.), returns nonzero if the file described by finfo can be executed.

ap_add_cgi_varsset environment variables for CGIs

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.

ap_add_common_varsset environment variables for subprograms

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.

ap_scan_script_header_errscan the headers output by a CGI

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:


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


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.

ap_scan_script_header_err_buffscan the headers output by a CGI

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 *.

14.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).

14.6.10. Time and Date Functions

ap_get_timereturn a human-readable version of the current time

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.

ap_ht_timereturn a pool-allocated string describing a 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.

ap_get_gmtoffget the time and calculate the local time zone offset from GMT

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.

ap_tm2secconvert a struct tm to standard Unix time

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.

ap_parseHTTPdateconvert an HTTP date to Unix time

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 timezone field.

14.6.11. String Functions

ap_strcmp_matchwildcard match two strings

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.

ap_strcasecmp_matchcase-blind wildcard match two strings

int ap_strcasecmp_match(const char *str, const char *exp)
Similar to strcmp_match, except matching is case blind.

ap_is_matchexpdoes a string contain wildcards?

int ap_is_matchexp(const char *exp)
Returns 1 if exp contains * or ?; 0 otherwise.

ap_getwordextract one word from a list of words

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 **.

ap_getword_whiteextract one word from a list of words

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).

ap_getword_nullsextract one word from a list of words

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.

ap_getword_confextract one word from a list of words

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.

ap_get_tokenextract a token from a string

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.

ap_find_tokenlook for a token in a line (usually an HTTP header)

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.

ap_find_last_tokencheck if the last token is a particular string

int ap_find_last_token(pool *p, const char *line, const char *tok)
Checks whether the end of line matches tok, and tok is preceded by a space or a comma. Returns 1 if so, 0 otherwise.

ap_uudecodeuudecode a block of characters

char *ap_uudecode(pool *p, const char *coded)
Returns a decoded version of coded allocated in p.

ap_escape_htmlescape some HTML

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.

ap_checkmaskcheck whether a string matches a mask

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


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

if(ap_checkmask(date, "## @$$ #### ##:##:## *"))
ap_str_tolowerconvert a string to lowercase

void ap_str_tolower(char *str)
Converts str to lowercase, in place.

ap_psprintfformat a string

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().

ap_pvsprintfformat a string

char *ap_pvsprintf(pool *p, const char *fmt, va_list ap)
Similar to ap_psprintf(), except that varargs are used.

ap_indfind the first index of a character in a string

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.

14.6.12. Path, Filename, and URL Manipulation Functions

ap_getparentsremove "." and ".." segments from a path

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.

ap_no2slashremove "//" from a path

void ap_no2slash(char *name)
Removes double slashes from a path. This is important for correct matching of URLs.

ap_make_dirstrmake a copy of a path with a trailing slash, if needed

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.

ap_make_dirstr_parentmake the path of the parent directory

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.

ap_make_dirstr_prefixcopy part of a path

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.

ap_count_dirscount the number of slashes in a path

int ap_count_dirs(const char *path)
Returns the number of slashes in a path.

ap_chdir_filechange to the directory containing file

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.

ap_unescape_urlremove escape sequences from a URL

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.

ap_construct_servermake the server part of a URL

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.

ap_construct_urlmake an HTTP URL

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 appending uri. Returns a pointer to the URL.

ap_escape_path_segmentescape a path segment as per RFC 1808

char *ap_escape_path_segment(pool *p, const char *segment)
Returns an escaped version of segment, as per RFC 1808.

ap_os_escape_pathescape a path 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 ":").

ap_is_directorychecks whether a path refers to a directory

int ap_is_directory(const char *path)
Returns nonzero if path is a directory.

ap_make_full_pathcombines two paths into one

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.

ap_is_urlchecks whether a string is in fact a URL

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>."

ap_fnmatchmatch a filename

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.


A closure, like 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:


Treat a "\" as a normal character.


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


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

ap_is_fnmatchcheck whether a string is a pattern

int ap_is_fnmatch(const char *pattern)
Returns 1 if pattern contains ?, *, or [...], 0 otherwise.

ap_server_root_relativemake a path relative to the server root

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).

14.6.14. TCP/IP and I/O Functions

ap_get_virthost_addrconvert a hostname or port to an address

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.

ap_get_local_hostget the FQDN for the local host

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.

ap_get_remote_hostget client hostname or IP address

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:


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


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


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).


Do 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.

ap_send_fdcopy an open file to the client

long ap_send_fd(FILE *f, request_rec *r)
Copies the stream f to the client. Returns the number of bytes sent.

ap_send_fd_lengthcopy a number of bytes from an open file to the client

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.

ap_send_fbcopy an open stream to a client

long ap_send_fb(BUFF *fb, request_rec *r)
Similar to ap_send_fd() except that it sends a BUFF * instead of a FILE *.

ap_send_fb_lengthcopy a number of bytes from an open stream to a client

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 *.

ap_send_mmapsend data from an in-memory buffer

size_t ap_send_mmap(void *mm, request_rec *r, size_t offset, size_t
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).

ap_rwritewrite a buffer to the client

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.

ap_rputcsend a character to the client

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.

ap_rputssend a string to the client

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.

ap_rvputssend a list of strings to the client

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.

ap_rprintfsend a formatted string to the client

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.

ap_rflushflush client output

int ap_rflush(request_rec *r)
Causes any buffered data to be sent to the client. Returns 0 on success, -1 on an error.

ap_should_client_blockready to receive data from the client

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.

ap_get_client_blockread a block of 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.

ap_send_http_headersend the response headers to the client

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.

14.6.15. Request-Handling Functions

ap_sub_req_lookup_urilook up a URI as if it were a request

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.

ap_sub_req_lookup_filelook up a file as if it were a request

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.

ap_run_sub_reqrun a subrequest

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.

ap_destroy_sub_reqdestroy a subrequest

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.

ap_internal_redirectinternally redirect a request

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.

14.6.16. Timeout and Alarm Functions

ap_hard_timeoutset a hard timeout on a request

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.

ap_keepalive_timeoutset the keepalive timeout on a request

void ap_keepalive_timeout(char *name, request_rec *r)
Works like ap_hard_timeout() except that if the request is kept alive, the keep-alive timeout is used instead of the server timeout. This should normally be used only when awaiting a request from the client, and thus is used only in http_protocol.c, but is included here for completeness.

ap_soft_timeoutset a soft timeout on a request

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).

ap_reset_timeoutresets a hard or soft timeout to its original time

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.

ap_kill_timeoutclears a timeout

void ap_kill_timeout(request_rec *r)
Clears the current timeout on the request r.

ap_block_alarms( )temporarily prevents a timeout from occurring

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().

ap_unblock_alarms( )unblock a blocked alarm

void ap_unblock_alarms(void)
Remove a block placed by ap_block_alarms().

ap_check_alarmcheck alarm (Win32 only)

int ap_check_alarm(void)
Figure 14.8 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.

14.6.17. Configuration Functions

ap_pcfg_openfileopen a file as a configuration

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 on success.

ap_pcfg_open_customcreate a custom configuration

configfile_t *ap_pcfg_open_custom(pool *p, const char *descr, void
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.

ap_cfg_getcread a character from a configuration

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.

ap_cfg_getlineread a line from a configuration, stripping whitespace

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.

ap_cfg_closefileclose a configuration

int ap_cfg_closefile(configfile_t *cfp)
Close the configuration cfp. Return is less than zero on error.

ap_check_cmd_contextcheck if configuration cmd allowed in current context

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:


Command cannot appear in a <VirtualHost> section.


Command cannot occur in a <Limit> section.


Command cannot occur in a <Directory> section.


Command cannot occur in a <Location> section.


Command cannot occur in a <Files> section.





ap_set_file_slotset a file slot in a configuration structure

const char *ap_set_file_slot(cmd_parms *cmd, char *struct_ptr, char
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 *.

ap_set_flag_slotset a flag slot in a configuration structure.

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.

ap_set_string_slotset a string slot in a configuration structure

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 *.

ap_set_string_slot_lowerset a lowercase string slot in a configuration structure

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.

14.6.18. Configuration Information Functions

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

ap_allow_optionsreturn options set with the Options directive

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:


No options set.


The Indexes option.


The Includes option.


The FollowSymLinks option.


The ExecCGI option.


The IncludesNOEXEC option.


The FollowSymLinksIfOwnerMatch option.


The MultiViews option.

ap_allow_overridesreturn overrides set with the AllowOverride option

int ap_allow_overrides (request_rec *r)
Returns the overrides permitted for the request r. These are the bitwise OR of the following:


No overrides are permitted.


The Limit override.


The Options override.


The FileInfo override.


The AuthConfig override.


The Indexes override.

ap_auth_typereturn the authentication type for this request

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.

ap_auth_namereturn the authentication domain name

const char *ap_auth_name (request_rec *r)
Returns the authentication domain name (as set by the AuthName directive) for the request r.

ap_requiresreturn the require array

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_TRACE

as set by a Limit directive.

14.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.

ap_bcreatecreate a buffered stream

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:


Reading is buffered.


Writing is buffered.


Reading and writing are buffered.

and, optionally:


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

ap_bpushfdset the file descriptors for a stream

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().

ap_bpushhset a Win32 handle for a stream

void ap_bpushh(BUFF *fb, HANDLE hFH)
Figure 14.3 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.

ap_bsetoptset an option

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,
[76] 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, -1 on failure.

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

ap_bgetoptget the value of an option

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()).

ap_bsetflagset or clear a flag

int ap_bsetflag(BUFF *fb, int flag, int value)
If value is 0, clear flag; otherwise, set it. flag is one of the following:


Prevent further I/O.


Use chunked writing.


Force an ap_bflush() if a read would block.


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


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

ap_bgetflagget a flag's setting

int ap_bgetflag(BUFF *fb, int flag)
Returns 0 if flag is not set, nonzero otherwise. See ap_bsetflag() for a list of flags.

ap_bonerrorregister an error function

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.

ap_bnonblockset a stream to nonblocking mode

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.

ap_bfilenoget a file descriptor from a stream

int ap_bfileno(BUFF *fb, int direction)
direction is one of B_RD or B_WR. Returns the corresponding file descriptor.

ap_breadread from a stream

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.

ap_bgetcget a character from a stream

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.

ap_bgetsread a line from a stream

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.

ap_blookcpeek at the next character in a stream

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.

ap_bskiplfdiscard until an LF is read

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).

ap_bwritewrite to a stream

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.

ap_bputcwrite a single character to a stream

int ap_bputc(char c, BUFF *fb)
Writes c to fb, returning 0 on success, -1 on an error.

ap_bputswrite a NUL-terminated string to a stream

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.

ap_bvputswrite several NUL-terminated strings to a stream

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)
ap_bprintfwrite formatted output to a stream

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.

ap_vbprintfwrite formatted output to a stream

int ap_vbprintf(BUFF *fb, const char *fmt, va_list ap)
Similar to ap_bprintf(), except it uses a va_list instead of "...".

ap_bflushflush output buffers

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).

14.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;
ap_parse_uri_componentsdissect a full URI

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.

ap_parse_hostinfo_componentsdissect host:port

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.

ap_unparse_uri_componentsconvert back to a URI

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:


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


Leave out the user.


Leave out the password.




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

ap_pgethostbynameresolve a hostname

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.

14.6.24. Miscellaneous Functions

ap_child_terminatecause the current process to terminate

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 cancelled.

ap_default_portreturn the default port for a request

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.

ap_is_default_portcheck whether a port is the default port

int ap_is_default_port(int port, request_rec *r)
Returns 1 if port is the default port for r, 0 if not.

ap_default_port_for_schemereturn the default port for a scheme

unsigned short ap_default_port_for_scheme(const char *scheme_str)
Returns the default port for the scheme scheme.

ap_http_methodreturn the scheme for a request

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.

ap_default_typereturns default content type

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.

ap_get_basic_auth_pwget the password supplied for basic authentication

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:


If the request does not require basic authentication


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


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


If the password has been put in *pw

ap_get_remote_lognameget the login name of the client's user

const char *ap_get_remote_logname(request_rec *r)
Returns the login name of the client's user, if it can be found and the facility has been enabled with the IdentityCheck directive. Returns NULL otherwise.

ap_get_server_nameget the name of the current server

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.

ap_is_initial_reqis this the main request_rec?

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.

ap_matches_request_vhostdoes a host match a request's virtual host?

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.

ap_os_dso_loadload a dynamic shared object (DSO)

void *ap_os_dso_load(const char *path)
Loads the dynamic shared object (that is, DLL, shared library, or whatever) 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.

ap_os_dso_unloadunload a dynamic shared object

void ap_os_dso_unload(void *handle)
Unloads the dynamic shared object described by handle.

ap_os_dso_symreturn the address of a symbol

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.

ap_os_dso_errorget a string describing a DSO error

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.

ap_popendirdo an opendir( ) with cleanup

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.

ap_pclosedirclose a DIR opened with ap_popendir( )

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().

ap_psignaturecreate the server "signature"

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 hotlinked to the administrator's email address, depending on the setting of the ServerSignature directive. Unless ServerSignature is off, the returned string has prefix prepended.

ap_vformattergeneral-purpose formatter

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;

as well as 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[78] is defined:

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

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;

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, and %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.

Library Navigation Links

Copyright © 2001 O'Reilly & Associates. All rights reserved.