Functions (Apache: The Definitive Guide)

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

ap_clear_pool

clear 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_pool

destroy 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_pool

report 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_blocks

report 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_palloc

allocate 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_pcalloc

allocate 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_pstrdup

duplicate 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_pstrndup

duplicate 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_pstrcat

concatenate 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:

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

returns a block of memory containing Hello, world!

14.6.2. Array Functions

ap_make_array

allocate 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_array

add 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_cat

concatenate 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_array

create 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_hdr

create 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_arrays

concatenate 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_table

create 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_table

copy a table

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

Returns a pointer to a copy of the table.

ap_table_elts

access 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_table

test whether a table is empty

int ap_is_empty_table(table *t)

Returns nonzero if the table is empty.

ap_table_set

create 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_setn

create or replace an entry in a table without duplication

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

ap_table_merge

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

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

ap_table_mergen

merge a new value into a table without duplication

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

ap_table_add

add 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_addn

add 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_unset

remove 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_get

find 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_do

apply 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_tables

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

ap_clear_table

clear a table without deleting it

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.

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_cleanup

register 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_cleanup

remove 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_exec

clear 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!

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_fd

register 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_fd

remove 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_socket

register 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_socket

remove 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_file

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

ap_run_cleanup

run a cleanup function, blocking alarms

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.

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_popenf

open 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_pclosef

close 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_pfopen

open 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_pfdopen

open 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_pfclose

close 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_psocket

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

ap_pclosesocket

close a socket created with ap_psocket( )

int ap_pclosesocket(pool *a, int sock)

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

14.6.6. Regular Expression Functions

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

ap_pregcomp

compile a regular expression with automatic cleanup

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.

ap_pregsub

substitute for regular expression submatches

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 where to substitute from. nmatch, pmatch, and source should be the same as passed to regexec(). Returns the substituted version of input in memory allocated from p.

ap_pregfree

free a regular expression compiled with ap_pregcomp( )

void ap_pregfree(pool *p, regex_t * reg)

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

ap_os_is_path_absolute

determine whether a path is absolute

int ap_os_is_path_absolute(const char *file)

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

14.6.7. Process and CGI Functions

ap_note_subprocess

register 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:

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.

ap_spawn_child

spawn 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_child

spawn a child process

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 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_exec

exec, 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_exec

check 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_vars

set 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_vars

set 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_err

scan 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:

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.

ap_scan_script_header_err_buff

scan the headers output by a CGI

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

ap_scan_script_header

scan the headers output by a CGI

int ap_scan_script_header(request_rec *r, FILE *f)

14.6.8. MD5 Functions

ap_md5

calculate the MD5 hash of a string

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.

ap_md5contextTo64

convert an MD5 context to base 64 encoding

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.

ap_md5digest

make a base 64 MD5 digest of an open file

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.

ap_MD5Init

initialize an MD5 digest

void ap_MD5Init(AP_MD5_CTX *context)

Initializes context, in preparation for an MD5 digest.

ap_MD5Final

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

ap_MD5Update

add a block to an MD5 digest

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.

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.9.1. Mutex Functions

ap_create_mutex

create a mutual exclusion object

mutex *ap_create_mutex(char *name)

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

ap_open_mutex

open a mutual exclusion object

mutex *ap_open_mutex(char *name)

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

ap_acquire_mutex

lock an open mutex object

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.

ap_release_mutex

release a locked mutex

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.

ap_destroy_mutex

destroy an open mutex

void ap_destroy_mutex(mutex *mutex_id);

Destroys the mutex mutex_id.

14.6.9.2. Semaphore Functions

create_semaphore

create a semaphore

semaphore *create_semaphore(int initial)

Creates a semaphore with an initial value of initial.

acquire_semaphore

acquire a semaphore

int acquire_semaphore(semaphore *semaphore_id)

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

release_semaphore

release a semaphore

int release_semaphore(semaphore *semaphore_id)

Releases the semaphore semaphore_id. Returns MULTI_OK or MULTI_ERR.

destroy_semaphore

destroy an open semaphore

void destroy_semaphore(semaphore *semaphore_id)

Destroys the semaphore semaphore_id.

14.6.9.3. Event Functions

create_event

create an event

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.

open_event

open an existing event

event *open_event(char *name)

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

acquire_event

wait for an event to be signaled

int acquire_event(event *event_id)

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

set_event

signal an event

int set_event(event *event_id)

Signals the event event_id. Returns MULTI_OK or MULTI_ERR.

reset_event

clear an event

int reset_event(event *event_id)

