Pool Cleanup Functions

Collaboration diagram for Pool Cleanup Functions:

Functions
	APR_DECLARE_NONSTD (apr_status_t) apr_pool_cleanup_null(void *data)
Variables
const void *	data
const void apr_status_t(*	plain_cleanup )(void *)
const void apr_status_t(*) apr_status_t(*	child_cleanup )(void *)) __attribute__((nonnull(3
const void apr_status_t(*) apr_status_t(*	APR_DECLARE )(void) apr_pool_pre_cleanup_register(apr_pool_t *p

---

Detailed Description

Cleanups are performed in the reverse order they were registered. That is: Last In, First Out. A cleanup function can safely allocate memory from the pool that is being cleaned up. It can also safely register additional cleanups which will be run LIFO, directly after the current cleanup terminates. Cleanups have to take caution in calling functions that create subpools. Subpools, created during cleanup will NOT automatically be cleaned up. In other words, cleanups are to clean up after themselves.

---

Function Documentation

APR_DECLARE_NONSTD

(

int

)

An empty cleanup function.

Passed to apr_pool_cleanup_register() when no cleanup is required.

Parameters:

data	The data to cleanup, will not be used by this function.

Write a string to a file using a printf format.

Parameters:

fptr	The file to write to.
format	The format string
...	The values to substitute in the format string

Returns:

The number of bytes written

snprintf routine based on apr_vformatter. This means it understands the same extensions.

Parameters:

buf	The buffer to write to
len	The size of the buffer
format	The format string
...	The arguments to use to fill out the format string.

Iterate over a table running the provided function once for every element in the table. The varargs array must be a list of zero or more (char *) keys followed by a NULL pointer. If zero keys are given, the

Parameters:

comp	function will be invoked for every element in the table. Otherwise, the function is invoked only for those elements matching the keys specified.

If an invocation of the

Parameters:

comp	function returns zero, iteration will continue using the next specified key, if any.
comp	The function to run
rec	The data to pass as the first argument to the function
t	The table to iterate over
...	A varargs array of zero or more (char *) keys followed by NULL

Returns:

FALSE if one of the comp() iterations returned zero; TRUE if all iterations returned non-zero

See also:

apr_table_do_callback_fn_t

---

Variable Documentation

APR_DECLARE

Register a function to be called when a pool is cleared or destroyed.

Unlike apr_pool_cleanup_register which register a cleanup that is called AFTER all subpools are destroyed this function register a function that will be called before any of the subpool is destoryed.

Parameters:

p	The pool register the cleanup with
data	The data to pass to the cleanup function.
plain_cleanup	The function to call when the pool is cleared or destroyed

Run the specified cleanup function immediately and unregister it.

The cleanup most recently registered with p having the same values of data and cleanup will be removed and cleanup will be called with data as the argument.

Parameters:

p	The pool to remove the cleanup from
data	The data to remove from cleanup
cleanup	The function to remove from cleanup

Free a list of blocks of mem, giving them back to the allocator. The list is typically terminated by a memnode with its next field set to NULL.

Parameters:

allocator	The allocator to give the mem back to
memnode	The memory node to return

Set the owner of the allocator

Parameters:

allocator	The allocator to set the owner for
pool	The pool that is to own the allocator

Remarks:

Typically pool is the highest level pool using the allocator

Set the current threshold at which the allocator should start giving blocks back to the system.

Parameters:

allocator	The allocator the set the threshold on
size	The threshold. 0 == unlimited.

atomically add 'val' to an apr_uint32_t

Parameters:

mem	pointer to the object
val	amount to add

Returns:

old value pointed to by mem

atomically subtract 'val' from an apr_uint32_t

Parameters:

mem	pointer to the object
val	amount to subtract

atomically increment an apr_uint32_t by 1

Parameters:

mem	pointer to the object

Returns:

old value pointed to by mem

atomically decrement an apr_uint32_t by 1

Parameters:

mem	pointer to the atomic value

Returns:

zero if the value becomes zero on decrement, otherwise non-zero

compare an apr_uint32_t's value with 'cmp'. If they are the same swap the value with 'with'

Parameters:

mem	pointer to the value
with	what to swap it with
cmp	the value to compare it to

Returns:

the old value of *mem

exchange an apr_uint32_t's value with 'val'.

Parameters:

mem	pointer to the value
val	what to swap it with

Returns:

the old value of *mem

exchange a pair of pointer values

Parameters:

mem	pointer to the pointer
with	what to swap it with

Returns:

the old value of the pointer

Set the value of an environment variable

Parameters:

envvar	the name of the environment variable
value	the value to set
pool	where to allocate temporary storage from

Delete a variable from the environment

Parameters:

envvar	the name of the environment variable
pool	where to allocate temporary storage from

Open the specified directory.

Parameters:

new_dir	The opened directory descriptor.
dirname	The full path to the directory (use / on all systems)
pool	The pool to use.

close the specified directory.

Parameters:

thedir

the directory descriptor to close.

Read the next entry from the specified directory.

Parameters:

finfo	the file info structure and filled in by apr_dir_read
wanted	The desired apr_finfo_t fields, as a bit flag of APR_FINFO_ values
thedir	the directory descriptor returned from apr_dir_open

Remarks:

No ordering is guaranteed for the entries read.

Note:

If APR_INCOMPLETE is returned all the fields in finfo may not be filled in, and you need to check the finfo->valid bitmask to verify that what you're looking for is there. When no more entries are available, APR_ENOENT is returned.

Rewind the directory to the first entry.

Parameters:

thedir

the directory descriptor to rewind.

Extract the rootpath from the given filepath

Parameters:

rootpath	the root file path returned with APR_SUCCESS or APR_EINCOMPLETE
filepath	the pathname to parse for its root component
flags	the desired rules to apply, from APR_FILEPATH_NATIVE Use native path seperators (e.g. '\' on Win32) APR_FILEPATH_TRUENAME Tests that the root exists, and makes it proper
p	the pool to allocate the new path string from

Remarks:

on return, filepath points to the first non-root character in the given filepath. In the simplest example, given a filepath of "/foo", returns the rootpath of "/" and filepath points at "foo". This is far more complex on other platforms, which will canonicalize the root form to a consistant format, given the APR_FILEPATH_TRUENAME flag, and also test for the validity of that root (e.g., that a drive d:/ or network share //machine/foovol/). The function returns APR_ERELATIVE if filepath isn't rooted (an error), APR_EINCOMPLETE if the root path is ambigious (but potentially legitimate, e.g. "/" on Windows is incomplete because it doesn't specify the drive letter), or APR_EBADPATH if the root is simply invalid. APR_SUCCESS is returned if filepath is an absolute path.

Merge additional file path onto the previously processed rootpath

Parameters:

newpath	the merged paths returned
rootpath	the root file path (NULL uses the current working path)
addpath	the path to add to the root path
flags	the desired APR_FILEPATH_ rules to apply when merging
p	the pool to allocate the new path string from

Remarks:

if the flag APR_FILEPATH_TRUENAME is given, and the addpath contains wildcard characters ('*', '?') on platforms that don't support such characters within filenames, the paths will be merged, but the result code will be APR_EPATHWILD, and all further segments will not reflect the true filenames including the wildcard and following segments.

Split a search path into separate components

Parameters:

pathelts	the returned components of the search path
liststr	the search path (e.g., getenv("PATH"))
p	the pool to allocate the array and path components from

Remarks:

empty path componenta do not become part of pathelts.

the path separator in liststr is system specific; e.g., ':' on Unix, ';' on Windows, etc.

Merge a list of search path components into a single search path

Parameters:

liststr	the returned search path; may be NULL if pathelts is empty
pathelts	the components of the search path
p	the pool to allocate the search path from

Remarks:

emtpy strings in the source array are ignored.

the path separator in liststr is system specific; e.g., ':' on Unix, ';' on Windows, etc.

Return the default file path (for relative file names)

Parameters:

path	the default path string returned
flags	optional flag APR_FILEPATH_NATIVE to retrieve the default file path in os-native format.
p	the pool to allocate the default path string from

Set the default file path (for relative file names)

Parameters:

path	the default path returned
p	the pool to allocate any working storage

Determine the encoding used internally by the FilePath functions

Parameters:

style	points to a variable which receives the encoding style flag
p	the pool to allocate any working storage

Remarks:

Use apr_os_locale_encoding and/or apr_os_default_encoding to get the name of the path encoding if it's not UTF-8.

Close the specified file.

Parameters:

file	The file descriptor to close.

Delete the specified file.

Parameters:

path	The full path to the file (using / on all systems)
pool	The pool to use.

Remarks:

If the file is open, it won't be removed until all instances are closed.

Rename the specified file.

Parameters:

from_path	The full path to the original file (using / on all systems)
to_path	The full path to the new file (using / on all systems)
pool	The pool to use.

Warning:

If a file exists at the new location, then it will be overwritten. Moving files or directories across devices may not be possible.

Create a hard link to the specified file.

Parameters:

from_path	The full path to the original file (using / on all systems)
to_path	The full path to the new file (using / on all systems)

Remarks:

Both files must reside on the same device.

Copy the specified file to another file.

Parameters:

from_path	The full path to the original file (using / on all systems)
to_path	The full path to the new file (using / on all systems)
perms	Access permissions for the new file if it is created. In place of the usual or'd combination of file permissions, the value APR_FILE_SOURCE_PERMS may be given, in which case the source file's permissions are copied.
pool	The pool to use.

Remarks:

The new file does not need to exist, it will be created if required.

Warning:

If the new file already exists, its contents will be overwritten.

Append the specified file to another file.

Parameters:

from_path	The full path to the source file (use / on all systems)
to_path	The full path to the destination file (use / on all systems)
perms	Access permissions for the destination file if it is created. In place of the usual or'd combination of file permissions, the value APR_FILE_SOURCE_PERMS may be given, in which case the source file's permissions are copied.
pool	The pool to use.

Remarks:

The new file does not need to exist, it will be created if required.

Are we at the end of the file

Parameters:

fptr	The apr file we are testing.

Remarks:

Returns APR_EOF if we are at the end of file, APR_SUCCESS otherwise.

Open standard error as an apr file pointer.

Parameters:

thefile	The apr file to use as stderr.
pool	The pool to allocate the file out of.

Remarks:

The only reason that the apr_file_open_std* functions exist is that you may not always have a stderr/out/in on Windows. This is generally a problem with newer versions of Windows and services.

The other problem is that the C library functions generally work differently on Windows and Unix. So, by using apr_file_open_std* functions, you can get a handle to an APR struct that works with the APR functions which are supposed to work identically on all platforms.

open standard output as an apr file pointer.

Parameters:

thefile	The apr file to use as stdout.
pool	The pool to allocate the file out of.

Remarks:

See remarks for apr_file_open_stderr.

open standard input as an apr file pointer.

Parameters:

thefile	The apr file to use as stdin.
pool	The pool to allocate the file out of.

Remarks:

See remarks for apr_file_open_stderr.

open standard error as an apr file pointer, with flags.

Parameters:

thefile	The apr file to use as stderr.
flags	The flags to open the file with. Only the APR_EXCL, APR_BUFFERED, APR_XTHREAD, APR_SHARELOCK, APR_SENDFILE_ENABLED and APR_LARGEFILE flags should be used. The APR_WRITE flag will be set unconditionally.
pool	The pool to allocate the file out of.

Remarks:

See remarks for apr_file_open_stderr.

open standard output as an apr file pointer, with flags.

Parameters:

thefile	The apr file to use as stdout.
flags	The flags to open the file with. Only the APR_EXCL, APR_BUFFERED, APR_XTHREAD, APR_SHARELOCK, APR_SENDFILE_ENABLED and APR_LARGEFILE flags should be used. The APR_WRITE flag will be set unconditionally.
pool	The pool to allocate the file out of.

Remarks:

See remarks for apr_file_open_stderr.

open standard input as an apr file pointer, with flags.

Parameters:

thefile	The apr file to use as stdin.
flags	The flags to open the file with. Only the APR_EXCL, APR_BUFFERED, APR_XTHREAD, APR_SHARELOCK, APR_SENDFILE_ENABLED and APR_LARGEFILE flags should be used. The APR_READ flag will be set unconditionally.
pool	The pool to allocate the file out of.

Remarks:

See remarks for apr_file_open_stderr.

Read data from the specified file.

Parameters:

thefile	The file descriptor to read from.
buf	The buffer to store the data to.
nbytes	On entry, the number of bytes to read; on exit, the number of bytes read.

Remarks:

apr_file_read will read up to the specified number of bytes, but never more. If there isn't enough data to fill that number of bytes, all of the available data is read. The third argument is modified to reflect the number of bytes read. If a char was put back into the stream via ungetc, it will be the first character returned.

It is not possible for both bytes to be read and an APR_EOF or other error to be returned. APR_EINTR is never returned.

Write data to the specified file.

Parameters:

thefile	The file descriptor to write to.
buf	The buffer which contains the data.
nbytes	On entry, the number of bytes to write; on exit, the number of bytes written.

Remarks:

apr_file_write will write up to the specified number of bytes, but never more. If the OS cannot write that many bytes, it will write as many as it can. The third argument is modified to reflect the * number of bytes written.

It is possible for both bytes to be written and an error to be returned. APR_EINTR is never returned.

Write data from iovec array to the specified file.

Parameters:

thefile	The file descriptor to write to.
vec	The array from which to get the data to write to the file.
nvec	The number of elements in the struct iovec array. This must be smaller than APR_MAX_IOVEC_SIZE. If it isn't, the function will fail with APR_EINVAL.
nbytes	The number of bytes written.

Remarks:

It is possible for both bytes to be written and an error to be returned. APR_EINTR is never returned.

apr_file_writev is available even if the underlying operating system doesn't provide writev().

Read data from the specified file, ensuring that the buffer is filled before returning.

Parameters:

thefile	The file descriptor to read from.
buf	The buffer to store the data to.
nbytes	The number of bytes to read.
bytes_read	If non-NULL, this will contain the number of bytes read.

Remarks:

apr_file_read will read up to the specified number of bytes, but never more. If there isn't enough data to fill that number of bytes, then the process/thread will block until it is available or EOF is reached. If a char was put back into the stream via ungetc, it will be the first character returned.

It is possible for both bytes to be read and an error to be returned. And if *bytes_read is less than nbytes, an accompanying error is _always_ returned.

APR_EINTR is never returned.

Write data to the specified file, ensuring that all of the data is written before returning.

Parameters:

thefile	The file descriptor to write to.
buf	The buffer which contains the data.
nbytes	The number of bytes to write.
bytes_written	If non-NULL, set to the number of bytes written.

Remarks:

apr_file_write will write up to the specified number of bytes, but never more. If the OS cannot write that many bytes, the process/thread will block until they can be written. Exceptional error such as "out of space" or "pipe closed" will terminate with an error.

It is possible for both bytes to be written and an error to be returned. And if *bytes_written is less than nbytes, an accompanying error is _always_ returned.

APR_EINTR is never returned.

Write data from iovec array to the specified file, ensuring that all of the data is written before returning.

Parameters:

thefile	The file descriptor to write to.
vec	The array from which to get the data to write to the file.
nvec	The number of elements in the struct iovec array. This must be smaller than APR_MAX_IOVEC_SIZE. If it isn't, the function will fail with APR_EINVAL.
nbytes	The number of bytes written.

Remarks:

apr_file_writev_full is available even if the underlying operating system doesn't provide writev().

Write a character into the specified file.

Parameters:

ch	The character to write.
thefile	The file descriptor to write to

Read a character from the specified file.

Parameters:

ch	The character to read into
thefile	The file descriptor to read from

Put a character back onto a specified stream.

Parameters:

ch	The character to write.
thefile	The file descriptor to write to

Read a line from the specified file

Parameters:

str	The buffer to store the string in.
len	The length of the string
thefile	The file descriptor to read from

Remarks:

The buffer will be NUL-terminated if any characters are stored. The newline at the end of the line will not be stripped.

Write the string into the specified file.

Parameters:

str	The string to write.
thefile	The file descriptor to write to

Flush the file's buffer.

Parameters:

thefile

The file descriptor to flush

Transfer all file modified data and metadata to disk.

Parameters:

thefile

The file descriptor to sync

Transfer all file modified data to disk.

Parameters:

thefile

The file descriptor to sync

Duplicate the specified file descriptor.

Parameters:

new_file	The structure to duplicate into.
old_file	The file to duplicate.
p	The pool to use for the new file.

Remarks:

*new_file must point to a valid apr_file_t, or point to NULL.

Duplicate the specified file descriptor and close the original

Parameters:

new_file	The old file that is to be closed and reused
old_file	The file to duplicate
p	The pool to use for the new file

Remarks:

new_file MUST point at a valid apr_file_t. It cannot be NULL.

Move the specified file descriptor to a new pool

Parameters:

new_file	Pointer in which to return the new apr_file_t
old_file	The file to move
p	The pool to which the descriptor is to be moved

Remarks:

Unlike apr_file_dup2(), this function doesn't do an OS dup() operation on the underlying descriptor; it just moves the descriptor's apr_file_t wrapper to a new pool.

The new pool need not be an ancestor of old_file's pool.

After calling this function, old_file may not be used

Give the specified apr file handle a new buffer

Parameters:

thefile	The file handle that is to be modified
buffer	The buffer
bufsize	The size of the buffer

Remarks:

It is possible to add a buffer to previously unbuffered file handles, the APR_BUFFERED flag will be added to the file handle's flags. Likewise, with buffer=NULL and bufsize=0 arguments it is possible to make a previously buffered file handle unbuffered.

Move the read/write file offset to a specified byte within a file.

Parameters:

thefile	The file descriptor
where	How to move the pointer, one of: APR_SET -- set the offset to offset APR_CUR -- add the offset to the current position APR_END -- add the offset to the current file size
offset	The offset to move the pointer to.

Remarks:

The third argument is modified to be the offset the pointer was actually moved to.

Create an anonymous pipe.

Parameters:

in	The newly created pipe's file for reading.
out	The newly created pipe's file for writing.
pool	The pool to operate on.

Remarks:

By default, the returned file descriptors will be inherited by child processes created using apr_proc_create(). This can be changed using apr_file_inherit_unset().

Bug:

Some platforms cannot toggle between blocking and nonblocking, and when passing a pipe as a standard handle to an application which does not expect it, a non-blocking stream will fluxor the client app.

Deprecated:

See also:

apr_file_pipe_create_ex

Create an anonymous pipe which portably supports async timeout options.

Parameters:

in	The newly created pipe's file for reading.
out	The newly created pipe's file for writing.
blocking	one of these values defined in apr_thread_proc.h;
pool	The pool to operate on. APR_FULL_BLOCK APR_READ_BLOCK APR_WRITE_BLOCK APR_FULL_NONBLOCK

Remarks:

By default, the returned file descriptors will be inherited by child processes created using apr_proc_create(). This can be changed using apr_file_inherit_unset().

Some platforms cannot toggle between blocking and nonblocking, and when passing a pipe as a standard handle to an application which does not expect it, a non-blocking stream will fluxor the client app. Use this function rather than apr_file_pipe_create to create pipes where one or both ends require non-blocking semantics.

Create a named pipe.

Parameters:

filename	The filename of the named pipe
perm	The permissions for the newly created pipe.
pool	The pool to operate on.

Get the timeout value for a pipe or manipulate the blocking state.

Parameters:

thepipe	The pipe we are getting a timeout for.
timeout	The current timeout value in microseconds.

Set the timeout value for a pipe or manipulate the blocking state.

Parameters:

thepipe	The pipe we are setting a timeout on.
timeout	The timeout value in microseconds. Values < 0 mean wait forever, 0 means do not wait at all.

file (un)locking functions. Establish a lock on the specified, open file. The lock may be advisory or mandatory, at the discretion of the platform. The lock applies to the file as a whole, rather than a specific range. Locks are established on a per-thread/process basis; a second lock by the same thread will not block.

Parameters:

thefile	The file to lock.
type	The type of lock to establish on the file.

Remove any outstanding locks on the file.

Parameters:

thefile

The file to unlock.

accessor and general file_io functions. return the file name of the current file.

Parameters:

new_path	The path of the file.
thefile	The currently open file.

Return the data associated with the current file.

Parameters:

data	The user data associated with the file.
key	The key to use for retrieving data associated with this file.
file	The currently open file.

Set the data associated with the current file.

Parameters:

file	The currently open file.
data	The user data to associate with the file.
key	The key to use for associating data with the file.
cleanup	The cleanup routine to use when the file is destroyed.

set the specified file's permission bits.

Parameters:

fname	The file (name) to apply the permissions to.
perms	The permission bits to apply to the file.

Warning:

Some platforms may not be able to apply all of the available permission bits; APR_INCOMPLETE will be returned if some permissions are specified which could not be set.

Platforms which do not implement this feature will return APR_ENOTIMPL.

Set attributes of the specified file.

Parameters:

fname	The full path to the file (using / on all systems)
attributes	Or'd combination of APR_FILE_ATTR_READONLY - make the file readonly APR_FILE_ATTR_EXECUTABLE - make the file executable APR_FILE_ATTR_HIDDEN - make the file hidden
attr_mask	Mask of valid bits in attributes.
pool	the pool to use.

Remarks:

This function should be used in preference to explicit manipulation of the file permissions, because the operations to provide these attributes are platform specific and may involve more than simply setting permission bits.

Warning:

Platforms which do not implement this feature will return APR_ENOTIMPL.

Set the mtime of the specified file.

Parameters:

fname	The full path to the file (using / on all systems)
mtime	The mtime to apply to the file.
pool	The pool to use.

Warning:

Platforms which do not implement this feature will return APR_ENOTIMPL.

Create a new directory on the file system.

Parameters:

path	the path for the directory to be created. (use / on all systems)
perm	Permissions for the new directory.
pool	the pool to use.

Creates a new directory on the file system, but behaves like 'mkdir -p'. Creates intermediate directories as required. No error will be reported if PATH already exists.

Parameters:

path	the path for the directory to be created. (use / on all systems)
perm	Permissions for the new directory.
pool	the pool to use.

Remove directory from the file system.

Parameters:

path	the path for the directory to be removed. (use / on all systems)
pool	the pool to use.

Remarks:

Removing a directory which is in-use (e.g., the current working directory, or during apr_dir_read, or with an open file) is not portable.

get the specified file's stats.

Parameters:

finfo	Where to store the information about the file.
wanted	The desired apr_finfo_t fields, as a bit flag of APR_FINFO_ values
thefile	The file to get information about.

Truncate the file's length to the specified offset

Parameters:

fp	The file to truncate
offset	The offset to truncate to.

Remarks:

The read/write file offset is repositioned to offset.

Open a temporary file

Parameters:

fp	The apr file to use as a temporary file.
templ	The template to use when creating a temp file.
flags	The flags to open the file with. If this is zero, the file is opened with APR_CREATE | APR_READ | APR_WRITE | APR_EXCL | APR_DELONCLOSE
p	The pool to allocate the file out of.

Remarks:

This function generates a unique temporary file name from template. The last six characters of template must be XXXXXX and these are replaced with a string that makes the filename unique. Since it will be modified, template must not be a string constant, but should be declared as a character array.

Find an existing directory suitable as a temporary storage location.

Parameters:

temp_dir	The temp directory.
p	The pool to use for any necessary allocations.

Remarks:

This function uses an algorithm to search for a directory that an an application can use for temporary storage.

Determine if the given pattern is a regular expression.

Parameters:

pattern

The pattern to search for glob characters.

Returns:

non-zero if pattern has any glob characters in it

Find all files that match a specified pattern.

Parameters:

pattern	The pattern to use for finding files.
result	Array to use when storing the results
p	The pool to use.

Returns:

non-zero if pattern has any glob characters in it

Set up an application with normalized argc, argv (and optionally env) in order to deal with platform-specific oddities, such as Win32 services, code pages and signals. This must be the first function called for any APR program.

Parameters:

argc	Pointer to the argc that may be corrected
argv	Pointer to the argv that may be corrected
env	Pointer to the env that may be corrected, may be NULL

Remarks:

See apr_initialize if this is a library consumer of apr. Otherwise, this call is identical to apr_initialize, and must be closed with a call to apr_terminate at the end of program execution.

Parse the options initialized by apr_getopt_init().

Parameters:

os	The apr_opt_t structure returned by apr_getopt_init()
opts	A string of characters that are acceptable options to the program. Characters followed by ":" are required to have an option associated
option_ch	The next option character parsed
option_arg	The argument following the option character:

Returns:

There are four potential status values on exit. They are:

             APR_EOF      --  No more options to parse
             APR_BADCH    --  Found a bad option character
             APR_BADARG   --  No argument followed the option flag
             APR_SUCCESS  --  The next option was found.
 

Parse the options initialized by apr_getopt_init(), accepting long options beginning with "--" in addition to single-character options beginning with "-".

Parameters:

os	The apr_getopt_t structure created by apr_getopt_init()
opts	A pointer to a list of apr_getopt_option_t structures, which can be initialized with { "name", optch, has_args }. has_args is nonzero if the option requires an argument. A structure with an optch value of 0 terminates the list.
option_ch	Receives the value of "optch" from the apr_getopt_option_t structure corresponding to the next option matched.
option_arg	Receives the argument following the option, if any.

Returns:

There are four potential status values on exit. They are:

             APR_EOF      --  No more options to parse
             APR_BADCH    --  Found a bad option character
             APR_BADARG   --  No argument followed the option flag
             APR_SUCCESS  --  The next option was found.
 

When APR_SUCCESS is returned, os->ind gives the index of the first non-option argument. On error, a message will be printed to stdout unless os->err is set to 0. If os->interleave is set to nonzero, options can come after arguments, and os->argv will be permuted to leave non-option arguments at the end (the original argv is unaffected).

Re-open a mutex in a child process.

Parameters:

mutex	The newly re-opened mutex structure.
fname	A file name to use if the mutex mechanism requires one. This argument should always be provided. The mutex code itself will determine if it should be used. This filename should be the same one that was passed to apr_global_mutex_create().
pool	The pool to operate on.

Remarks:

This function must be called to maintain portability, even if the underlying lock mechanism does not require it.

Acquire the lock for the given mutex. If the mutex is already locked, the current thread will be put to sleep until the lock becomes available.

Parameters:

mutex

the mutex on which to acquire the lock.

Attempt to acquire the lock for the given mutex. If the mutex has already been acquired, the call returns immediately with APR_EBUSY. Note: it is important that the APR_STATUS_IS_EBUSY(s) macro be used to determine if the return value was APR_EBUSY, for portability reasons.

Parameters:

mutex

the mutex on which to attempt the lock acquiring.

Release the lock for the given mutex.

Parameters:

mutex

the mutex from which to release the lock.

Destroy the mutex and free the memory associated with the lock.

Parameters:

mutex

the mutex to destroy.

Display the name of the mutex, as it relates to the actual method used for the underlying apr_proc_mutex_t, if any. NULL is returned if there is no underlying apr_proc_mutex_t.

Parameters:

mutex

the name of the mutex

Create a hash table with a custom hash function

Parameters:

pool	The pool to allocate the hash table out of
hash_func	A custom hash function.

Returns:

The hash table just created

Make a copy of a hash table

Parameters:

pool	The pool from which to allocate the new hash table
h	The hash table to clone

Returns:

The hash table just created

Remarks:

Makes a shallow copy

Continue iterating over the entries in a hash table.

Parameters:

hi	The iteration state

Returns:

a pointer to the updated iteration state. NULL if there are no more entries.

Get the current entry's details from the iteration state.

Parameters:

hi	The iteration state
key	Return pointer for the pointer to the key.
klen	Return pointer for the key length.
val	Return pointer for the associated value.

Remarks:

The return pointers should point to a variable that will be set to the corresponding data, or they may be NULL if the data isn't interesting.

Clear any key/value pairs in the hash table.

Parameters:

ht	The hash table

Merge two hash tables into one new hash table. The values of the overlay hash override the values of the base if both have the same key. Both hash tables must use the same hash function.

Parameters:

p	The pool to use for the new hash table
overlay	The table to add to the initial table
base	The table that represents the initial values of the new table

Returns:

A new hash table containing all of the data from the two passed in

Merge two hash tables into one new hash table. If the same key is present in both tables, call the supplied merge function to produce a merged value for the key in the new table. Both hash tables must use the same hash function.

Parameters:

p	The pool to use for the new hash table
h1	The first of the tables to merge
h2	The second of the tables to merge
merger	A callback function to merge values, or NULL to make values from h1 override values from h2 (same semantics as apr_hash_overlay())
data	Client data to pass to the merger function

Returns:

A new hash table containing all of the data from the two passed in

Display a prompt and read in the password from stdin.

Parameters:

prompt	The prompt to display
pwbuf	Buffer to store the password
bufsize	The length of the password buffer.

Remarks:

If the password entered must be truncated to fit in the provided buffer, APR_ENAMETOOLONG will be returned. Note that the bufsize paramater is passed by reference for no reason; its value will never be modified by the apr_password_get() function.

Shutdown either reading, writing, or both sides of a socket.

Parameters:

thesocket	The socket to close
how	How to shutdown the socket. One of: APR_SHUTDOWN_READ no longer allow read requests APR_SHUTDOWN_WRITE no longer allow write requests APR_SHUTDOWN_READWRITE no longer allow read or write requests

See also:

apr_shutdown_how_e

Remarks:

This does not actually close the socket descriptor, it just controls which calls are still valid on the socket.

Close a socket.

Parameters:

thesocket

The socket to close

Bind the socket to its associated port

Parameters:

sock	The socket to bind
sa	The socket address to bind to

Remarks:

This may be where we will find out if there is any other process using the selected port.

Listen to a bound socket for connections.

Parameters:

sock	The socket to listen on
backlog	The number of outstanding connections allowed in the sockets listen queue. If this value is less than zero, the listen queue size is set to zero.

Accept a new connection request

Parameters:

new_sock	A copy of the socket that is connected to the socket that made the connection request. This is the socket which should be used for all future communication.
sock	The socket we are listening on.
connection_pool	The pool for the new socket.

Issue a connection request to a socket either on the same machine or a different one.

Parameters:

sock	The socket we wish to use for our side of the connection
sa	The address of the machine we wish to connect to.

Determine whether the receive part of the socket has been closed by the peer (such that a subsequent call to apr_socket_read would return APR_EOF), if the socket's receive buffer is empty. This function does not block waiting for I/O.

Parameters:

sock	The socket to check
atreadeof	If APR_SUCCESS is returned, *atreadeof is set to non-zero if a subsequent read would return APR_EOF

Returns:

an error is returned if it was not possible to determine the status, in which case *atreadeof is not changed.

Create apr_sockaddr_t from hostname, address family, and port.

Parameters:

sa	The new apr_sockaddr_t.
hostname	The hostname or numeric address string to resolve/parse, or NULL to build an address that corresponds to 0.0.0.0 or ::
family	The address family to use, or APR_UNSPEC if the system should decide.
port	The port number.
flags	Special processing flags: APR_IPV4_ADDR_OK first query for IPv4 addresses; only look for IPv6 addresses if the first query failed; only valid if family is APR_UNSPEC and hostname isn't NULL; mutually exclusive with APR_IPV6_ADDR_OK APR_IPV6_ADDR_OK first query for IPv6 addresses; only look for IPv4 addresses if the first query failed; only valid if family is APR_UNSPEC and hostname isn't NULL and APR_HAVE_IPV6; mutually exclusive with APR_IPV4_ADDR_OK
p	The pool for the apr_sockaddr_t and associated storage.

Look up the host name from an apr_sockaddr_t.

Parameters:

hostname	The hostname.
sa	The apr_sockaddr_t.
flags	Special processing flags.

Parse hostname/IP address with scope id and port.

Any of the following strings are accepted: 8080 (just the port number) www.apache.org (just the hostname) www.apache.org:8080 (hostname and port number) [fe80::1]:80 (IPv6 numeric address string only) [fe80::1eth0] (IPv6 numeric address string and scope id)

Invalid strings: (empty string) [abc] (not valid IPv6 numeric address string) abc:65536 (invalid port number)

Parameters:

addr	The new buffer containing just the hostname. On output, *addr will be NULL if no hostname/IP address was specfied.
scope_id	The new buffer containing just the scope id. On output, *scope_id will be NULL if no scope id was specified.
port	The port number. On output, *port will be 0 if no port was specified. ### FIXME: 0 is a legal port (per RFC 1700). this should ### return something besides zero if the port is missing.
str	The input string to be parsed.
p	The pool from which *addr and *scope_id are allocated.

Remarks:

If scope id shouldn't be allowed, check for scope_id != NULL in addition to checking the return code. If addr/hostname should be required, check for addr == NULL in addition to checking the return code.

Get name of the current machine

Parameters:

buf	A buffer to store the hostname in.
len	The maximum length of the hostname that can be stored in the buffer provided. The suggested length is APRMAXHOSTLEN + 1.
cont	The pool to use.

Remarks:

If the buffer was not large enough, an error will be returned.

Return the data associated with the current socket

Parameters:

data	The user data associated with the socket.
key	The key to associate with the user data.
sock	The currently open socket.

Set the data associated with the current socket.

Parameters:

sock	The currently open socket.
data	The user data to associate with the socket.
key	The key to associate with the data.
cleanup	The cleanup to call when the socket is destroyed.

Send data over a network.

Parameters:

sock	The socket to send the data over.
buf	The buffer which contains the data to be sent.
len	On entry, the number of bytes to send; on exit, the number of bytes sent.

Remarks:

 This functions acts like a blocking write by default.  To change 
 this behavior, use apr_socket_timeout_set() or the APR_SO_NONBLOCK
 socket option.

It is possible for both bytes to be sent and an error to be returned.

 APR_EINTR is never returned.
 

Send multiple packets of data over a network.

Parameters:

sock	The socket to send the data over.
vec	The array of iovec structs containing the data to send
nvec	The number of iovec structs in the array
len	Receives the number of bytes actually written

Remarks:

 This functions acts like a blocking write by default.  To change 
 this behavior, use apr_socket_timeout_set() or the APR_SO_NONBLOCK
 socket option.
 The number of bytes actually sent is stored in argument 3.

It is possible for both bytes to be sent and an error to be returned.

 APR_EINTR is never returned.
 

Parameters:

sock	The socket to send from
where	The apr_sockaddr_t describing where to send the data
flags	The flags to use
buf	The data to send
len	The length of the data to send

Read data from a socket. On success, the address of the peer from which the data was sent is copied into the from parameter, and the len parameter is updated to give the number of bytes written to buf.

Parameters:

from	Updated with the address from which the data was received
sock	The socket to use
flags	The flags to use
buf	The buffer to use
len	The length of the available buffer

Read data from a network.

Parameters:

sock	The socket to read the data from.
buf	The buffer to store the data in.
len	On entry, the number of bytes to receive; on exit, the number of bytes received.

Remarks:

 This functions acts like a blocking read by default.  To change 
 this behavior, use apr_socket_timeout_set() or the APR_SO_NONBLOCK
 socket option.
 The number of bytes actually received is stored in argument 3.

It is possible for both bytes to be received and an APR_EOF or other error to be returned.

 APR_EINTR is never returned.
 

Setup socket options for the specified socket

Parameters:

sock	The socket to set up.
opt	The option we would like to configure. One of: APR_SO_DEBUG -- turn on debugging information APR_SO_KEEPALIVE -- keep connections active APR_SO_LINGER -- lingers on close if data is present APR_SO_NONBLOCK -- Turns blocking on/off for socket When this option is enabled, use the APR_STATUS_IS_EAGAIN() macro to see if a send or receive function could not transfer data without blocking. APR_SO_REUSEADDR -- The rules used in validating addresses supplied to bind should allow reuse of local addresses. APR_SO_SNDBUF -- Set the SendBufferSize APR_SO_RCVBUF -- Set the ReceiveBufferSize
on	Value for the option.

Setup socket timeout for the specified socket

Parameters:

sock	The socket to set up.
t	Value for the timeout. t > 0 -- read and write calls return APR_TIMEUP if specified time elapsess with no data read or written t == 0 -- read and write calls never block t < 0 -- read and write calls block

Query socket options for the specified socket

Parameters:

sock	The socket to query
opt	The option we would like to query. One of: APR_SO_DEBUG -- turn on debugging information APR_SO_KEEPALIVE -- keep connections active APR_SO_LINGER -- lingers on close if data is present APR_SO_NONBLOCK -- Turns blocking on/off for socket APR_SO_REUSEADDR -- The rules used in validating addresses supplied to bind should allow reuse of local addresses. APR_SO_SNDBUF -- Set the SendBufferSize APR_SO_RCVBUF -- Set the ReceiveBufferSize APR_SO_DISCONNECTED -- Query the disconnected state of the socket. (Currently only used on Windows)
on	Socket option returned on the call.

Query socket timeout for the specified socket

Parameters:

sock	The socket to query
t	Socket timeout returned from the query.

Query the specified socket if at the OOB/Urgent data mark

Parameters:

sock	The socket to query
atmark	Is set to true if socket is at the OOB/urgent mark, otherwise is set to false.

Return an address associated with a socket; either the address to which the socket is bound locally or the the address of the peer to which the socket is connected.

Parameters:

sa	The returned apr_sockaddr_t.
which	Whether to retrieve the local or remote address
sock	The socket to use

Return the IP address (in numeric address string format) in an APR socket address. APR will allocate storage for the IP address string from the pool of the apr_sockaddr_t.

Parameters:

addr	The IP address.
sockaddr	The socket address to reference.

Write the IP address (in numeric address string format) of the APR socket address sockaddr into the buffer buf (of size buflen).

Parameters:

sockaddr

The socket address to reference.

See if the IP addresses in two APR socket addresses are equivalent. Appropriate logic is present for comparing IPv4-mapped IPv6 addresses with IPv4 addresses.

Parameters:

addr1	One of the APR socket addresses.
addr2	The other APR socket address.

Remarks:

The return value will be non-zero if the addresses are equivalent.

Return the type of the socket.

Parameters:

sock	The socket to query.
type	The returned type (e.g., SOCK_STREAM).

Given an apr_sockaddr_t and a service name, set the port for the service

Parameters:

sockaddr	The apr_sockaddr_t that will have its port set
servname	The name of the service you wish to use

Build an ip-subnet representation from an IP address and optional netmask or number-of-bits.

Parameters:

ipsub	The new ip-subnet representation
ipstr	The input IP address string
mask_or_numbits	The input netmask or number-of-bits string, or NULL
p	The pool to allocate from

Test the IP address in an apr_sockaddr_t against a pre-built ip-subnet representation.

Parameters:

ipsub	The ip-subnet representation
sa	The socket address to test

Returns:

non-zero if the socket address is within the subnet, 0 otherwise

Return the protocol of the socket.

Parameters:

sock	The socket to query.
protocol	The returned protocol (e.g., APR_PROTO_TCP).

Join a Multicast Group

Parameters:

sock	The socket to join a multicast group
join	The address of the multicast group to join
iface	Address of the interface to use. If NULL is passed, the default multicast interface will be used. (OS Dependent)
source	Source Address to accept transmissions from (non-NULL implies Source-Specific Multicast)

Leave a Multicast Group. All arguments must be the same as apr_mcast_join.

Parameters:

sock	The socket to leave a multicast group
addr	The address of the multicast group to leave
iface	Address of the interface to use. If NULL is passed, the default multicast interface will be used. (OS Dependent)
source	Source Address to accept transmissions from (non-NULL implies Source-Specific Multicast)

Set the Multicast Time to Live (ttl) for a multicast transmission.

Parameters:

sock	The socket to set the multicast ttl
ttl	Time to live to Assign. 0-255, default=1

Remarks:

If the TTL is 0, packets will only be seen by sockets on the local machine, and only when multicast loopback is enabled.

Toggle IP Multicast Loopback

Parameters:

sock	The socket to set multicast loopback
opt	0=disable, 1=enable

Set the Interface to be used for outgoing Multicast Transmissions.

Parameters:

sock	The socket to set the multicast interface on
iface	Address of the interface to use for Multicast

Set up a pollset object

Parameters:

pollset	The pointer in which to return the newly created object
size	The maximum number of descriptors that this pollset can hold
p	The pool from which to allocate the pollset
flags	Optional flags to modify the operation of the pollset.
method	Poll method to use. See apr_pollset_method_e. If this method cannot be used, the default method will be used unless the APR_POLLSET_NODEFAULT flag has been specified.

Remarks:

If flags contains APR_POLLSET_THREADSAFE, then a pollset is created on which it is safe to make concurrent calls to apr_pollset_add(), apr_pollset_remove() and apr_pollset_poll() from separate threads. This feature is only supported on some platforms; the apr_pollset_create_ex() call will fail with APR_ENOTIMPL on platforms where it is not supported.

If flags contains APR_POLLSET_WAKEABLE, then a pollset is created with additional internal pipe object used for the apr_pollset_wakeup() call. The actual size of pollset is in that case size + 1. This feature is only supported on some platforms; the apr_pollset_create_ex() call will fail with APR_ENOTIMPL on platforms where it is not supported.

If flags contains APR_POLLSET_NOCOPY, then the apr_pollfd_t structures passed to apr_pollset_add() are not copied and must have a lifetime at least as long as the pollset.

Some poll methods (including APR_POLLSET_KQUEUE, APR_POLLSET_PORT, and APR_POLLSET_EPOLL) do not have a fixed limit on the size of the pollset. For these methods, the size parameter controls the maximum number of descriptors that will be returned by a single call to apr_pollset_poll().

Destroy a pollset object

Parameters:

pollset

The pollset to destroy

Add a socket or file descriptor to a pollset

Parameters:

pollset	The pollset to which to add the descriptor
descriptor	The descriptor to add

Remarks:

If you set client_data in the descriptor, that value will be returned in the client_data field whenever this descriptor is signalled in apr_pollset_poll().

If the pollset has been created with APR_POLLSET_THREADSAFE and thread T1 is blocked in a call to apr_pollset_poll() for this same pollset that is being modified via apr_pollset_add() in thread T2, the currently executing apr_pollset_poll() call in T1 will either: (1) automatically include the newly added descriptor in the set of descriptors it is watching or (2) return immediately with APR_EINTR. Option (1) is recommended, but option (2) is allowed for implementations where option (1) is impossible or impractical.

If the pollset has been created with APR_POLLSET_NOCOPY, the apr_pollfd_t structure referenced by descriptor will not be copied and must have a lifetime at least as long as the pollset.

Do not add the same socket or file descriptor to the same pollset multiple times, even if the requested events differ for the different calls to apr_pollset_add(). If the events of interest for a descriptor change, you must first remove the descriptor from the pollset with apr_pollset_remove(), then add it again specifying all requested events.

Remove a descriptor from a pollset

Parameters:

pollset	The pollset from which to remove the descriptor
descriptor	The descriptor to remove

Remarks:

If the pollset has been created with APR_POLLSET_THREADSAFE and thread T1 is blocked in a call to apr_pollset_poll() for this same pollset that is being modified via apr_pollset_remove() in thread T2, the currently executing apr_pollset_poll() call in T1 will either: (1) automatically exclude the newly added descriptor in the set of descriptors it is watching or (2) return immediately with APR_EINTR. Option (1) is recommended, but option (2) is allowed for implementations where option (1) is impossible or impractical.

apr_pollset_remove() cannot be used to remove a subset of requested events for a descriptor. The reqevents field in the apr_pollfd_t parameter must contain the same value when removing as when adding.

Block for activity on the descriptor(s) in a pollset

Parameters:

pollset	The pollset to use
timeout	The amount of time in microseconds to wait. This is a maximum, not a minimum. If a descriptor is signalled, the function will return before this time. If timeout is negative, the function will block until a descriptor is signalled or until apr_pollset_wakeup() has been called.
num	Number of signalled descriptors (output parameter)
descriptors	Array of signalled descriptors (output parameter)

Remarks:

APR_EINTR will be returned if the pollset has been created with APR_POLLSET_WAKEABLE, apr_pollset_wakeup() has been called while waiting for activity, and there were no signalled descriptors at the time of the wakeup call.

Multiple signalled conditions for the same descriptor may be reported in one or more returned apr_pollfd_t structures, depending on the implementation.

Bug:

With versions 1.4.2 and prior on Windows, a call with no descriptors and timeout will return immediately with the wrong error code.

Interrupt the blocked apr_pollset_poll() call.

Parameters:

pollset

The pollset to use

Remarks:

If the pollset was not created with APR_POLLSET_WAKEABLE the return value is APR_EINIT.

Poll the descriptors in the poll structure

Parameters:

aprset	The poll structure we will be using.
numsock	The number of descriptors we are polling
nsds	The number of descriptors signalled (output parameter)
timeout	The amount of time in microseconds to wait. This is a maximum, not a minimum. If a descriptor is signalled, the function will return before this time. If timeout is negative, the function will block until a descriptor is signalled or until apr_pollset_wakeup() has been called.

Remarks:

The number of descriptors signalled is returned in the third argument. This is a blocking call, and it will not return until either a descriptor has been signalled or the timeout has expired.

The rtnevents field in the apr_pollfd_t array will only be filled- in if the return value is APR_SUCCESS.

Bug:

With versions 1.4.2 and prior on Windows, a call with no descriptors and timeout will return immediately with the wrong error code.

Return a printable representation of the default pollset method (APR_POLLSET_DEFAULT).

Set up a pollcb object

Parameters:

pollcb	The pointer in which to return the newly created object
size	The maximum number of descriptors that a single _poll can return.
p	The pool from which to allocate the pollcb
flags	Optional flags to modify the operation of the pollcb.

Remarks:

Pollcb is only supported on some platforms; the apr_pollcb_create() call will fail with APR_ENOTIMPL on platforms where it is not supported.

Set up a pollcb object

Parameters:

pollcb	The pointer in which to return the newly created object
size	The maximum number of descriptors that a single _poll can return.
p	The pool from which to allocate the pollcb
flags	Optional flags to modify the operation of the pollcb.
method	Poll method to use. See apr_pollset_method_e. If this method cannot be used, the default method will be used unless the APR_POLLSET_NODEFAULT flag has been specified.

Remarks:

Pollcb is only supported on some platforms; the apr_pollcb_create_ex() call will fail with APR_ENOTIMPL on platforms where it is not supported.

Add a socket or file descriptor to a pollcb

Parameters:

pollcb	The pollcb to which to add the descriptor
descriptor	The descriptor to add

Remarks:

If you set client_data in the descriptor, that value will be returned in the client_data field whenever this descriptor is signalled in apr_pollcb_poll().

Unlike the apr_pollset API, the descriptor is not copied, and users must retain the memory used by descriptor, as the same pointer will be returned to them from apr_pollcb_poll.

Do not add the same socket or file descriptor to the same pollcb multiple times, even if the requested events differ for the different calls to apr_pollcb_add(). If the events of interest for a descriptor change, you must first remove the descriptor from the pollcb with apr_pollcb_remove(), then add it again specifying all requested events.

Remove a descriptor from a pollcb

Parameters:

pollcb	The pollcb from which to remove the descriptor
descriptor	The descriptor to remove

Remarks:

apr_pollcb_remove() cannot be used to remove a subset of requested events for a descriptor. The reqevents field in the apr_pollfd_t parameter must contain the same value when removing as when adding.

Block for activity on the descriptor(s) in a pollcb

Parameters:

pollcb	The pollcb to use
timeout	The amount of time in microseconds to wait. This is a maximum, not a minimum. If a descriptor is signalled, the function will return before this time. If timeout is negative, the function will block until a descriptor is signalled.
func	Callback function to call for each active descriptor.
baton	Opaque baton passed to the callback function.

Remarks:

Multiple signalled conditions for the same descriptor may be reported in one or more calls to the callback function, depending on the implementation.

Bug:

With versions 1.4.2 and prior on Windows, a call with no descriptors and timeout will return immediately with the wrong error code.

Create a new pool.

Parameters:

newpool	The pool we have just created.
parent	The parent pool. If this is NULL, the new pool is a root pool. If it is non-NULL, the new pool will inherit all of its parent pool's attributes, except the apr_pool_t will be a sub-pool.
abort_fn	A function to use if the pool cannot allocate more memory.
allocator	The allocator to use with the new pool. If NULL the allocator of the parent pool will be used.

Remarks:

This function is thread-safe, in the sense that multiple threads can safely create subpools of the same parent pool concurrently. Similarly, a subpool can be created by one thread at the same time that another thread accesses the parent pool.

Create a new pool.

Deprecated:

See also:

apr_pool_create_unmanaged_ex.

Create a new unmanaged pool.

Parameters:

newpool	The pool we have just created.
abort_fn	A function to use if the pool cannot allocate more memory.
allocator	The allocator to use with the new pool. If NULL a new allocator will be crated with newpool as owner.

Remarks:

An unmanaged pool is a special pool without a parent; it will NOT be destroyed upon apr_terminate. It must be explicitly destroyed by calling apr_pool_destroy, to prevent memory leaks. Use of this function is discouraged, think twice about whether you really really need it.

Debug version of apr_pool_create_ex.

Parameters:

newpool

See also:

apr_pool_create.

Parameters:

parent

See also:

apr_pool_create.

Parameters:

abort_fn

See also:

apr_pool_create.

Parameters:

allocator

See also:

apr_pool_create.

Parameters:

file_line

Where the function is called from. This is usually APR_POOL__FILE_LINE__.

Remarks:

Only available when APR_POOL_DEBUG is defined. Call this directly if you have you apr_pool_create_ex calls in a wrapper function and wish to override the file_line argument to reflect the caller of your wrapper function. If you do not have apr_pool_create_ex in a wrapper, trust the macro and don't call apr_pool_create_ex_debug directly.

Debug version of apr_pool_create_core_ex.

Deprecated:

See also:

apr_pool_create_unmanaged_ex_debug.

Debug version of apr_pool_create_unmanaged_ex.

Parameters:

newpool

See also:

apr_pool_create_unmanaged.

Parameters:

abort_fn

See also:

apr_pool_create_unmanaged.

Parameters:

allocator

See also:

apr_pool_create_unmanaged.

Parameters:

file_line

Where the function is called from. This is usually APR_POOL__FILE_LINE__.

Remarks:

Only available when APR_POOL_DEBUG is defined. Call this directly if you have you apr_pool_create_unmanaged_ex calls in a wrapper function and wish to override the file_line argument to reflect the caller of your wrapper function. If you do not have apr_pool_create_core_ex in a wrapper, trust the macro and don't call apr_pool_create_core_ex_debug directly.

Clear all memory in the pool and run all the cleanups. This also destroys all subpools.

Parameters:

p	The pool to clear

Remarks:

This does not actually free the memory, it just allows the pool to re-use this memory for the next allocation.

See also:

apr_pool_destroy()

Debug version of apr_pool_clear.

Parameters:

p	See: apr_pool_clear.
file_line	Where the function is called from. This is usually APR_POOL__FILE_LINE__.

Remarks:

Only available when APR_POOL_DEBUG is defined. Call this directly if you have you apr_pool_clear calls in a wrapper function and wish to override the file_line argument to reflect the caller of your wrapper function. If you do not have apr_pool_clear in a wrapper, trust the macro and don't call apr_pool_destroy_clear directly.

Destroy the pool. This takes similar action as apr_pool_clear() and then frees all the memory.

Parameters:

p	The pool to destroy

Remarks:

This will actually free the memory

Debug version of apr_pool_destroy.

Parameters:

p	See: apr_pool_destroy.
file_line	Where the function is called from. This is usually APR_POOL__FILE_LINE__.

Remarks:

Only available when APR_POOL_DEBUG is defined. Call this directly if you have you apr_pool_destroy calls in a wrapper function and wish to override the file_line argument to reflect the caller of your wrapper function. If you do not have apr_pool_destroy in a wrapper, trust the macro and don't call apr_pool_destroy_debug directly.

Debug version of apr_palloc

Parameters:

p	See: apr_palloc
size	See: apr_palloc
file_line	Where the function is called from. This is usually APR_POOL__FILE_LINE__.

Returns:

See: apr_palloc

Debug version of apr_pcalloc

Parameters:

p	See: apr_pcalloc
size	See: apr_pcalloc
file_line	Where the function is called from. This is usually APR_POOL__FILE_LINE__.

Returns:

See: apr_pcalloc

Set the function to be called when an allocation failure occurs.

Remarks:

If the program wants APR to exit on a memory allocation error, then this function can be called to set the callback to use (for performing cleanup and then exiting). If this function is not called, then APR will return an error and expect the calling program to deal with the error accordingly.

Determine if pool a is an ancestor of pool b.

Parameters:

a	The pool to search
b	The pool to search for

Returns:

True if a is an ancestor of b, NULL is considered an ancestor of all pools.

Remarks:

if compiled with APR_POOL_DEBUG, this function will also return true if A is a pool which has been guaranteed by the caller (using apr_pool_join) to have a lifetime at least as long as some ancestor of pool B.

Tag a pool (give it a name)

Parameters:

pool	The pool to tag
tag	The tag

Set the data associated with the current pool

Parameters:

data	The user data associated with the pool.
key	The key to use for association
cleanup	The cleanup program to use to cleanup the data (NULL if none)
pool	The current pool

Warning:

The data to be attached to the pool should have a life span at least as long as the pool it is being attached to.

Users of APR must take EXTREME care when choosing a key to use for their data. It is possible to accidentally overwrite data by choosing a key that another part of the program is using. Therefore it is advised that steps are taken to ensure that unique keys are used for all of the userdata objects in a particular pool (the same key in two different pools or a pool and one of its subpools is okay) at all times. Careful namespace prefixing of key names is a typical way to help ensure this uniqueness.

Set the data associated with the current pool

Parameters:

data	The user data associated with the pool.
key	The key to use for association
cleanup	The cleanup program to use to cleanup the data (NULL if none)
pool	The current pool

Note:

same as apr_pool_userdata_set(), except that this version doesn't make a copy of the key (this function is useful, for example, when the key is a string literal)

Warning:

This should NOT be used if the key could change addresses by any means between the apr_pool_userdata_setn() call and a subsequent apr_pool_userdata_get() on that key, such as if a static string is used as a userdata key in a DSO and the DSO could be unloaded and reloaded between the _setn() and the _get(). You MUST use apr_pool_userdata_set() in such cases.

More generally, the key and the data to be attached to the pool should have a life span at least as long as the pool itself.

Return the data associated with the current pool.

Parameters:

data	The user data associated with the pool.
key	The key for the data to retrieve
pool	The current pool.

Register a function to be called when a pool is cleared or destroyed

Parameters:

p	The pool register the cleanup with
data	The data to pass to the cleanup function.
plain_cleanup	The function to call when the pool is cleared or destroyed
child_cleanup	The function to call when a child process is about to exec - this function is called in the child, obviously!

Remove a previously registered cleanup function.

The cleanup most recently registered with p having the same values of data and cleanup will be removed.

Parameters:

p	The pool to remove the cleanup from
data	The data of the registered cleanup
cleanup	The function to remove from cleanup

Remarks:

For some strange reason only the plain_cleanup is handled by this function

Replace the child cleanup function of a previously registered cleanup.

The cleanup most recently registered with p having the same values of data and plain_cleanup will have the registered child cleanup function replaced with child_cleanup.

Parameters:

p	The pool of the registered cleanup
data	The data of the registered cleanup
plain_cleanup	The plain cleanup function of the registered cleanup
child_cleanup	The function to register as the child cleanup

Run all registered child cleanups, in preparation for an exec() call in a forked child -- close files, etc., but *don't* flush I/O buffers, *don't* wait for subprocesses, and *don't* free any memory.

convert the file from apr type to os specific type.

Parameters:

thefile	The os specific file we are converting to
file	The apr file to convert.

Remarks:

On Unix, it is only possible to get a file descriptor from an apr file type.

convert the dir from apr type to os specific type.

Parameters:

thedir	The os specific dir we are converting to
dir	The apr dir to convert.

Convert the socket from an apr type to an OS specific socket

Parameters:

thesock	The socket to convert.
sock	The os specific equivalent of the apr socket..

Convert the proc mutex from os specific type to apr type

Parameters:

ospmutex	The os specific proc mutex we are converting to.
pmutex	The apr proc mutex to convert.

Get the exploded time in the platforms native format.

Parameters:

ostime	the native time format
aprtime	the time to convert

Get the imploded time in the platforms native format.

Parameters:

ostime	the native time format
aprtime	the time to convert

convert the shm from apr type to os specific type.

Parameters:

osshm	The os specific shm representation
shm	The apr shm to convert.

convert the file from os specific type to apr type.

Parameters:

file	The apr file we are converting to.
thefile	The os specific file to convert
flags	The flags that were used to open this file.
cont	The pool to use if it is needed.

Remarks:

On Unix, it is only possible to put a file descriptor into an apr file type.

convert the file from os specific type to apr type.

Parameters:

file	The apr file we are converting to.
thefile	The os specific pipe to convert
cont	The pool to use if it is needed.

Remarks:

On Unix, it is only possible to put a file descriptor into an apr file type.

convert the file from os specific type to apr type.

Parameters:

file	The apr file we are converting to.
thefile	The os specific pipe to convert
register_cleanup	A cleanup will be registered on the apr_file_t to issue apr_file_close().
cont	The pool to use if it is needed.

Remarks:

On Unix, it is only possible to put a file descriptor into an apr file type.

convert the dir from os specific type to apr type.

Parameters:

dir	The apr dir we are converting to.
thedir	The os specific dir to convert
cont	The pool to use when creating to apr directory.

Convert a socket from the os specific type to the apr type

Parameters:

sock	The pool to use.
thesock	The socket to convert to.
cont	The socket we are converting to an apr type.

Remarks:

If it is a true socket, it is best to call apr_os_sock_make() and provide APR with more information about the socket.

Create a socket from an existing descriptor and local and remote socket addresses.

Parameters:

apr_sock	The new socket that has been set up
os_sock_info	The os representation of the socket handle and other characteristics of the socket
cont	The pool to use

Remarks:

If you only know the descriptor/handle or if it isn't really a true socket, use apr_os_sock_put() instead.

Convert the proc mutex from os specific type to apr type

Parameters:

pmutex	The apr proc mutex we are converting to.
ospmutex	The os specific proc mutex to convert.
cont	The pool to use if it is needed.

Put the imploded time in the APR format.

Parameters:

aprtime	the APR time format
ostime	the time to convert
cont	the pool to use if necessary

Put the exploded time in the APR format.

Parameters:

aprtime	the APR time format
ostime	the time to convert
cont	the pool to use if necessary

convert the shared memory from os specific type to apr type.

Parameters:

shm	The apr shm representation of osshm
osshm	The os specific shm identity
cont	The pool to use if it is needed.

Remarks:

On fork()ed architectures, this is typically nothing more than the memory block mapped. On non-fork architectures, this is typically some internal handle to pass the mapping from process to process.

Get the name of the current locale character set.

Parameters:

pool	the pool to allocate the name from, if needed

Remarks:

Defers to apr_os_default_encoding if the current locale's data can't be retrieved on this system.

Re-open a mutex in a child process.

Parameters:

mutex	The newly re-opened mutex structure.
fname	A file name to use if the mutex mechanism requires one. This argument should always be provided. The mutex code itself will determine if it should be used. This filename should be the same one that was passed to apr_proc_mutex_create().
pool	The pool to operate on.

Remarks:

This function must be called to maintain portability, even if the underlying lock mechanism does not require it.

Destroy the mutex and free the memory associated with the lock.

Parameters:

mutex

the mutex to destroy.

Note:

This function is generally used to kill a cleanup on an already created mutex

Display the name of the mutex, as it relates to the actual method used. This matches the valid options for Apache's AcceptMutex directive

Parameters:

mutex

the name of the mutex

Display the name of the default mutex: APR_LOCK_DEFAULT

Mix the randomness pools.

Parameters:

g	The PRNG state
entropy_	Entropy buffer
bytes	Length of entropy_ in bytes

Generate cryptographically secure random bytes.

Parameters:

g	The RNG state
random	Buffer to fill with random bytes
bytes	Length of buffer in bytes

Ensures that E bits of conditional entropy are mixed into the PRNG before any further randomness is extracted.

Parameters:

g	The RNG state

Return APR_SUCCESS if the cryptographic PRNG has been seeded with enough data, APR_ENOTENOUGHENTROPY otherwise.

Parameters:

r	The RNG state

Return APR_SUCCESS if the PRNG has been seeded with enough data, APR_ENOTENOUGHENTROPY otherwise.

Parameters:

r	The PRNG state

Mix the randomness pools after forking.

Parameters:

proc	The resulting process handle from apr_proc_fork()

Remarks:

Call this in the child after forking to mix the randomness pools. Note that its generally a bad idea to fork a process with a real PRNG in it - better to have the PRNG externally and get the randomness from there. However, if you really must do it, then you should supply all your entropy to all the PRNGs - don't worry, they won't produce the same output.

Note that apr_proc_fork() calls this for you, so only weird applications need ever call it themselves.

Remove named resource associated with a shared memory segment, preventing attachments to the resource, but not destroying it.

Parameters:

filename	The filename associated with shared-memory segment which needs to be removed
pool	The pool used for file operations

Remarks:

This function is only supported on platforms which support name-based shared memory segments, and will return APR_ENOTIMPL on platforms without such support. Removing the file while the shm is in use is not entirely portable, caller may use this to enhance obscurity of the resource, but be prepared for the the call to fail, and for concurrent attempts to create a resource of the same name to also fail. The pool cleanup of apr_shm_create (apr_shm_destroy) also removes the named resource.

Destroy a shared memory segment and associated memory.

Parameters:

m	The shared memory segment structure to destroy.

Attach to a shared memory segment that was created by another process.

Parameters:

m	The shared memory structure to create.
filename	The file used to create the original segment. (This MUST match the original filename.)
pool	the pool from which to allocate the shared memory structure for this process.

Detach from a shared memory segment without destroying it.

Parameters:

m	The shared memory structure representing the segment to detach from.

Enable the delivery of a particular signal

Parameters:

signum

The signal number

Returns:

status

Do a natural order comparison of two strings ignoring the case of the strings.

Parameters:

a	The first string to compare
b	The second string to compare

Returns:

Either <0, 0, or >0. If the first string is less than the second this returns <0, if they are equivalent it returns 0, and if the first string is greater than second string it retuns >0.

Create a null-terminated string by making a copy of a sequence of characters and appending a null byte

Parameters:

p	The pool to allocate out of
s	The block of characters to duplicate
n	The number of characters to duplicate

Returns:

The new string

Remarks:

This is a faster alternative to apr_pstrndup, for use when you know that the string being duplicated really has 'n' or more characters. If the string might contain fewer characters, use apr_pstrndup.

Duplicate at most n characters of a string into memory allocated out of a pool; the new string will be NUL-terminated

Parameters:

p	The pool to allocate out of
s	The string to duplicate
n	The maximum number of characters to duplicate

Returns:

The new string

Remarks:

The amount of memory allocated from the pool is the length of the returned string including the NUL terminator

Concatenate multiple strings specified in a writev-style vector

Parameters:

p	The pool from which to allocate
vec	The strings to concatenate
nvec	The number of strings to concatenate
nbytes	(output) strlen of new string (pass in NULL to omit)

Returns:

The new string

printf-style style printing routine. The data is output to a string allocated from a pool

Parameters:

p	The pool to allocate out of
fmt	The format of the string
ap	The arguments to use while printing the data

Returns:

The new string

Copy up to dst_size characters from src to dst; does not copy past a NUL terminator in src, but always terminates dst with a NUL regardless.

Parameters:

dst	The destination string
src	The source string
dst_size	The space available in dst; dst always receives NUL termination, so if src is longer than dst_size, the actual number of characters copied is dst_size - 1.

Returns:

Pointer to the NUL terminator of the destination string, dst

Remarks:

 Note the differences between this function and strncpy():
  1) strncpy() doesn't always NUL terminate; apr_cpystrn() does.
  2) strncpy() pads the destination string with NULs, which is often 
     unnecessary; apr_cpystrn() does not.
  3) strncpy() returns a pointer to the beginning of the dst string;
     apr_cpystrn() returns a pointer to the NUL terminator of dst, 
     to allow a check for truncation.
 

Remove all whitespace from a string

Parameters:

dest	The destination string. It is okay to modify the string in place. Namely dest == src
src	The string to rid the spaces from.

Returns:

A pointer to the destination string's null terminator.

Convert the arguments to a program from one string to an array of strings terminated by a NULL pointer

Parameters:

arg_str	The arguments to convert
argv_out	Output location. This is a pointer to an array of strings.
token_context	Pool to use.

Split a string into separate null-terminated tokens. The tokens are delimited in the string by one or more characters from the sep argument.

Parameters:

str	The string to separate; this should be specified on the first call to apr_strtok() for a given string, and NULL on subsequent calls.
sep	The set of delimiters
last	Internal state saved by apr_strtok() between calls.

Returns:

The next token from the string

vsnprintf routine based on apr_vformatter. This means it understands the same extensions.

Parameters:

buf	The buffer to write to
len	The size of the buffer
format	The format string
ap	The arguments to use to fill out the format string.

create a string representation of an int, allocated from a pool

Parameters:

p	The pool from which to allocate
n	The number to format

Returns:

The string representation of the number

create a string representation of a long, allocated from a pool

Parameters:

p	The pool from which to allocate
n	The number to format

Returns:

The string representation of the number

create a string representation of an apr_off_t, allocated from a pool

Parameters:

p	The pool from which to allocate
n	The number to format

Returns:

The string representation of the number

Convert a numeric string into an apr_off_t numeric value.

Parameters:

offset	The value of the parsed string.
buf	The string to parse. It may contain optional whitespace, followed by an optional '+' (positive, default) or '-' (negative) character, followed by an optional '0x' prefix if base is 0 or 16, followed by numeric digits appropriate for base.
end	A pointer to the end of the valid character in buf. If not NULL, it is set to the first invalid character in buf.
base	A numeric base in the range between 2 and 36 inclusive, or 0. If base is zero, buf will be treated as base ten unless its digits are prefixed with '0x', in which case it will be treated as base 16.

Bug:

*end breaks type safety; where *buf is const, *end needs to be declared as const in APR 2.0

parse a base-10 numeric string into a 64-bit numeric value. Equivalent to apr_strtoi64(buf, (char**)NULL, 10).

Parameters:

buf	The string to parse

Returns:

The numeric value of the string. On overflow, errno is set to ERANGE. On success, errno is set to 0.

Format a binary size (magnitiudes are 2^10 rather than 10^3) from an apr_off_t, as bytes, K, M, T, etc, to a four character compacted human readable string.

Parameters:

size	The size to format
buf	The 5 byte text buffer (counting the trailing null)

Returns:

The buf passed to apr_strfsize()

Remarks:

All negative sizes report ' - ', apr_strfsize only formats positive values.

Determine if the array is empty (either NULL or having no elements).

Parameters:

a	The array to check

Returns:

True if empty, False otherwise

Remove an element from an array (as a first-in, last-out stack).

Parameters:

arr	The array to remove an element from.

Returns:

Location of the element in the array.

Remarks:

If there are no elements in the array, NULL is returned.

Concatenate two arrays together.

Parameters:

dst	The destination array, and the one to go first in the combined array
src	The source array to add to the destination array

Copy the entire array.

Parameters:

p	The pool to allocate the copy of the array out of
arr	The array to copy

Returns:

An exact copy of the array passed in

Remarks:

The alternate apr_array_copy_hdr copies only the header, and arranges for the elements to be copied if (and only if) the code subsequently does a push or arraycat.

Copy the headers of the array, and arrange for the elements to be copied if and only if the code subsequently does a push or arraycat.

Parameters:

p	The pool to allocate the copy of the array out of
arr	The array to copy

Returns:

An exact copy of the array passed in

Remarks:

The alternate apr_array_copy copies the *entire* array.

Append one array to the end of another, creating a new array in the process.

Parameters:

p	The pool to allocate the new array out of
first	The array to put first in the new array.
second	The array to put second in the new array.

Returns:

A new array containing the data from the two arrays passed in.

Create a new table and copy another table into it.

Parameters:

p	The pool to allocate the new table out of
t	The table to copy

Returns:

A copy of the table passed in

Warning:

The table keys and respective values are not copied

Create a new table whose contents are deep copied from the given table. A deep copy operation copies all fields, and makes copies of dynamically allocated memory pointed to by the fields.

Parameters:

p	The pool to allocate the new table out of
t	The table to clone

Returns:

A deep copy of the table passed in

Delete all of the elements from a table.

Parameters:

t	The table to clear

Add a key/value pair to a table. If another element already exists with the same key, this will overwrite the old data.

Parameters:

t	The table to add the data to.
key	The key to use (case does not matter)
val	The value to add

Remarks:

When adding data, this function makes a copy of both the key and the value.

Add a key/value pair to a table. If another element already exists with the same key, this will overwrite the old data.

Parameters:

t	The table to add the data to.
key	The key to use (case does not matter)
val	The value to add

Warning:

When adding data, this function does not make a copy of the key or the value, so care should be taken to ensure that the values will not change after they have been added..

Remove data from the table.

Parameters:

t	The table to remove data from
key	The key of the data being removed (case does not matter)

Add data to a table by merging the value with data that has already been stored. The merging is done by concatenating the two values, separated by the string ", ".

Parameters:

t	The table to search for the data
key	The key to merge data for (case does not matter)
val	The data to add

Remarks:

If the key is not found, then this function acts like apr_table_add

Add data to a table by merging the value with data that has already been stored. The merging is done by concatenating the two values, separated by the string ", ".

Parameters:

t	The table to search for the data
key	The key to merge data for (case does not matter)
val	The data to add

Remarks:

If the key is not found, then this function acts like apr_table_addn

Add data to a table, regardless of whether there is another element with the same key.

Parameters:

t	The table to add to
key	The key to use
val	The value to add.

Remarks:

When adding data, this function makes a copy of both the key and the value.

Add data to a table, regardless of whether there is another element with the same key.

Parameters:

t	The table to add to
key	The key to use
val	The value to add.

Remarks:

When adding data, this function does not make a copy of the key or the value, so care should be taken to ensure that the values will not change after they have been added.

Merge two tables into one new table.

Parameters:

p	The pool to use for the new table
overlay	The first table to put in the new table
base	The table to add at the end of the new table

Returns:

A new table containing all of the data from the two passed in

Iterate over a table running the provided function once for every element in the table. The

Parameters:

vp	varargs parameter must be a list of zero or more (char *) keys followed by a NULL pointer. If zero keys are given, the
comp	function will be invoked for every element in the table. Otherwise, the function is invoked only for those elements matching the keys specified.

If an invocation of the

Parameters:

comp	function returns zero, iteration will continue using the next specified key, if any.
comp	The function to run
rec	The data to pass as the first argument to the function
t	The table to iterate over
vp	List of zero or more (char *) keys followed by NULL

Returns:

FALSE if one of the comp() iterations returned zero; TRUE if all iterations returned non-zero

See also:

apr_table_do_callback_fn_t

For each element in table b, either use setn or mergen to add the data to table a. Which method is used is determined by the flags passed in.

Parameters:

a	The table to add the data to.
b	The table to iterate over, adding its data to table a
flags	How to add the table to table a. One of: APR_OVERLAP_TABLES_SET Use apr_table_setn APR_OVERLAP_TABLES_MERGE Use apr_table_mergen

Remarks:

When merging duplicates, the two values are concatenated, separated by the string ", ".

This function is highly optimized, and uses less memory and CPU cycles than a function that just loops through table b calling other functions. Conceptually, apr_table_overlap does this:

  apr_array_header_t *barr = apr_table_elts(b);
  apr_table_entry_t *belt = (apr_table_entry_t *)barr->elts;
  int i;

  for (i = 0; i < barr->nelts; ++i) {
      if (flags & APR_OVERLAP_TABLES_MERGE) {
          apr_table_mergen(a, belt[i].key, belt[i].val);
      }
      else {
          apr_table_setn(a, belt[i].key, belt[i].val);
      }
  }
 

Except that it is more efficient (less space and cpu-time) especially when b has many elements.

Notice the assumptions on the keys and values in b -- they must be in an ancestor of a's pool. In practice b and a are usually from the same pool.

Eliminate redundant entries in a table by either overwriting or merging duplicates.

Parameters:

t	Table.
flags	APR_OVERLAP_TABLES_MERGE to merge, or APR_OVERLAP_TABLES_SET to overwrite

Remarks:

When merging duplicates, the two values are concatenated, separated by the string ", ".

Determine if any of stdin, stdout, or stderr should be linked to pipes when starting a child process.

Parameters:

attr	The procattr we care about.
in	Should stdin be a pipe back to the parent?
out	Should stdout be a pipe back to the parent?
err	Should stderr be a pipe back to the parent?

Note:

If APR_NO_PIPE, there will be no special channel, the child inherits the parent's corresponding stdio stream. If APR_NO_FILE is specified, that corresponding stream is closed in the child (and will be INVALID_HANDLE_VALUE when inspected on Win32). This can have ugly side effects, as the next file opened in the child on Unix will fall into the stdio stream fd slot!

Set the child_in and/or parent_in values to existing apr_file_t values.

Parameters:

attr	The procattr we care about.
child_in	apr_file_t value to use as child_in. Must be a valid file.
parent_in	apr_file_t value to use as parent_in. Must be a valid file.

Remarks:

This is NOT a required initializer function. This is useful if you have already opened a pipe (or multiple files) that you wish to use, perhaps persistently across multiple process invocations - such as a log file. You can save some extra function calls by not creating your own pipe since this creates one in the process space for you.

Bug:

Note that calling this function with two NULL files on some platforms creates an APR_FULL_BLOCK pipe, but this behavior is neither portable nor is it supported.

See also:

apr_procattr_io_set instead for simple pipes.

Set the child_out and parent_out values to existing apr_file_t values.

Parameters:

attr	The procattr we care about.
child_out	apr_file_t value to use as child_out. Must be a valid file.
parent_out	apr_file_t value to use as parent_out. Must be a valid file.

Remarks:

This is NOT a required initializer function. This is useful if you have already opened a pipe (or multiple files) that you wish to use, perhaps persistently across multiple process invocations - such as a log file.

Bug:

Note that calling this function with two NULL files on some platforms creates an APR_FULL_BLOCK pipe, but this behavior is neither portable nor is it supported.

See also:

apr_procattr_io_set instead for simple pipes.

Set the child_err and parent_err values to existing apr_file_t values.

Parameters:

attr	The procattr we care about.
child_err	apr_file_t value to use as child_err. Must be a valid file.
parent_err	apr_file_t value to use as parent_err. Must be a valid file.

Remarks:

This is NOT a required initializer function. This is useful if you have already opened a pipe (or multiple files) that you wish to use, perhaps persistently across multiple process invocations - such as a log file.

Bug:

Note that calling this function with two NULL files on some platforms creates an APR_FULL_BLOCK pipe, but this behavior is neither portable nor is it supported.

See also:

apr_procattr_io_set instead for simple pipes.

Set which directory the child process should start executing in.

Parameters:

attr	The procattr we care about.
dir	Which dir to start in. By default, this is the same dir as the parent currently resides in, when the createprocess call is made.

Set what type of command the child process will call.

Parameters:

attr	The procattr we care about.
cmd	The type of command. One of: APR_SHELLCMD -- Anything that the shell can handle APR_PROGRAM -- Executable program (default) APR_PROGRAM_ENV -- Executable program, copy environment APR_PROGRAM_PATH -- Executable program on PATH, copy env

Determine if the child should start in detached state.

Parameters:

attr	The procattr we care about.
detach	Should the child start in detached state? Default is no.

Specify an error function to be called in the child process if APR encounters an error in the child prior to running the specified program.

Parameters:

attr	The procattr describing the child process to be created.
errfn	The function to call in the child process.

Remarks:

At the present time, it will only be called from apr_proc_create() on platforms where fork() is used. It will never be called on other platforms, on those platforms apr_proc_create() will return the error in the parent process rather than invoke the callback in the now-forked child process.

Specify that apr_proc_create() should do whatever it can to report failures to the caller of apr_proc_create(), rather than find out in the child.

Parameters:

attr	The procattr describing the child process to be created.
chk	Flag to indicate whether or not extra work should be done to try to report failures to the caller.

Remarks:

This flag only affects apr_proc_create() on platforms where fork() is used. This leads to extra overhead in the calling process, but that may help the application handle such errors more gracefully.

Determine if the child should start in its own address space or using the current one from its parent

Parameters:

attr	The procattr we care about.
addrspace	Should the child start in its own address space? Default is no on NetWare and yes on other platforms.

Set the username used for running process

Parameters:

attr	The procattr we care about.
username	The username used
password	User password if needed. Password is needed on WIN32 or any other platform having APR_PROCATTR_USER_SET_REQUIRES_PASSWORD set.

Set the group used for running process

Parameters:

attr	The procattr we care about.
groupname	The group name used

Create a new process and execute a new program within that process.

Parameters:

new_proc	The resulting process handle.
progname	The program to run
args	the arguments to pass to the new program. The first one should be the program name.
env	The new environment table for the new process. This should be a list of NULL-terminated strings. This argument is ignored for APR_PROGRAM_ENV, APR_PROGRAM_PATH, and APR_SHELLCMD_ENV types of commands.
attr	the procattr we should use to determine how to create the new process
pool	The pool to use.

Note:

This function returns without waiting for the new process to terminate; use apr_proc_wait for that.

Wait for a child process to die

Parameters:

proc	The process handle that corresponds to the desired child process
exitcode	The returned exit status of the child, if a child process dies, or the signal that caused the child to die. On platforms that don't support obtaining this information, the status parameter will be returned as APR_ENOTIMPL.
exitwhy	Why the child died, the bitwise or of: APR_PROC_EXIT -- process terminated normally APR_PROC_SIGNAL -- process was killed by a signal APR_PROC_SIGNAL_CORE -- process was killed by a signal, and generated a core dump.
waithow	How should we wait. One of: APR_WAIT -- block until the child process dies. APR_NOWAIT -- return immediately regardless of if the child is dead or not.

Remarks:

The childs status is in the return code to this process. It is one of:

            APR_CHILD_DONE     -- child is no longer running.
            APR_CHILD_NOTDONE  -- child is still running.
 

Wait for any current child process to die and return information about that child.

Parameters:

proc	Pointer to NULL on entry, will be filled out with child's information
exitcode	The returned exit status of the child, if a child process dies, or the signal that caused the child to die. On platforms that don't support obtaining this information, the status parameter will be returned as APR_ENOTIMPL.
exitwhy	Why the child died, the bitwise or of: APR_PROC_EXIT -- process terminated normally APR_PROC_SIGNAL -- process was killed by a signal APR_PROC_SIGNAL_CORE -- process was killed by a signal, and generated a core dump.
waithow	How should we wait. One of: APR_WAIT -- block until the child process dies. APR_NOWAIT -- return immediately regardless of if the child is dead or not.
p	Pool to allocate child information out of.

Bug:

Passing proc as a *proc rather than **proc was an odd choice for some platforms... this should be revisited in 1.0

Detach the process from the controlling terminal.

Parameters:

daemonize

set to non-zero if the process should daemonize and become a background process, else it will stay in the foreground.

Stop watching the specified other child.

Parameters:

data	The data to pass to the maintenance function. This is used to find the process to unregister.

Warning:

Since this can be called by a maintenance function while we're scanning the other_children list, all scanners should protect themself by loading ocr->next before calling any maintenance function.

Notify the maintenance callback of a registered other child process that application has detected an event, such as death.

Parameters:

proc	The process to check
reason	The reason code to pass to the maintenance function
status	The status to pass to the maintenance function

Remarks:

An example of code using this behavior;

 rv = apr_proc_wait_all_procs(&proc, &exitcode, &status, APR_WAIT, p);
 if (APR_STATUS_IS_CHILD_DONE(rv)) {
 #if APR_HAS_OTHER_CHILD
     if (apr_proc_other_child_alert(&proc, APR_OC_REASON_DEATH, status)
             == APR_SUCCESS) {
         ;  (already handled)
     }
     else
 #endif
         [... handling non-otherchild processes death ...]
 

Test one specific other child processes and invoke the maintenance callback with the appropriate reason code, if still running, or the appropriate reason code if the process is no longer healthy.

Parameters:

ocr	The registered other child
reason	The reason code (e.g. APR_OC_REASON_RESTART) if still running

Test all registered other child processes and invoke the maintenance callback with the appropriate reason code, if still running, or the appropriate reason code if the process is no longer healthy.

Parameters:

reason

The reason code (e.g. APR_OC_REASON_RESTART) to running processes

Terminate a process.

Parameters:

proc	The process to terminate.
sig	How to kill the process.

Register a process to be killed when a pool dies.

Parameters:

a	The pool to use to define the processes lifetime
proc	The process to register
how	How to kill the process, one of: APR_KILL_NEVER -- process is never sent any signals APR_KILL_ALWAYS -- process is sent SIGKILL on apr_pool_t cleanup APR_KILL_AFTER_TIMEOUT -- SIGTERM, wait 3 seconds, SIGKILL APR_JUST_WAIT -- wait forever for the process to complete APR_KILL_ONLY_ONCE -- send SIGTERM and then wait

convert a time to its human readable components using an offset from GMT

Parameters:

result	the exploded time
input	the time to explode
offs	the number of seconds offset to apply

convert a time to its human readable components in GMT timezone

Parameters:

result	the exploded time
input	the time to explode

convert a time to its human readable components in local timezone

Parameters:

result	the exploded time
input	the time to explode

Convert time value from human readable format to a numeric apr_time_t e.g. elapsed usec since epoch

Parameters:

result	the resulting imploded time
input	the input exploded time

Convert time value from human readable format to a numeric apr_time_t that always represents GMT

Parameters:

result	the resulting imploded time
input	the input exploded time

apr_rfc822_date formats dates in the RFC822 format in an efficient manner. It is a fixed length format which requires the indicated amount of storage, including the trailing NUL terminator.

Parameters:

date_str	String to write to.
t	the time to convert

apr_ctime formats dates in the ctime() format in an efficient manner. it is a fixed length format and requires the indicated amount of storage including the trailing NUL terminator. Unlike ANSI/ISO C ctime(), apr_ctime() does not include a
at the end of the string.

Parameters:

date_str	String to write to.
t	the time to convert

formats the exploded time according to the format specified

Parameters:

s	string to write to
retsize	The length of the returned string
max	The maximum length of the string
format	The format for the time string
tm	The time to convert

Improve the clock resolution for the lifetime of the given pool. Generally this is only desireable on benchmarking and other very time-sensitive applications, and has no impact on most platforms.

Parameters:

p	The pool to associate the finer clock resolution

An APR internal function for fast ucs-2 wide Unicode format conversion to the utf-8 octet-encoded Unicode. This function is used for filename and other resource conversions for platforms providing native Unicode support.

Only the errors APR_EINVAL and APR_INCOMPLETE may occur, the former when the character code is invalid (in or out of context) and the later when more words were expected, but insufficient words remain.

Definition at line 642 of file apr_pools.h.

const void apr_status_t(*) apr_status_t(* child_cleanup)(void *)) __attribute__((nonnull(3

Definition at line 627 of file apr_pools.h.

const void apr_status_t(*) apr_status_t(*) void data)

Definition at line 625 of file apr_pools.h.

const void apr_status_t(* plain_cleanup)(void *)

Definition at line 626 of file apr_pools.h.