basic memory node structure
@note The next, ref and first_avail fields are available for use by the
caller of apr_allocator_alloc(), the remaining fields are read-only.
The next field has to be used with caution and sensibly set when the
memnode is passed back to apr_allocator_free(). See apr_allocator_free()
for details.
The ref and first_avail fields will be properly restored by
apr_allocator_free().
@remark
As far as I can tell the only really sane way to store an MMAP is as a
void * and a length. BeOS requires this area_id, but that’s just a little
something extra. I am exposing this type, because it doesn’t make much
sense to keep it private, and opening it up makes some stuff easier in
Apache.
/
/** The MMAP structure
This structure allows the underlying API error codes to be returned
along with plain text error messages that explain to us mere mortals
what really happened.
Get the true size that would be allocated for the given size (including
the header and alignment).
@param allocator The allocator from which to the memory would be allocated
@param size The size to align
@return The aligned size (or zero on apr_size_t overflow)
Allocate a block of mem from the allocator
@param allocator The allocator to allocate from
@param size The size of the mem to allocate (excluding the
memnode structure)
Destroy an allocator
@param allocator The allocator to be destroyed
@remark Any memnodes not given back to the allocator prior to destroying
will not be free()d.
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.
@param allocator The allocator to give the mem back to
@param memnode The memory node to return
Set the current threshold at which the allocator should start
giving blocks back to the system.
@param allocator The allocator to set the threshold on
@param size The threshold. 0 == unlimited.
Set the owner of the allocator
@param allocator The allocator to set the owner for
@param pool The pool that is to own the allocator
@remark Typically pool is the highest level pool using the allocator
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.
@param argc Pointer to the argc that may be corrected
@param argv Pointer to the argv that may be corrected
@param env Pointer to the env that may be corrected, may be NULL
@remark 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.
Append one array to the end of another, creating a new array in the process.
@param p The pool to allocate the new array out of
@param first The array to put first in the new array.
@param second The array to put second in the new array.
@return A new array containing the data from the two arrays passed in.
Concatenate two arrays together.
@param dst The destination array, and the one to go first in the combined
array
@param src The source array to add to the destination array
Remove all elements from an array.
@param arr The array to remove all elements from.
@remark As the underlying storage is allocated from a pool, no
memory is freed by this operation, but is available for reuse.
Copy the entire array.
@param p The pool to allocate the copy of the array out of
@param arr The array to copy
@return An exact copy of the array passed in
@remark 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.
@param p The pool to allocate the copy of the array out of
@param arr The array to copy
@return An exact copy of the array passed in
@remark The alternate apr_array_copy() copies the entire array.
Create an array.
@param p The pool to allocate the memory out of
@param nelts the number of elements in the initial array
@param elt_size The size of each element in the array.
@return The new array
Remove an element from an array (as a first-in, last-out stack).
@param arr The array to remove an element from.
@return Location of the element in the array.
@remark If there are no elements in the array, NULL is returned.
Generate a new string from the apr_pool_t containing the concatenated
sequence of substrings referenced as elements within the array. The string
will be empty if all substrings are empty or null, or if there are no
elements in the array. If sep is non-NUL, it will be inserted between
elements as a separator.
@param p The pool to allocate the string out of
@param arr The array to generate the string from
@param sep The separator to use
@return A string containing all of the data in the array.
Add a new element to an array (as a first-in, last-out stack).
@param arr The array to add an element to.
@return Location for the new element in the array.
@remark If there are no free spots in the array, then this function will
allocate new space for the new element.
parse a base-10 numeric string into a 64-bit numeric value.
Equivalent to apr_strtoi64(buf, (char**)NULL, 10).
@param buf The string to parse
@return The numeric value of the string. On overflow, errno is set
to ERANGE. On success, errno is set to 0.
Decode a string to plain text
@param plain_dst The destination string for the plain text
@param coded_src The encoded string
@return the length of the plain text string
Decode an EBCDIC string to plain text
@param plain_dst The destination string for the plain text
@param coded_src The encoded string
@return the length of the plain text string
Determine the maximum buffer length required to decode the plain text
string given the encoded string.
@param coded_src The encoded string
@return the maximum required buffer length for the plain text string
Encode a text string using base64encoding.
@param coded_dst The destination string for the encoded string.
@param plain_src The original string in plain text
@param len_plain_src The length of the plain text string
@return the length of the encoded string
Encode an EBCDIC string using base64encoding.
@param coded_dst The destination string for the encoded string.
@param plain_src The original string in plain text
@param len_plain_src The length of the plain text string
@return the length of the encoded string
Given the length of an un-encoded string, get the length of the
encoded string.
@param len the length of an unencoded string.
@return the length of the string after it is encoded, including the
trailing \0
Encode a password using the bcrypt algorithm
@param password The password to encode
@param count The cost of the encoding, possible values are 4 to 31
@param salt Pointer to binary data to be used as salt for the encoding
@param salt_len The size of the salt data (must be >= 16)
@param out The string to store the encoded password in
@param out_len The size of the result buffer (must be >= 61)
Remove all whitespace from a string
@param dest The destination string. It is okay to modify the string
in place. Namely dest == src
@param src The string to rid the spaces from.
@return A pointer to the destination string’s null terminator.
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.
@param dst The destination string
@param src The source string
@param 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.
@return Pointer to the NUL terminator of the destination string, dst
@remark
@brief Clean encryption / decryption context.
@note After cleanup, a context is free to be reused if necessary.
@param ctx The block context to use.
@return Returns APR_ENOTIMPL if not supported.
@brief Decrypt data provided by in, write it to out.
@note The number of bytes written will be written to outlen. If
out is NULL, outlen will contain the maximum size of the
buffer needed to hold the data, including any data
generated by apr_crypto_block_decrypt_finish below. If *out points
to NULL, a buffer sufficiently large will be created from
the pool provided. If *out points to a not-NULL value, this
value will be used as a buffer instead.
@param out Address of a buffer to which data will be written,
see note.
@param outlen Length of the output will be written here.
@param in Address of the buffer to read.
@param inlen Length of the buffer to read.
@param ctx The block context to use.
@return APR_ECRYPT if an error occurred. Returns APR_ENOTIMPL if
not implemented.
@brief Decrypt final data block, write it to out.
@note If necessary the final block will be written out after being
padded. Typically the final block will be written to the
same buffer used by apr_crypto_block_decrypt, offset by the
number of bytes returned as actually written by the
apr_crypto_block_decrypt() call. After this call, the context
is cleaned and can be reused by apr_crypto_block_decrypt_init().
@param out Address of a buffer to which data will be written. This
buffer must already exist, and is usually the same
buffer used by apr_evp_crypt(). See note.
@param outlen Length of the output will be written here.
@param ctx The block context to use.
@return APR_ECRYPT if an error occurred.
@return APR_EPADDING if padding was enabled and the block was incorrectly
formatted.
@return APR_ENOTIMPL if not implemented.
@brief Initialise a context for decrypting arbitrary data using the given key.
@note If *ctx is NULL, a apr_crypto_block_t will be created from a pool. If
*ctx is not NULL, *ctx must point at a previously created structure.
@param ctx The block context returned, see note.
@param blockSize The block size of the cipher.
@param iv Optional initialisation vector.
@param key The key structure to use.
@param p The pool to use.
@return Returns APR_ENOIV if an initialisation vector is required but not specified.
Returns APR_EINIT if the backend failed to initialise the context. Returns
APR_ENOTIMPL if not implemented.
@brief Encrypt data provided by in, write it to out.
@note The number of bytes written will be written to outlen. If
out is NULL, outlen will contain the maximum size of the
buffer needed to hold the data, including any data
generated by apr_crypto_block_encrypt_finish below. If *out points
to NULL, a buffer sufficiently large will be created from
the pool provided. If *out points to a not-NULL value, this
value will be used as a buffer instead.
@param out Address of a buffer to which data will be written,
see note.
@param outlen Length of the output will be written here.
@param in Address of the buffer to read.
@param inlen Length of the buffer to read.
@param ctx The block context to use.
@return APR_ECRYPT if an error occurred. Returns APR_ENOTIMPL if
not implemented.
@brief Encrypt final data block, write it to out.
@note If necessary the final block will be written out after being
padded. Typically the final block will be written to the
same buffer used by apr_crypto_block_encrypt, offset by the
number of bytes returned as actually written by the
apr_crypto_block_encrypt() call. After this call, the context
is cleaned and can be reused by apr_crypto_block_encrypt_init().
@param out Address of a buffer to which data will be written. This
buffer must already exist, and is usually the same
buffer used by apr_evp_crypt(). See note.
@param outlen Length of the output will be written here.
@param ctx The block context to use.
@return APR_ECRYPT if an error occurred.
@return APR_EPADDING if padding was enabled and the block was incorrectly
formatted.
@return APR_ENOTIMPL if not implemented.
@brief Initialise a context for encrypting arbitrary data using the given key.
@note If *ctx is NULL, a apr_crypto_block_t will be created from a pool. If
*ctx is not NULL, *ctx must point at a previously created structure.
@param ctx The block context returned, see note.
@param iv Optional initialisation vector. If the buffer pointed to is NULL,
an IV will be created at random, in space allocated from the pool.
If the buffer pointed to is not NULL, the IV in the buffer will be
used.
@param key The key structure to use.
@param blockSize The block size of the cipher.
@param p The pool to use.
@return Returns APR_ENOIV if an initialisation vector is required but not specified.
Returns APR_EINIT if the backend failed to initialise the context. Returns
APR_ENOTIMPL if not implemented.
@brief Clean encryption / decryption context.
@note After cleanup, a context is free to be reused if necessary.
@param f The context to use.
@return Returns APR_ENOTIMPL if not supported.
@brief Get the result of the last operation on a context. If the result
is NULL, the operation was successful.
@param result - the result structure
@param f - context pointer
@return APR_SUCCESS for success
@brief Get a hash table of key modes, keyed by the name of the mode against
a pointer to apr_crypto_block_key_mode_t, which in turn begins with an
integer.
@brief Get a hash table of key types, keyed by the name of the type against
a pointer to apr_crypto_block_key_type_t, which in turn begins with an
integer.
@brief Create a key from the provided secret or passphrase. The key is cleaned
up when the context is cleaned, and may be reused with multiple encryption
or decryption operations.
@note If *key is NULL, a apr_crypto_key_t will be created from a pool. If
*key is not NULL, *key must point at a previously created structure.
@param key The key returned, see note.
@param rec The key record, from which the key will be derived.
@param f The context to use.
@param p The pool to use.
@return Returns APR_ENOKEY if the pass phrase is missing or empty, or if a backend
error occurred while generating the key. APR_ENOCIPHER if the type or mode
is not supported by the particular backend. APR_EKEYTYPE if the key type is
not known. APR_EPADDING if padding was requested but is not supported.
APR_ENOTIMPL if not implemented.
@brief Create a context for supporting encryption. Keys, certificates,
algorithms and other parameters will be set per context. More than
one context can be created at one time. A cleanup will be automatically
registered with the given pool to guarantee a graceful shutdown.
@param f - context pointer will be written here
@param driver - driver to use
@param params - array of key parameters
@param pool - process pool
@return APR_ENOENGINE when the engine specified does not exist. APR_EINITENGINE
if the engine cannot be initialised.
@remarks NSS: currently no params are supported.
@remarks OpenSSL: the params can have “engine” as a key, followed by an equal
sign and a value.
@brief Create a key from the given passphrase. By default, the PBKDF2
algorithm is used to generate the key from the passphrase. It is expected
that the same pass phrase will generate the same key, regardless of the
backend crypto platform used. The key is cleaned up when the context
is cleaned, and may be reused with multiple encryption or decryption
operations.
@note If *key is NULL, a apr_crypto_key_t will be created from a pool. If
*key is not NULL, *key must point at a previously created structure.
@param key The key returned, see note.
@param ivSize The size of the initialisation vector will be returned, based
on whether an IV is relevant for this type of crypto.
@param pass The passphrase to use.
@param passLen The passphrase length in bytes
@param salt The salt to use.
@param saltLen The salt length in bytes
@param type 3DES_192, AES_128, AES_192, AES_256.
@param mode Electronic Code Book / Cipher Block Chaining.
@param doPad Pad if necessary.
@param iterations Number of iterations to use in algorithm
@param f The context to use.
@param p The pool to use.
@return Returns APR_ENOKEY if the pass phrase is missing or empty, or if a backend
error occurred while generating the key. APR_ENOCIPHER if the type or mode
is not supported by the particular backend. APR_EKEYTYPE if the key type is
not known. APR_EPADDING if padding was requested but is not supported.
APR_ENOTIMPL if not implemented.
@deprecated Replaced by apr_crypto_key().
@brief Shutdown the crypto library.
@note After shutdown, it is expected that the init function can be called again.
@param driver - driver to use
@return Returns APR_ENOTIMPL if not supported.
apr_ctime formats dates in the ctime() format
in an efficient manner. It is a fixed length format
and requires APR_CTIME_LEN bytes of storage including
the trailing NUL terminator.
Unlike ANSI/ISO C ctime(), apr_ctime() does not include
a \n at the end of the string.
@param date_str String to write to.
@param t the time to convert
Parses a string resembling an RFC 822 date. This is meant to be
leinent in its parsing of dates. Hence, this will parse a wider
range of dates than apr_date_parse_http.
Create a new directory on the file system.
@param path the path for the directory to be created. (use / on all systems)
@param perm Permissions for the new directory.
@param 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.
@param path the path for the directory to be created. (use / on all systems)
@param perm Permissions for the new directory.
@param pool the pool to use.
Open the specified directory.
@param new_dir The opened directory descriptor.
@param dirname The full path to the directory (use / on all systems)
@param pool The pool to use.
Read the next entry from the specified directory.
@param finfo the file info structure and filled in by apr_dir_read
@param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_
values
@param thedir the directory descriptor returned from apr_dir_open
@remark No ordering is guaranteed for the entries read.
Remove directory from the file system.
@param path the path for the directory to be removed. (use / on all systems)
@param pool the pool to use.
@remark 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.
Report more information when a DSO function fails.
@param dso The dso handle that has been opened
@param buf Location to store the dso error
@param bufsize The size of the provided buffer
Load a DSO library.
@param res_handle Location to store new handle for the DSO.
@param path Path to the DSO library
@param ctx Pool to use.
@bug We aught to provide an alternative to RTLD_GLOBAL, which
is the only supported method of loading DSOs today.
Load a symbol from a DSO handle.
@param ressym Location to store the loaded symbol
@param handle handle to load the symbol from.
@param symname Name of the symbol to load.
Get the value of an environment variable
@param value the returned value, allocated from @a pool
@param envvar the name of the environment variable
@param pool where to allocate @a value and any temporary storage from
Set the value of an environment variable
@param envvar the name of the environment variable
@param value the value to set
@param pool where to allocate temporary storage from
Append the specified file to another file.
@param from_path The full path to the source file (use / on all systems)
@param to_path The full path to the destination file (use / on all systems)
@param 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_FPROT_FILE_SOURCE_PERMS may be given, in which case the source
file’s permissions are copied.
@param pool The pool to use.
@remark The new file does not need to exist, it will be created if required.
@remark Note that advanced filesystem permissions such as ACLs are not
duplicated by this API. The target permissions (including duplicating the
source file permissions) are assigned only when the target file does not yet
exist.
Set attributes of the specified file.
@param fname The full path to the file (using / on all systems)
@param attributes Or’d combination of
@li #APR_FILE_ATTR_READONLY - make the file readonly
@li #APR_FILE_ATTR_EXECUTABLE - make the file executable
@li #APR_FILE_ATTR_HIDDEN - make the file hidden
@param attr_mask Mask of valid bits in attributes.
@param pool the pool to use.
@remark 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.
Give the specified apr file handle a new buffer
@param thefile The file handle that is to be modified
@param buffer The buffer
@param bufsize The size of the buffer
@remark It is possible to add a buffer to previously unbuffered
file handles, the #APR_FOPEN_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.
Copy the specified file to another file.
@param from_path The full path to the original file (using / on all systems)
@param to_path The full path to the new file (using / on all systems)
@param 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_FPROT_FILE_SOURCE_PERMS may be given, in which case the source
file’s permissions are copied.
@param pool The pool to use.
@remark 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.
Return the data associated with the current file.
@param data The user data associated with the file.
@param key The key to use for retrieving data associated with this file.
@param file The currently open file.
Set the data associated with the current file.
@param file The currently open file.
@param data The user data to associate with the file.
@param key The key to use for associating data with the file.
@param cleanup The cleanup routine to use when the file is destroyed.
Duplicate the specified file descriptor.
@param new_file The structure to duplicate into.
@param old_file The file to duplicate.
@param p The pool to use for the new file.
@remark *new_file must point to a valid apr_file_t, or point to NULL.
Duplicate the specified file descriptor and close the original
@param new_file The old file that is to be closed and reused
@param old_file The file to duplicate
@param p The pool to use for the new file
Read a line from the specified file
@param str The buffer to store the string in.
@param len The length of the string
@param thefile The file descriptor to read from
@remark The buffer will be NUL-terminated if any characters are stored.
The newline at the end of the line will not be stripped.
get the specified file’s stats.
@param finfo Where to store the information about the file.
@param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_* values
@param thefile The file to get information about.
Create a hard link to the specified file.
@param from_path The full path to the original file (using / on all systems)
@param to_path The full path to the new file (using / on all systems)
@remark Both files must reside on the same device.
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.
@param thefile The file to lock.
@param type The type of lock to establish on the file.
Open a temporary file
@param fp The apr file to use as a temporary file.
@param templ The template to use when creating a temp file.
@param flags The flags to open the file with. If this is zero,
the file is opened with
#APR_FOPEN_CREATE | #APR_FOPEN_READ | #APR_FOPEN_WRITE |
#APR_FOPEN_EXCL | #APR_FOPEN_DELONCLOSE
@param p The pool to allocate the file out of.
@remark
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.
Set the mtime of the specified file.
@param fname The full path to the file (using / on all systems)
@param mtime The mtime to apply to the file.
@param pool The pool to use.
@warning Platforms which do not implement this feature will return
#APR_ENOTIMPL.
Create a named pipe.
@param filename The filename of the named pipe
@param perm The permissions for the newly created pipe.
@param pool The pool to operate on.
Open the specified file.
@param newf The opened file descriptor.
@param fname The full path to the file (using / on all systems)
@param flag Or’ed value of:
@li #APR_FOPEN_READ open for reading
@li #APR_FOPEN_WRITE open for writing
@li #APR_FOPEN_CREATE create the file if not there
@li #APR_FOPEN_APPEND file ptr is set to end prior to all writes
@li #APR_FOPEN_TRUNCATE set length to zero if file exists
@li #APR_FOPEN_BINARY not a text file
@li #APR_FOPEN_BUFFERED buffer the data. Default is non-buffered
@li #APR_FOPEN_EXCL return error if #APR_FOPEN_CREATE and file exists
@li #APR_FOPEN_DELONCLOSE delete the file after closing
@li #APR_FOPEN_XTHREAD Platform dependent tag to open the file
for use across multiple threads
@li #APR_FOPEN_SHARELOCK Platform dependent support for higher
level locked read/write access to support
writes across process/machines
@li #APR_FOPEN_NOCLEANUP Do not register a cleanup with the pool
passed in on the @a pool argument (see below)
@li #APR_FOPEN_SENDFILE_ENABLED Open with appropriate platform semantics
for sendfile operations. Advisory only,
apr_socket_sendfile does not check this flag
@li #APR_FOPEN_LARGEFILE Platform dependent flag to enable large file
support, see WARNING below
@li #APR_FOPEN_SPARSE Platform dependent flag to enable sparse file
support, see WARNING below
@li #APR_FOPEN_NONBLOCK Platform dependent flag to enable
non blocking file io
@param perm Access permissions for file.
@param pool The pool to use.
@remark If perm is #APR_FPROT_OS_DEFAULT and the file is being created,
appropriate default permissions will be used.
@remark By default, the returned file descriptor will not be
inherited by child processes created by apr_proc_create(). This
can be changed using apr_file_inherit_set().
open standard error as an apr file pointer, with flags.
@param thefile The apr file to use as stderr.
@param flags The flags to open the file with. Only the
@li #APR_FOPEN_EXCL
@li #APR_FOPEN_BUFFERED
@li #APR_FOPEN_XTHREAD
@li #APR_FOPEN_SHARELOCK
@li #APR_FOPEN_SENDFILE_ENABLED
@li #APR_FOPEN_LARGEFILE
open standard input as an apr file pointer, with flags.
@param thefile The apr file to use as stdin.
@param flags The flags to open the file with. Only the
@li #APR_FOPEN_EXCL
@li #APR_FOPEN_BUFFERED
@li #APR_FOPEN_XTHREAD
@li #APR_FOPEN_SHARELOCK
@li #APR_FOPEN_SENDFILE_ENABLED
@li #APR_FOPEN_LARGEFILE
open standard output as an apr file pointer, with flags.
@param thefile The apr file to use as stdout.
@param flags The flags to open the file with. Only the
@li #APR_FOPEN_EXCL
@li #APR_FOPEN_BUFFERED
@li #APR_FOPEN_XTHREAD
@li #APR_FOPEN_SHARELOCK
@li #APR_FOPEN_SENDFILE_ENABLED
@li #APR_FOPEN_LARGEFILE
set the specified file’s permission bits.
@param fname The file (name) to apply the permissions to.
@param perms The permission bits to apply to the file.
Create an anonymous pipe.
@param in The newly created pipe’s file for reading.
@param out The newly created pipe’s file for writing.
@param pool The pool to operate on.
@remark 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 apr_file_pipe_create_pools()
Create an anonymous pipe which portably supports async timeout options.
@param in The newly created pipe’s file for reading.
@param out The newly created pipe’s file for writing.
@param blocking one of these values defined in apr_thread_proc.h;
@li #APR_FULL_BLOCK
@li #APR_READ_BLOCK
@li #APR_WRITE_BLOCK
@li #APR_FULL_NONBLOCK
@param pool The pool to operate on.
@remark 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().
@remark 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.
@deprecated @see apr_file_pipe_create_pools()
Create an anonymous pipe which portably supports async timeout options,
placing each side of the pipe in a different pool.
@param in The newly created pipe’s file for reading.
@param out The newly created pipe’s file for writing.
@param blocking one of these values defined in apr_thread_proc.h;
@li #APR_FULL_BLOCK
@li #APR_READ_BLOCK
@li #APR_WRITE_BLOCK
@li #APR_FULL_NONBLOCK
@param pool_in The pool for the reading pipe.
@param pool_out The pool for the writing pipe.
@remark 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().
@remark 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.
Get the timeout value for a pipe or manipulate the blocking state.
@param thepipe The pipe we are getting a timeout for.
@param timeout The current timeout value in microseconds.
Set the timeout value for a pipe or manipulate the blocking state.
@param thepipe The pipe we are setting a timeout on.
@param timeout The timeout value in microseconds. Values < 0 mean wait
forever, 0 means do not wait at all.
Write a string to a file using a printf format.
@param fptr The file to write to.
@param format The format string
@param … The values to substitute in the format string
@return The number of bytes written
Read data from the specified file.
@param thefile The file descriptor to read from.
@param buf The buffer to store the data to.
@param nbytes On entry, the number of bytes to read; on exit, the number
of bytes read.
Read data from the specified file, ensuring that the buffer is filled
before returning.
@param thefile The file descriptor to read from.
@param buf The buffer to store the data to.
@param nbytes The number of bytes to read.
@param bytes_read If non-NULL, this will contain the number of bytes read.
Delete the specified file.
@param path The full path to the file (using / on all systems)
@param pool The pool to use.
@remark If the file is open, it won’t be removed until all
instances are closed.
Rename the specified file.
@param from_path The full path to the original file (using / on all systems)
@param to_path The full path to the new file (using / on all systems)
@param 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.
Move the read/write file offset to a specified byte within a file.
@param thefile The file descriptor
@param where How to move the pointer, one of:
@li #APR_SET – set the offset to offset
@li #APR_CUR – add the offset to the current position
@li #APR_END – add the offset to the current file size
@param offset The offset to move the pointer to.
@remark The third argument is modified to be the offset the pointer
was actually moved to.
Move the specified file descriptor to a new pool
@param new_file Pointer in which to return the new apr_file_t
@param old_file The file to move
@param p The pool to which the descriptor is to be moved
@remark 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.
@remark The new pool need not be an ancestor of old_file’s pool.
@remark After calling this function, old_file may not be used
Truncate the file’s length to the specified offset
@param fp The file to truncate
@param offset The offset to truncate to.
@remark The read/write file offset is repositioned to offset.
Write data to the specified file.
@param thefile The file descriptor to write to.
@param buf The buffer which contains the data.
@param nbytes On entry, the number of bytes to write; on exit, the number
of bytes written.
Write data to the specified file, ensuring that all of the data is
written before returning.
@param thefile The file descriptor to write to.
@param buf The buffer which contains the data.
@param nbytes The number of bytes to write.
@param bytes_written If non-NULL, set to the number of bytes written.
Write data from iovec array to the specified file.
@param thefile The file descriptor to write to.
@param vec The array from which to get the data to write to the file.
@param 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.
@param nbytes The number of bytes written.
Write data from iovec array to the specified file, ensuring that all of the
data is written before returning.
@param thefile The file descriptor to write to.
@param vec The array from which to get the data to write to the file.
@param 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.
@param nbytes The number of bytes written.
Determine the encoding used internally by the FilePath functions
@param style points to a variable which receives the encoding style flag
@param p the pool to allocate any working storage
@remark 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.
Return the default file path (for relative file names)
@param path the default path string returned
@param flags optional flag APR_FILEPATH_NATIVE to retrieve the
default file path in os-native format.
@param p the pool to allocate the default path string from
Merge a list of search path components into a single search path
@param liststr the returned search path; may be NULL if @a pathelts is empty
@param pathelts the components of the search path
@param p the pool to allocate the search path from
@remark emtpy strings in the source array are ignored.
@remark the path separator in @a liststr is system specific;
e.g., ‘:’ on Unix, ‘;’ on Windows, etc.
Split a search path into separate components
@param pathelts the returned components of the search path
@param liststr the search path (e.g., getenv(“PATH”))
@param p the pool to allocate the array and path components from
@remark empty path components do not become part of @a pathelts.
@remark the path separator in @a liststr is system specific;
e.g., ‘:’ on Unix, ‘;’ on Windows, etc.
Merge additional file path onto the previously processed rootpath
@param newpath the merged paths returned
@param rootpath the root file path (NULL uses the current working path)
@param addpath the path to add to the root path
@param flags the desired APR_FILEPATH_ rules to apply when merging
@param p the pool to allocate the new path string from
@remark 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.
Extract the rootpath from the given filepath
@param rootpath the root file path returned with APR_SUCCESS or APR_EINCOMPLETE
@param filepath the pathname to parse for its root component
@param flags the desired rules to apply, from
Get name of the current machine
@param buf A buffer to store the hostname in.
@param len The maximum length of the hostname that can be stored in the
buffer provided. The suggested length is APRMAXHOSTLEN + 1.
@param cont The pool to use.
@remark If the buffer was not large enough, an error will be returned.
Look up the host name from an apr_sockaddr_t.
@param hostname The hostname.
@param sa The apr_sockaddr_t.
@param flags Special processing flags.
@remark Results can vary significantly between platforms
when processing wildcard socket addresses.
Parse the options initialized by apr_getopt_init().
@param os The apr_opt_t structure returned by apr_getopt_init()
@param opts A string of characters that are acceptable options to the
program. Characters followed by “:” are required to have an
option associated
@param option_ch The next option character parsed
@param option_arg The argument following the option character:
@return There are four potential status values on exit. They are:
Initialize the arguments for parsing by apr_getopt().
@param os The options structure created for apr_getopt()
@param cont The pool to operate on
@param argc The number of arguments to parse
@param argv The array of arguments to parse
@remark Arguments 3 and 4 are most commonly argc and argv from main(argc, argv)
The (*os)->errfn is initialized to fprintf(stderr… but may be overridden.
Parse the options initialized by apr_getopt_init(), accepting long
options beginning with “–” in addition to single-character
options beginning with “-”.
@param os The apr_getopt_t structure created by apr_getopt_init()
@param 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.
@param option_ch Receives the value of “optch” from the apr_getopt_option_t
structure corresponding to the next option matched.
@param option_arg Receives the argument following the option, if any.
@return There are four potential status values on exit. They are:
Given an apr_sockaddr_t and a service name, set the port for the service
@param sockaddr The apr_sockaddr_t that will have its port set
@param servname The name of the service you wish to use
Get the groupid for a specified group name
@param groupid Pointer to the group id (on output)
@param groupname The group name to look up
@param p The pool from which to allocate the string
@remark This function is available only if APR_HAS_USER is defined.
Get the group name for a specified groupid
@param groupname Pointer to new string containing group name (on output)
@param groupid The groupid
@param p The pool from which to allocate the string
@remark This function is available only if APR_HAS_USER is defined.
Make a copy of a hash table
@param pool The pool from which to allocate the new hash table
@param h The hash table to clone
@return The hash table just created
@remark Makes a shallow copy
Iterate over a hash table running the provided function once for every
element in the hash table. The @p comp function will be invoked for
every element in the hash table.
Start iterating over the entries in a hash table.
@param p The pool to allocate the apr_hash_index_t iterator. If this
pool is NULL, then an internal, non-thread-safe iterator is used.
@param ht The hash table
@return The iteration state
@remark There is no restriction on adding or deleting hash entries during
an iteration (although the results may be unpredictable unless all you do
is delete the current entry) and multiple iterations can be in
progress at the same time.
Look up the value associated with a key in a hash table.
@param ht The hash table
@param key Pointer to the key
@param klen Length of the key. Can be APR_HASH_KEY_STRING to use the string length.
@return Returns NULL if the key is not present.
Create a hash table with a custom hash function
@param pool The pool to allocate the hash table out of
@param hash_func A custom hash function.
@return The hash table just created
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.
@param p The pool to use for the new hash table
@param h1 The first of the tables to merge
@param h2 The second of the tables to merge
@param merger A callback function to merge values, or NULL to
make values from h1 override values from h2 (same semantics as
apr_hash_overlay())
@param data Client data to pass to the merger function
@return A new hash table containing all of the data from the two passed in
Continue iterating over the entries in a hash table.
@param hi The iteration state
@return a pointer to the updated iteration state. NULL if there are no more
entries.
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.
@param p The pool to use for the new hash table
@param overlay The table to add to the initial table
@param base The table that represents the initial values of the new table
@return A new hash table containing all of the data from the two passed in
Associate a value with a key in a hash table.
@param ht The hash table
@param key Pointer to the key
@param klen Length of the key. Can be APR_HASH_KEY_STRING to use the string length.
@param val Value to associate with the key
@remark If the value is NULL the hash entry is deleted. The key is stored as is,
and so must have a lifetime at least as long as the hash table’s pool.
Get the current entry’s details from the iteration state.
@param hi The iteration state
@param key Return pointer for the pointer to the key.
@param klen Return pointer for the key length.
@param val Return pointer for the associated value.
@remark 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.
Setup any APR internal data structures. This MUST be the first function
called for any APR library. It is safe to call apr_initialize several
times as long as apr_terminate() is called the same number of times.
@remark See apr_app_initialize() if this is an application, rather than
a library consumer of apr.
Build an ip-subnet representation from an IP address and optional netmask or
number-of-bits.
@param ipsub The new ip-subnet representation
@param ipstr The input IP address string
@param mask_or_numbits The input netmask or number-of-bits string, or NULL
@param p The pool to allocate from
Test the IP address in an apr_sockaddr_t against a pre-built ip-subnet
representation.
@param ipsub The ip-subnet representation
@param sa The socket address to test
@return non-zero if the socket address is within the subnet, 0 otherwise
create a string representation of an int, allocated from a pool
@param p The pool from which to allocate
@param n The number to format
@return The string representation of the number
create a string representation of a long, allocated from a pool
@param p The pool from which to allocate
@param n The number to format
@return The string representation of the number
Set the Multicast Time to Live (ttl) for a multicast transmission.
@param sock The socket to set the multicast ttl
@param ttl Time to live to Assign. 0-255, default=1
@remark If the TTL is 0, packets will only be seen by sockets on
the local machine, and only when multicast loopback is enabled.
Set the Interface to be used for outgoing Multicast Transmissions.
@param sock The socket to set the multicast interface on
@param iface Address of the interface to use for Multicast
Join a Multicast Group
@param sock The socket to join a multicast group
@param join The address of the multicast group to join
@param iface Address of the interface to use. If NULL is passed, the
default multicast interface will be used. (OS Dependent)
@param 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.
@param sock The socket to leave a multicast group
@param addr The address of the multicast group to leave
@param iface Address of the interface to use. If NULL is passed, the
default multicast interface will be used. (OS Dependent)
@param source Source Address to accept transmissions from (non-NULL
implies Source-Specific Multicast)
Encode a password using an MD5 algorithm
@param password The password to encode
@param salt The salt string to use for the encoding
@param result The string to store the encoded password in
@param nbytes The size of the result buffer
MD5 finalization. Ends an MD5 message-digest operation, writing the
message digest and zeroing the context
@param digest The final MD5 digest
@param context The MD5 content we are finalizing.
MD5 translation setup. Provides the APR translation handle to be used
for translating the content before calculating the digest.
@param context The MD5 content to set the translation for.
@param xlate The translation handle to use for this MD5 context
MD5 block update operation. Continue an MD5 message-digest operation,
processing another message block, and updating the context.
@param context The MD5 content to update.
@param input next message block to update
@param inputLen The length of the next message block
Create a new mmap’ed file out of an existing APR file.
@param newmmap The newly created mmap’ed file.
@param file The file to turn into an mmap.
@param offset The offset into the file to start the data pointer at.
@param size The size of the file
@param flag bit-wise or of:
Duplicate the specified MMAP.
@param new_mmap The structure to duplicate into.
@param old_mmap The mmap to duplicate.
@param p The pool to use for new_mmap.
Move the pointer into the mmap’ed file to the specified offset.
@param addr The pointer to the offset specified.
@param mm The mmap’ed file.
@param offset The offset to move to.
create a string representation of an apr_off_t, allocated from a pool
@param p The pool from which to allocate
@param n The number to format
@return The string representation of the number
Debug version of apr_palloc
@param p See: apr_palloc
@param size See: apr_palloc
@param file_line Where the function is called from.
This is usually APR_POOL__FILE_LINE__.
@return See: apr_palloc
Validate hashes created by APR-supported algorithms: md5, bcrypt, and sha1.
hashes created by crypt are supported only on platforms that provide
crypt(3), so don’t rely on that function unless you know that your
application will be run only on platforms that support it. On platforms
that don’t support crypt(3), this falls back to a clear text string
comparison.
@param passwd The password to validate
@param hash The password to validate against
Debug version of apr_pcalloc
@param p See: apr_pcalloc
@param size See: apr_pcalloc
@param file_line Where the function is called from.
This is usually APR_POOL__FILE_LINE__.
@return See: apr_pcalloc
Get the abort function associated with the specified pool.
@param pool The pool for retrieving the abort function.
@return The abort function for the given pool.
Set the function to be called when an allocation failure occurs.
@remark 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.
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.
Register a function to be called when a pool is cleared or destroyed
@param p The pool to register the cleanup with
@param data The data to pass to the cleanup function.
@param plain_cleanup The function to call when the pool is cleared
or destroyed
@param child_cleanup The function to call when a child process is about
to exec - this function is called in the child, obviously!
Clear all memory in the pool and run all the cleanups. This also destroys all
subpools.
@param p The pool to clear
@remark This does not actually free the memory, it just allows the pool
to re-use this memory for the next allocation.
@see apr_pool_destroy()
Debug version of apr_pool_clear.
@param p See: apr_pool_clear.
@param file_line Where the function is called from.
This is usually APR_POOL__FILE_LINE__.
@remark Only available when APR_POOL_DEBUG is defined.
Call this directly if you have your 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.
Create a new pool.
@param newpool The pool we have just created.
@param 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.
@param abort_fn A function to use if the pool cannot allocate more memory.
@param allocator The allocator to use with the new pool. If NULL the
allocator of the parent pool will be used.
@remark 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.
Debug version of apr_pool_create_ex.
@param newpool @see apr_pool_create.
@param parent @see apr_pool_create.
@param abort_fn @see apr_pool_create.
@param allocator @see apr_pool_create.
@param file_line Where the function is called from.
This is usually APR_POOL__FILE_LINE__.
@remark Only available when APR_POOL_DEBUG is defined.
Call this directly if you have your 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.
Create a new unmanaged pool.
@param newpool The pool we have just created.
@param abort_fn A function to use if the pool cannot allocate more memory.
@param allocator The allocator to use with the new pool. If NULL a
new allocator will be created with the new pool as owner.
@remark 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.
@warning Any child cleanups registered against the new pool, or
against sub-pools thereof, will not be executed during an
invocation of apr_proc_create(), so resources created in an
“unmanaged” pool hierarchy will leak to child processes.
Debug version of apr_pool_create_unmanaged_ex.
@param newpool @see apr_pool_create_unmanaged.
@param abort_fn @see apr_pool_create_unmanaged.
@param allocator @see apr_pool_create_unmanaged.
@param file_line Where the function is called from.
This is usually APR_POOL__FILE_LINE__.
@remark Only available when APR_POOL_DEBUG is defined.
Call this directly if you have your 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.
Destroy the pool. This takes similar action as apr_pool_clear() and then
frees all the memory.
@param p The pool to destroy
@remark This will actually free the memory
Debug version of apr_pool_destroy.
@param p See: apr_pool_destroy.
@param file_line Where the function is called from.
This is usually APR_POOL__FILE_LINE__.
@remark Only available when APR_POOL_DEBUG is defined.
Call this directly if you have your 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.
Setup all of the internal structures required to use pools
@remark Programs do NOT need to call this directly. APR will call this
automatically from apr_initialize.
@internal
Determine if pool a is an ancestor of pool b.
@param a The pool to search
@param b The pool to search for
@return True if a is an ancestor of b, NULL is considered an ancestor
of all pools.
@remark 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.
Register a process to be killed when a pool dies.
@param a The pool to use to define the processes lifetime
@param proc The process to register
@param how How to kill the process, one of:
Tear down all of the internal structures required to use pools
@remark Programs do NOT need to call this directly. APR will call this
automatically from apr_terminate.
@internal
Return the data associated with the current pool.
@param data The user data associated with the pool.
@param key The key for the data to retrieve
@param pool The current pool.
Set the data associated with the current pool
@param data The user data associated with the pool.
@param key The key to use for association
@param cleanup The cleanup program to use to cleanup the data (NULL if none)
@param 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.
Set the data associated with the current pool
@param data The user data associated with the pool.
@param key The key to use for association
@param cleanup The cleanup program to use to cleanup the data (NULL if none)
@param 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.
@warning 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.
Create a new process and execute a new program within that process.
@param new_proc The resulting process handle.
@param progname The program to run
@param args the arguments to pass to the new program. The first
one should be the program name.
@param 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.
@param attr the procattr we should use to determine how to create the new
process
@param pool The pool to use.
@note This function returns without waiting for the new process to terminate;
use apr_proc_wait for that.
Detach the process from the controlling terminal.
@param daemonize set to non-zero if the process should daemonize
and become a background process, else it will
stay in the foreground.
This is currently the only non-portable call in APR. This executes
a standard unix fork.
@param proc The resulting process handle.
@param cont The pool to use.
@remark returns APR_INCHILD for the child, and APR_INPARENT for the parent
or an error.
Notify the maintenance callback of a registered other child process
that application has detected an event, such as death.
@param proc The process to check
@param reason The reason code to pass to the maintenance function
@param status The status to pass to the maintenance function
@remark An example of code using this behavior;
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.
@param ocr The registered other child
@param 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.
@param reason The reason code (e.g. APR_OC_REASON_RESTART) to running processes
Register an other_child – a child associated to its registered
maintence callback. This callback is invoked when the process
dies, is disconnected or disappears.
@param proc The child process to register.
@param maintenance maintenance is a function that is invoked with a
reason and the data pointer passed here.
@param data Opaque context data passed to the maintenance function.
@param write_fd An fd that is probed for writing. If it is ever unwritable
then the maintenance is invoked with reason
OC_REASON_UNWRITABLE.
@param p The pool to use for allocating memory.
@bug write_fd duplicates the proc->out stream, it’s really redundant
and should be replaced in the APR 1.0 API with a bitflag of which
proc->in/out/err handles should be health checked.
@bug no platform currently tests the pipes health.
Stop watching the specified other child.
@param 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.
Wait for a child process to die
@param proc The process handle that corresponds to the desired child process
@param 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.
@param exitwhy Why the child died, the bitwise or of:
Wait for any current child process to die and return information
about that child.
@param proc Pointer to NULL on entry, will be filled out with child’s
information
@param 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.
@param exitwhy Why the child died, the bitwise or of:
Determine if the child should start in its own address space or using the
current one from its parent
@param attr The procattr we care about.
@param addrspace Should the child start in its own address space? Default
is no on NetWare and yes on other platforms.
Set the child_err and parent_err values to existing apr_file_t values.
@param attr The procattr we care about.
@param child_err apr_file_t value to use as child_err. Must be a valid file.
@param parent_err apr_file_t value to use as parent_err. Must be a valid file.
@remark 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 apr_procattr_io_set instead for simple pipes.
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.
@param attr The procattr describing the child process to be created.
@param errfn The function to call in the child process.
@remark 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.
Set the child_in and/or parent_in values to existing apr_file_t values.
@param attr The procattr we care about.
@param child_in apr_file_t value to use as child_in. Must be a valid file.
@param parent_in apr_file_t value to use as parent_in. Must be a valid file.
@remark 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 apr_procattr_io_set instead for simple pipes.
Set the child_out and parent_out values to existing apr_file_t values.
@param attr The procattr we care about.
@param child_out apr_file_t value to use as child_out. Must be a valid file.
@param parent_out apr_file_t value to use as parent_out. Must be a valid file.
@remark 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 apr_procattr_io_set instead for simple pipes.
Determine if the child should start in detached state.
@param attr The procattr we care about.
@param detach Should the child start in detached state? Default is no.
Set which directory the child process should start executing in.
@param attr The procattr we care about.
@param 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.
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.
@param attr The procattr describing the child process to be created.
@param chk Flag to indicate whether or not extra work should be done
to try to report failures to the caller.
@remark 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 any of stdin, stdout, or stderr should be linked to pipes
when starting a child process.
@param attr The procattr we care about.
@param in Should stdin be a pipe back to the parent?
@param out Should stdout be a pipe back to the parent?
@param 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!
Register permission set function
@param attr The procattr we care about.
@param perms_set_fn Permission set callback
@param data Data to pass to permission callback function
@param perms Permissions to set
Set the username used for running process
@param attr The procattr we care about.
@param username The username used
@param password User password if needed. Password is needed on WIN32
or any other platform having
APR_PROCATTR_USER_SET_REQUIRES_PASSWORD set.
printf-style style printing routine. The data is output to a string
allocated from a pool
@param p The pool to allocate out of
@param fmt The format of the string
@param … The arguments to use while printing the data
@return The new string
Concatenate multiple strings, allocating memory out a pool
@param p The pool to allocate out of
@param … The strings to concatenate. The final string must be NULL
@return The new string
Concatenate multiple strings specified in a writev-style vector
@param p The pool from which to allocate
@param vec The strings to concatenate
@param nvec The number of strings to concatenate
@param nbytes (output) strlen of new string (pass in NULL to omit)
@return The new string
duplicate a string into memory allocated out of a pool
@param p The pool to allocate out of
@param s The string to duplicate
@return The new string or NULL if s == NULL
Create a null-terminated string by making a copy of a sequence
of characters and appending a null byte
@param p The pool to allocate out of
@param s The block of characters to duplicate
@param n The number of characters to duplicate
@return The new string or NULL if s == NULL
@remark 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
@param p The pool to allocate out of
@param s The string to duplicate
@param n The maximum number of characters to duplicate
@return The new string or NULL if s == NULL
@remark The amount of memory allocated from the pool is the length
of the returned string including the NUL terminator
printf-style style printing routine. The data is output to a string
allocated from a pool
@param p The pool to allocate out of
@param fmt The format of the string
@param ap The arguments to use while printing the data
@return The new string
apr_rfc822_date formats dates in the RFC822
format in an efficient manner. It is a fixed length
format which requires APR_RFC822_DATA_LEN bytes of storage,
including the trailing NUL terminator.
@param date_str String to write to.
@param t the time to convert
Provide a means to SHA1 crypt/encode a plaintext password in a way which
makes password file compatible with those commonly use in netscape web
and ldap installations.
@param clear The plaintext password
@param len The length of the plaintext password
@param out The encrypted/encoded password
@note SHA1 support is useful for migration purposes, but is less
secure than Apache’s password format, since Apache’s (MD5)
password format uses a random eight character salt to generate
one of many possible hashes for the same password. Netscape
uses plain SHA1 without a salt, so the same password
will always generate the same hash, making it easier
to break since the search space is smaller.
Update the SHA digest
@param context The SHA1 context to update
@param input The buffer to add to the SHA digest
@param inputLen The length of the input buffer
Update the SHA digest with binary data
@param context The SHA1 context to update
@param input The buffer to add to the SHA digest
@param inputLen The length of the input buffer
Make the current thread listen for signals. This thread will loop
forever, calling a provided function whenever it receives a signal. That
functions should return 1 if the signal has been handled, 0 otherwise.
@param signal_handler The function to call when a signal is received
apr_status_t apr_signal_thread((int)(*signal_handler)(int signum))
@note Synchronous signals like SIGABRT/SIGSEGV/SIGBUS/… are ignored by
apr_signal_thread() and thus can’t be waited by this function (they remain
handled by the operating system or its native signals interface).
@remark In APR version 1.6 and ealier, SIGUSR2 was part of these ignored
signals and thus was never passed in to the signal_handler. From APR 1.7
this is no more the case so SIGUSR2 can be handled in signal_handler and
acted upon like the other asynchronous signals.
snprintf routine based on apr_vformatter. This means it understands the
same extensions.
@param buf The buffer to write to
@param len The size of the buffer
@param format The format string
@param … The arguments to use to fill out the format string.
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.
Copy apr_sockaddr_t src to dst on pool p.
@param dst The destination apr_sockaddr_t.
@param src The source apr_sockaddr_t.
@param p The pool for the apr_sockaddr_t and associated storage.
Create apr_sockaddr_t from hostname, address family, and port.
@param sa The new apr_sockaddr_t.
@param hostname The hostname or numeric address string to resolve/parse, or
NULL to build an address that corresponds to 0.0.0.0 or ::
or in case of APR_UNIX family it is absolute socket filename.
@param family The address family to use, or APR_UNSPEC if the system should
decide.
@param port The port number.
@param flags Special processing flags:
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.
@param addr The IP address.
@param sockaddr The socket address to reference.
Write the IP address (in numeric address string format) of the APR
socket address @a sockaddr into the buffer @a buf (of size @a buflen).
@param sockaddr The socket address to reference.
Retrieve the zone of an IPv6 link-local address object.
@param sa Socket address object
@param name If non-NULL, set to the textual representation of the zone id
@param id If non-NULL, set to the integer zone id
@param p Pool from which *name is allocated if used.
@return Returns APR_EBADIP for non-IPv6 socket or socket without any zone id
set, or other error if the interface could not be mapped to a name.
@remark Both name and id may be NULL, neither are modified if
non-NULL in error cases.
Set the zone of an IPv6 link-local address object.
@param sa Socket address object
@param zone_id Zone ID (textual “eth0” or numeric “3”).
@return Returns APR_EBADIP for non-IPv6 socket or an IPv6 address
which isn’t link-local.
Accept a new connection request
@param 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.
@param sock The socket we are listening on.
@param connection_pool The pool for the new socket.
@note The pool will be used by various functions that operate on the
socket. The caller must ensure that it is not used by other threads
at the same time.
Return an address associated with a socket; either the address to
which the socket is bound locally or the address of the peer
to which the socket is connected.
@param sa The returned apr_sockaddr_t.
@param which Whether to retrieve the local or remote address
@param sock The socket to use
Query the specified socket if at the OOB/Urgent data mark
@param sock The socket to query
@param atmark Is set to true if socket is at the OOB/urgent mark,
otherwise is set to false.
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.
Bind the socket to its associated port
@param sock The socket to bind
@param sa The socket address to bind to
@remark This may be where we will find out if there is any other process
using the selected port.
Issue a connection request to a socket either on the same machine
or a different one.
@param sock The socket we wish to use for our side of the connection
@param sa The address of the machine we wish to connect to.
Create a socket.
@param new_sock The new socket that has been set up.
@param family The address family of the socket (e.g., APR_INET).
@param type The type of the socket (e.g., SOCK_STREAM).
@param protocol The protocol of the socket (e.g., APR_PROTO_TCP).
@param cont The pool for the apr_socket_t and associated storage.
@note The pool will be used by various functions that operate on the
socket. The caller must ensure that it is not used by other threads
at the same time.
Return the data associated with the current socket
@param data The user data associated with the socket.
@param key The key to associate with the user data.
@param sock The currently open socket.
Set the data associated with the current socket.
@param sock The currently open socket.
@param data The user data to associate with the socket.
@param key The key to associate with the data.
@param cleanup The cleanup to call when the socket is destroyed.
Listen to a bound socket for connections.
@param sock The socket to listen on
@param 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.
Read data from a network.
@param sock The socket to read the data from.
@param buf The buffer to store the data in.
@param len On entry, the number of bytes to receive; on exit, the number
of bytes received.
@remark
Read data from a socket. On success, the address of the peer from
which the data was sent is copied into the @a from parameter, and the
@a len parameter is updated to give the number of bytes written to
@a buf.
Send data over a network.
@param sock The socket to send the data over.
@param buf The buffer which contains the data to be sent.
@param len On entry, the number of bytes to send; on exit, the number
of bytes sent.
@remark
Send a file from an open file descriptor to a socket, along with
optional headers and trailers
@param sock The socket to which we’re writing
@param file The open file from which to read
@param hdtr A structure containing the headers and trailers to send
@param offset Offset into the file where we should begin writing
@param len (input) - Number of bytes to send from the file
(output) - Number of bytes actually sent,
including headers, file, and trailers
@param flags APR flags that are mapped to OS specific flags
@remark 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 the len parameter.
The offset parameter is passed by reference for no reason; its
value will never be modified by the apr_socket_sendfile() function.
@param sock The socket to send from
@param where The apr_sockaddr_t describing where to send the data
@param flags The flags to use
@param buf The data to send
@param len The length of the data to send
Send multiple buffers over a network.
@param sock The socket to send the data over.
@param vec The array of iovec structs containing the data to send
@param nvec The number of iovec structs in the array
@param len Receives the number of bytes actually written
@remark
get the specified file’s stats. The file is specified by filename,
instead of using a pre-opened file.
@param finfo Where to store the information about the file, which is
never touched if the call fails.
@param fname The name of the file to stat.
@param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_
values
@param pool the pool to use to allocate the new file.
Return a human readable string describing the specified error.
@param statcode The error code to get a string for.
@param buf A buffer to hold the error string.
@param bufsize Size of the buffer to hold the string.
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.
@param size The size to format
@param buf The 5 byte text buffer (counting the trailing null)
@return The buf passed to apr_strfsize()
@remark All negative sizes report ’ - ’, apr_strfsize only formats positive values.
Formats the exploded time according to the format specified
@param s string to write to
@param retsize The length of the returned string
@param max The maximum length of the string
@param format The format for the time string
@param tm The time to convert
Precompile a pattern for matching using the Boyer-Moore-Horspool algorithm
@param p The pool from which to allocate the pattern
@param s The pattern string
@param case_sensitive Whether the matching should be case-sensitive
@return a pointer to the compiled pattern, or NULL if compilation fails
Do a natural order comparison of two strings ignoring the case of the
strings.
@param a The first string to compare
@param b The second string to compare
@return 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.
Do a natural order comparison of two strings.
@param a The first string to compare
@param b The second string to compare
@return 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.
Convert a numeric string into an apr_off_t numeric value.
@param offset The value of the parsed string.
@param 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.
@param 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.
@param 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 numeric string into a 64-bit numeric value
@param 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.
@param 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.
@param 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.
@return The numeric value of the string. On overflow, errno is set
to ERANGE. On success, errno is set to 0.
Split a string into separate null-terminated tokens. The tokens are
delimited in the string by one or more characters from the sep
argument.
@param 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.
@param sep The set of delimiters
@param last State saved by apr_strtok() between calls.
@return The next token from the string
@note the ‘last’ state points to the trailing NUL char of the final
token, otherwise it points to the character following the current
token (all successive or empty occurances of sep are skiped on the
subsequent call to apr_strtok). Therefore it is possible to avoid
a strlen() determination, with the following logic;
toklen = last - retval; if (*last) –toklen;
Add data to a table, regardless of whether there is another element with the
same key.
@param t The table to add to
@param key The key to use
@param val The value to add.
@remark 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.
@param t The table to add to
@param key The key to use
@param val The value to add.
@remark 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.
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.
@param p The pool to allocate the new table out of
@param t The table to clone
@return A deep copy of the table passed in
Create a new table and copy another table into it.
@param p The pool to allocate the new table out of
@param t The table to copy
@return A copy of the table passed in
@warning The table keys and respective values are not copied
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 @p comp function will be invoked for every element
in the table. Otherwise, the function is invoked only for those
elements matching the keys specified.
Get the value associated with a given key from the table. After this call,
the data is still in the table.
@param t The table to search for the key
@param key The key to search for (case does not matter)
@return The value associated with the key, or NULL if the key does not exist.
Get values associated with a given key from the table. If more than one
value exists, return a comma separated list of values. After this call, the
data is still in the table.
@param p The pool to allocate the combined value from, if necessary
@param t The table to search for the key
@param key The key to search for (case does not matter)
@return The value associated with the key, or NULL if the key does not exist.
Make a new table.
@param p The pool to allocate the pool out of
@param nelts The number of elements in the initial table.
@return The new table.
@warning This table can only store text data
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 “, “.
@param t The table to search for the data
@param key The key to merge data for (case does not matter)
@param val The data to add
@remark 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 “, “.
@param t The table to search for the data
@param key The key to merge data for (case does not matter)
@param val The data to add
@remark If the key is not found, then this function acts like apr_table_addn()
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.
@param a The table to add the data to.
@param b The table to iterate over, adding its data to table a
@param 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
APR_OVERLAP_TABLES_ADD Use apr_table_addn
@remark When merging duplicates, the two values are concatenated,
separated by the string “, “.
@remark 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:
Merge two tables into one new table.
@param p The pool to use for the new table
@param overlay The first table to put in the new table
@param base The table to add at the end of the new table
@return A new table containing all of the data from the two passed in
Add a key/value pair to a table. If another element already exists with the
same key, this will overwrite the old data.
@param t The table to add the data to.
@param key The key to use (case does not matter)
@param val The value to add
@remark 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.
@param t The table to add the data to.
@param key The key to use (case does not matter)
@param 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..
Iterate over a table running the provided function once for every
element in the table. The @p vp varargs parameter must be a
list of zero or more (char *) keys followed by a NULL pointer. If
zero keys are given, the @p comp function will be invoked for
every element in the table. Otherwise, the function is invoked
only for those elements matching the keys specified.
Find an existing directory suitable as a temporary storage location.
@param temp_dir The temp directory.
@param p The pool to use for any necessary allocations.
@remark
This function uses an algorithm to search for a directory that an
an application can use for temporary storage.
Tear down any APR internal data structures which aren’t torn down
automatically. apr_terminate must be called once for every call to
apr_initialize() or apr_app_initialize().
@remark An APR program must call this function at termination once it
has stopped using APR services. The APR developers suggest using
@c atexit(apr_terminate) to ensure this is called. When using APR
from a language other than C that has problems with the calling
convention, use apr_terminate2() instead.
@see apr_terminate2
Tear down any APR internal data structures which aren’t torn down
automatically, same as apr_terminate()
@remark An APR program must call either the apr_terminate() or apr_terminate2
function once it it has finished using APR services. The APR
developers suggest using @c atexit(apr_terminate) to ensure this is done.
apr_terminate2 exists to allow non-c language apps to tear down apr,
while apr_terminate() is recommended from c language applications.
Append a piece of text to the end of a list
@param p The pool to allocate out of
@param hdr The text header to append to
@param text The new text to append
Signals all threads blocking on the given condition variable.
Each thread that was signaled is then scheduled to wake up and acquire
the associated mutex. This will happen in a serialized manner.
@param cond the condition variable on which to produce the broadcast.
@remark If no threads are waiting on the condition variable, nothing happens.
Create and initialize a condition variable that can be used to signal
and schedule threads in a single process.
@param cond the memory address where the newly created condition variable
will be stored.
@param pool the pool from which to allocate the condition.
Signals a single thread, if one exists, that is blocking on the given
condition variable. That thread is then scheduled to wake up and acquire
the associated mutex. Although it is not required, if predictable scheduling
is desired, that mutex must be locked while calling this function.
@param cond the condition variable on which to produce the signal.
@remark If no threads are waiting on the condition variable, nothing happens.
Put the active calling thread to sleep until signaled to wake up or
the timeout is reached. Each condition variable must be associated
with a mutex, and that mutex must be locked before calling this
function, or the behavior will be undefined. As the calling thread
is put to sleep, the given mutex will be simultaneously released;
and as this thread wakes up the lock is again simultaneously acquired.
@param cond the condition variable on which to block.
@param mutex the mutex that must be locked upon entering this function,
is released while the thread is asleep, and is again acquired before
returning from this function.
@param timeout The amount of time in microseconds to wait. This is
a maximum, not a minimum. If the condition is signaled, we
will wake up before this time, otherwise the error APR_TIMEUP
is returned.
Put the active calling thread to sleep until signaled to wake up. Each
condition variable must be associated with a mutex, and that mutex must
be locked before calling this function, or the behavior will be
undefined. As the calling thread is put to sleep, the given mutex
will be simultaneously released; and as this thread wakes up the lock
is again simultaneously acquired.
@param cond the condition variable on which to block.
@param mutex the mutex that must be locked upon entering this function,
is released while the thread is asleep, and is again acquired before
returning from this function.
@remark Spurious wakeups may occur. Before and after every call to wait on
a condition variable, the caller should test whether the condition is already
met.
Create a new thread of execution
@param new_thread The newly created thread handle.
@param attr The threadattr to use to determine how to create the thread
@param func The function to start the new thread in
@param data Any data to be passed to the starting function
@param cont The pool to use
Return user data associated with the current thread.
@param data The user data associated with the thread.
@param key The key to associate with the data
@param thread The currently open thread.
Set user data associated with the current thread.
@param data The user data to associate with the thread.
@param key The key to use for associating the data with the thread
@param cleanup The cleanup routine to use when the thread is destroyed.
@param thread The currently open thread.
Create and initialize a mutex that can be used to synchronize threads.
@param mutex the memory address where the newly created mutex will be
stored.
@param flags Or’ed value of:
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.
@param mutex the mutex on which to acquire the lock.
Attempt to acquire the lock for the given mutex until timeout expires.
If the acquisition time outs, the call returns with APR_TIMEUP.
@param mutex the mutex on which to attempt the lock acquiring.
@param timeout the relative timeout (microseconds).
@note A timeout negative or nul means immediate attempt, returning
APR_TIMEUP without blocking if it the lock is already acquired.
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.
@param mutex the mutex on which to attempt the lock acquiring.
Run the specified function one time, regardless of how many threads
call it.
@param control The control variable. The same variable should
be passed in each time the function is tried to be
called. This is how the underlying functions determine
if the function has ever been called before.
@param func The function to call.
Initialize the control variable for apr_thread_once. If this isn’t
called, apr_initialize won’t work.
@param control The control variable to initialize
@param p The pool to allocate data from.
Get the detach state for this threadattr.
@param attr The threadattr to reference
@return APR_DETACH if threads are to be detached, or APR_NOTDETACH
if threads are to be joinable.
Set if newly created threads should be created in detached state.
@param attr The threadattr to affect
@param on Non-zero if detached threads should be created.
Set the stack guard area size of newly created threads.
@param attr The threadattr to affect
@param guardsize The stack guard area size in bytes
@note Thread library implementations commonly use a “guard area”
after each thread’s stack which is not readable or writable such that
stack overflows cause a segfault; this consumes e.g. 4K of memory
and increases memory management overhead. Setting the guard area
size to zero hence trades off reliable behaviour on stack overflow
for performance.
Return the pool associated with the current threadkey.
@param data The user data associated with the threadkey.
@param key The key associated with the data
@param threadkey The currently open threadkey.
Return the pool associated with the current threadkey.
@param data The data to set.
@param key The key to associate with the data.
@param cleanup The cleanup routine to use when the file is destroyed.
@param threadkey The currently open threadkey.
Create and initialize a new thread private address space
@param key The thread private handle.
@param dest The destructor to use when freeing the private memory.
@param cont The pool to use
Get a pointer to the thread private memory
@param new_mem The data stored in private memory
@param key The handle for the desired thread private memory
Set the data to be stored in thread private memory
@param priv The data to be stored in private memory
@param key The handle for the desired thread private memory
Improve the clock resolution for the lifetime of the given pool.
Generally this is only desirable on benchmarking and other very
time-sensitive applications, and has no impact on most platforms.
@param p The pool to associate the finer clock resolution
Convert time value from human readable format to a numeric apr_time_t
(elapsed microseconds since the epoch).
@param result the resulting imploded time
@param input the input exploded time
Convert time value from human readable format to a numeric apr_time_t that
always represents GMT.
@param result the resulting imploded time
@param input the input exploded time
Convert a time to its human readable components using an offset
from GMT.
@param result the exploded time
@param input the time to explode
@param offs the number of seconds offset to apply
Convert the arguments to a program from one string to an array of
strings terminated by a NULL pointer
@param arg_str The arguments to convert
@param argv_out Output location. This is a pointer to an array of strings.
@param token_context Pool to use.
Get the userid (and groupid) of the calling process
@param userid Returns the user id
@param groupid Returns the user’s group id
@param p The pool from which to allocate working space
@remark This function is available only if APR_HAS_USER is defined.
Get the userid (and groupid) for the specified username
@param userid Returns the user id
@param groupid Returns the user’s group id
@param username The username to look up
@param p The pool from which to allocate working space
@remark This function is available only if APR_HAS_USER is defined.
Get the home directory for the named user
@param dirname Pointer to new string containing directory name (on output)
@param username The named user
@param p The pool from which to allocate the string
@remark This function is available only if APR_HAS_USER is defined.
Get the user name for a specified userid
@param username Pointer to new string containing user name (on output)
@param userid The userid
@param p The pool from which to allocate the string
@remark This function is available only if APR_HAS_USER is defined.
Parse a given URI, fill in all supplied fields of a apr_uri_t
structure. This eliminates the necessity of extracting host, port,
path, query info repeatedly in the modules.
@param p The pool to allocate out of
@param uri The uri to parse
@param uptr The apr_uri_t to fill out
@return APR_SUCCESS for success or error code
Special case for CONNECT parsing: it comes with the hostinfo part only
@param p The pool to allocate out of
@param hostinfo The hostinfo string to parse
@param uptr The apr_uri_t to fill out
@return APR_SUCCESS for success or error code
Return the default port for a given scheme. The schemes recognized are
http, ftp, https, gopher, wais, nntp, snews, and prospero
@param scheme_str The string that contains the current scheme
@return The default port for this scheme
Unparse a apr_uri_t structure to an URI string. Optionally
suppress the password for security reasons.
@param p The pool to allocate out of
@param uptr All of the parts of the uri
@param flags How to unparse the uri. One of:
Format a UUID into a string, following the standard format
@param buffer The buffer to place the formatted UUID string into. It must
be at least APR_UUID_FORMATTED_LENGTH + 1 bytes long to hold
the formatted UUID and a null terminator
@param uuid The UUID to format
vsnprintf routine based on apr_vformatter. This means it understands the
same extensions.
@param buf The buffer to write to
@param len The size of the buffer
@param format The format string
@param ap The arguments to use to fill out the format string.
Close a codepage translation handle.
@param convset The codepage translation handle to close
@remark
Return APR_ENOTIMPL if charset transcoding is not available
in this instance of apr-util (i.e., APR_HAS_XLATE is undefined).
Convert a buffer of text from one codepage to another.
@param convset The handle allocated by apr_xlate_open, specifying
the parameters of conversion
@param inbuf The address of the source buffer
@param inbytes_left Input: the amount of input data to be translated
Output: the amount of input data not yet translated
@param outbuf The address of the destination buffer
@param outbytes_left Input: the size of the output buffer
Output: the amount of the output buffer not yet used
@remark
Returns APR_ENOTIMPL if charset transcoding is not available
in this instance of apr-util (i.e., APR_HAS_XLATE is undefined).
Returns APR_INCOMPLETE if the input buffer ends in an incomplete
multi-byte character.
Convert a single-byte character from one charset to another.
@param convset The handle allocated by apr_xlate_open, specifying the
parameters of conversion
@param inchar The single-byte character to convert.
@warning This only works when converting between single-byte character sets.
-1 will be returned if the conversion can’t be performed.
Set up for converting text from one charset to another.
@param convset The handle to be filled in by this function
@param topage The name of the target charset
@param frompage The name of the source charset
@param pool The pool to use
@remark
Specify APR_DEFAULT_CHARSET for one of the charset
names to indicate the charset of the source code at
compile time. This is useful if there are literal
strings in the source code which must be translated
according to the charset of the source code.
APR_DEFAULT_CHARSET is not useful if the source code
of the caller was not encoded in the same charset as
APR at compile time.
Find out whether or not the specified conversion is single-byte-only.
@param convset The handle allocated by apr_xlate_open, specifying the
parameters of conversion
@param onoff Output: whether or not the conversion is single-byte-only
@remark
Return APR_ENOTIMPL if charset transcoding is not available
in this instance of apr-util (i.e., APR_HAS_XLATE is undefined).
return the URI’s (existing) index, or insert it and return a new index
@param uri_array array to insert into
@param uri The uri to insert
@return int The uri’s index
Parse a File, producing a xml_doc
@param p The pool for allocating the parse results.
@param parser A pointer to *parser (needed so calling function can get
errors), will be set to NULL on successful completion.
@param ppdoc A pointer to *apr_xml_doc (which has the parsed results in it)
@param xmlfd A file to read from.
@param buffer_length Buffer length which would be suitable
@return Any errors found during parsing.
Terminate the parsing and return the result
@param parser The XML parser for parsing this data.
@param pdoc The resulting parse information. May be NULL to simply
terminate the parsing without fetching the info.
@return Any errors found during the final stage of parsing.
@remark Use apr_xml_parser_geterror() to get more error information.
Feed input into the parser
@param parser The XML parser for parsing this data.
@param data The data to parse.
@param len The length of the data.
@return Any errors found during parsing.
@remark Use apr_xml_parser_geterror() to get more error information.
Fetch additional error information from the parser.
@param parser The XML parser to query for errors.
@param errbuf A buffer for storing error text.
@param errbufsize The length of the error text buffer.
@return The error buffer
quote an XML string
Replace ‘<’, ‘>’, and ‘&’ with ‘<’, ‘>’, and ‘&’.
@param p The pool to allocate out of
@param s The string to quote
@param quotes If quotes is true, then replace ‘"’ with ‘"’.
@return The quoted string
@note If the string does not contain special characters, it is not
duplicated into the pool and the original string is returned.
Converts an XML element tree to flat text
@param p The pool to allocate out of
@param elem The XML element to convert
@param style How to covert the XML. One of:
The prototype for APR child errfn functions. (See the description
of apr_procattr_child_errfn_set() for more information.)
It is passed the following parameters:
@param pool Pool associated with the apr_proc_t. If your child
error function needs user data, associate it with this
pool.
@param err APR error code describing the error
@param description Text description of type of processing which failed
apr_filetype_e values for the filetype member of the
apr_file_info_t structure
@warning Not all of the filetypes below can be determined.
For example, a given platform might not correctly report
a socket descriptor as APR_SOCK if that type isn’t
well-identified on that platform. In such cases where
a filetype exists but cannot be described by the recognized
flags below, the filetype will be APR_UNKFILE. If the
filetype member is not determined, the type will be APR_NOFILE.
Callback functions for calculating hash values.
@param key The key.
@param klen The length of the key, or APR_HASH_KEY_STRING to use the string
length. If APR_HASH_KEY_STRING then returns the actual key length.
Declaration prototype for the iterator callback function of apr_table_do()
and apr_table_vdo().
@param rec The data passed as the first argument to apr_table_[v]do()
@param key The key from this iteration of the table
@param value The value from this iteration of the table
@remark Iteration continues while this callback function returns non-zero.
To export the callback function for apr_table_[v]do() it must be declared
in the _NONSTD convention.
@see apr_table_do @see apr_table_vdo