Clears the event event_id. Returns MULTI_OK or MULTI_ERR.

destroy_event

destroy an open event

void destroy_event(event *event_id)

Destroys the event event_id .

14.6.9.4. Thread Functions

create_thread

create a thread

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.

kill_thread

kill a thread

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.

await_thread

wait for a thread to complete

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.

exit_thread

exit the current thread

void exit_thread(int status)

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

free_thread

free a thread's resources

void free_thread(thread *thread_id)

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

14.6.10. Time and Date Functions

ap_get_time

return 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_time

return 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_gm_timestr_822

format a time according to RFC 822

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 [72] ). The time is always formatted as GMT. Returns a pointer to the string containing the time.

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

ap_get_gmtoff

get 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_tm2sec

convert 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_parseHTTPdate

convert 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_match

wildcard 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_match

case-blind wildcard match two strings

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

ap_is_matchexp

does a string contain wildcards?

int ap_is_matchexp(const char *exp)

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

ap_getword

extract 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_white

extract 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_nulls

extract 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_conf

extract 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_token

extract 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_token

look 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_token

check 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_escape_shell_cmd

escape dangerous characters in a shell command

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.[73]

[73]Don't think that using this function makes shell scripts safe: it doesn't. See Chapter 13, "Security".

ap_uudecode

uudecode a block of characters

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

Returns a decoded version of coded allocated in p.

ap_escape_html

escape 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_checkmask

check 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: Itself

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_tolower

convert a string to lowercase

void ap_str_tolower(char *str)

Converts str to lowercase, in place.

ap_psprintf

format 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_pvsprintf

format a string

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

ap_ind

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

ap_rind

find the last index of a character in a string

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.

14.6.12. Path, Filename, and URL Manipulation Functions

ap_getparents

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

remove "//" from a path

void ap_no2slash(char *name)

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

ap_make_dirstr

make 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_parent

make 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_prefix

copy 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_dirs

count the number of slashes in a path

int ap_count_dirs(const char *path)

Returns the number of slashes in a path.

ap_chdir_file

change 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_url

remove 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_server

make 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_url

make 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_segment

escape 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_path

escape 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_directory

checks whether a path refers to a directory

int ap_is_directory(const char *path)

Returns nonzero if path is a directory.

ap_make_full_path

combines 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_url

checks 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_fnmatch

match 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:

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.

ap_is_fnmatch

check whether a string is a pattern

int ap_is_fnmatch(const char *pattern)

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

ap_server_root_relative

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

ap_os_canonical_filename

convert a filename to its canonical form

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.

Figure 14.19 Win32, for example, is case blind, ignores trailing dots and spaces, and so on.[74] This function is generally used before checking a filename against a pattern or other similar operations.

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

14.6.13. User and Group Functions

ap_uname2id

convert a username to a user ID (UID)

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.

ap_gname2id

convert a group name to a group ID (GID)

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.

14.6.14. TCP/IP and I/O Functions

ap_get_virthost_addr

convert 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_host

get 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_host

get 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:

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: 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_fd

copy 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_length

copy 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_fb

copy an open stream to a client

long ap_send_fb(BUFF *fb, request_rec *r)

ap_send_fb_length

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

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

ap_send_mmap

send data from an in-memory buffer

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

ap_rwrite

write 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_rputc

send 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_rputs

send 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_rvputs

send 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_rprintf

send 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_rflush

flush 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_setup_client_block

prepare to receive data from the client

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 is not one that includes 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

ap_should_client_block

ready 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_block

read 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_header

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

ap_send_size

send a size approximately

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.

14.6.15. Request-Handling Functions

ap_sub_req_lookup_uri

look 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_file

look up a file as if it were a request

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

ap_run_sub_req

run 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_req

destroy 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_redirect

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

ap_internal_redirect_handler

internally redirect a request, preserving handler

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

14.6.16. Timeout and Alarm Functions

ap_hard_timeout

set 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_timeout

set 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_timeout

set a soft timeout on a request

void ap_soft_timeout(char *name, request_rec *r)

ap_reset_timeout

resets 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_timeout

clears 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_alarm

check alarm (Win32 only)

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.

14.6.17. Configuration Functions

ap_pcfg_openfile

open 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_custom

create a custom configuration

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

read 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_getline

read 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_closefile

close a configuration

int ap_cfg_closefile(configfile_t *cfp)

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

ap_check_cmd_context

check 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:

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.

ap_set_file_slot

set a file slot in a configuration structure

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

ap_set_flag_slot

set 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_slot

set 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_lower

set a lowercase string slot in a configuration structure

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

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_options

return 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:

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.

ap_allow_overrides

return 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:

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.

ap_auth_type

return 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_name

return 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_requires

return 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_DELETE
1 << M_CONNECT
1 << M_OPTIONS
1 << M_TRACE
1 << M_INVALID

as set by a Limit directive.

ap_satisfies

return the satisfy setting

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

14.6.19. Server Information Functions

ap_get_server_built

get the date and time Apache was built

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

ap_get_server_version

get the Apache version string

const char *ap_get_server_version(  )

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

ap_add_version_component

add a module version string

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, for example, MyModule/1.3. Most modules do not add a version string.

14.6.20. Logging Functions

ap_error_log2stderr

map stderr to an error log

void ap_error_log2stderr (server_rec *s)

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

ap_log_error

log an error

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: The system is unusable.
APLOG_ALERT: Action must 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.

optionally ORed with:

APLOG_NOERRNO: Do not log errno.
APLOG_WIN32ERROR: On Win32 use GetLastError() instead of errno.

ap_log_reason

log an access failure

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.

14.6.21. Piped Log Functions

Apache provides functions to manage reliable piped logs. These are logs which 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.

ap_open_piped_log

open a piped log program

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

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

ap_close_piped_log

close a piped log

void ap_close_piped_log (piped_log *pl)

Closes pl. Doesn't kill the spawned child.

ap_piped_log_write_fd

get the file descriptor of a log pipe

int ap_piped_log_write_fd(piped_log *pl)

Returns the file descriptor of an open piped log.

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_bcreate

create 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:

B_RD: Reading is buffered.
B_WR: Writing is buffered.
B_RDWR: Reading and writing are buffered.

and, optionally:

B_SOCKET: 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_bpushfd

set 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_bpushh

set a Win32 handle for a stream

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.

ap_bsetopt

set 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_bgetopt

get 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_bsetflag

set 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:

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.

ap_bgetflag

get 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_bonerror

register 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_bnonblock

set 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_bfileno

get 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_bread

read 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_bgetc

get 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_bgets

read 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_blookc

peek 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_bskiplf

discard 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_bwrite

write 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_bputc

write 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_bputs

write 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_bvputs

write 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_bprintf

write 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_vbprintf

write formatted output to a stream

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

ap_bflush

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

ap_bclose

close a stream

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.

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_components

dissect 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_components

dissect 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_components

convert 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:

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

ap_pgethostbyname

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

ap_pduphostent

duplicate a hostent structure

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

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

14.6.24. Miscellaneous Functions

ap_child_terminate

cause 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_port

return 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_port

check 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_scheme

return 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_method

return 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_type

returns 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_pw

get 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:

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

ap_get_module_config

get module-specific configuration information

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 15, "Writing Apache Modules", for more information.

ap_get_remote_logname

get 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_name

get 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_get_server_port

get the port of the current server

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, or the configured port otherwise.[77]

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

ap_is_initial_req

is 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_vhost

does 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_load

load 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_unload

unload a dynamic shared object

void ap_os_dso_unload(void *handle)

Unloads the dynamic shared object described by handle.

ap_os_dso_sym

return 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_error

get 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_popendir

do 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_pclosedir

close 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_psignature

create 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_vformatter

general-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;
    ...
    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, 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.


14.5. Access to Configuration and Request Information		15. Writing Apache Modules

14.6. Functions

14.6.1. Pool Functions

14.6.2. Array Functions

14.6.3. Table Functions

14.6.4. Cleanup Functions

14.6.5. File and Socket Functions

14.6.6. Regular Expression Functions

14.6.7. Process and CGI Functions

14.6.8. MD5 Functions

14.6.9. Synchronization and Thread Functions

14.6.9.1. Mutex Functions

14.6.9.2. Semaphore Functions

14.6.9.3. Event Functions

14.6.9.4. Thread Functions

14.6.10. Time and Date Functions

14.6.11. String Functions

14.6.12. Path, Filename, and URL Manipulation Functions

14.6.13. User and Group Functions

14.6.14. TCP/IP and I/O Functions

14.6.15. Request-Handling Functions

14.6.16. Timeout and Alarm Functions

14.6.17. Configuration Functions

14.6.18. Configuration Information Functions

14.6.19. Server Information Functions

14.6.20. Logging Functions

14.6.21. Piped Log Functions

14.6.22. Buffering Functions

14.6.23. URI Functions

14.6.24. Miscellaneous Functions