GME  13
Classes | Defines | Typedefs | Functions
Internal Memory Allocation

Classes

struct  apr_memnode_t

Defines

#define APR_MEMNODE_T_SIZE   APR_ALIGN_DEFAULT(sizeof(apr_memnode_t))
#define APR_ALLOCATOR_MAX_FREE_UNLIMITED   0

Typedefs

typedef struct apr_allocator_t apr_allocator_t
typedef struct apr_memnode_t apr_memnode_t

Functions

 APR_DECLARE (apr_status_t) apr_allocator_create(apr_allocator_t **allocator) __attribute__((nonnull(1)))
 APR_DECLARE (void) apr_allocator_destroy(apr_allocator_t *allocator) __attribute__((nonnull(1)))
 APR_DECLARE (apr_memnode_t *) apr_allocator_alloc(apr_allocator_t *allocator
apr_size_t size __attribute__ ((nonnull(1)))
apr_memnode_t *memnode __attribute__ ((nonnull(1, 2)))
 APR_DECLARE (apr_pool_t *) apr_allocator_owner_get(apr_allocator_t *allocator) __attribute__((nonnull(1)))

Define Documentation

Symbolic constants

Definition at line 67 of file apr_allocator.h.

The base size of a memory node - aligned.

Definition at line 64 of file apr_allocator.h.


Typedef Documentation

the allocator structure

Definition at line 41 of file apr_allocator.h.

typedef struct apr_memnode_t apr_memnode_t

the structure which holds information about the allocation

Definition at line 43 of file apr_allocator.h.


Function Documentation

apr_size_t size __attribute__ ( (nonnull(1))  )
apr_memnode_t* memnode __attribute__ ( (nonnull(1, 2))  )

Create a new allocator

Parameters:
allocatorThe allocator we have just created.

Get the value of an environment variable

Parameters:
valuethe returned value, allocated from pool
envvarthe name of the environment variable
poolwhere to allocate value and any temporary storage from

Set the value of an environment variable

Parameters:
envvarthe name of the environment variable
valuethe value to set
poolwhere to allocate temporary storage from

Delete a variable from the environment

Parameters:
envvarthe name of the environment variable
poolwhere to allocate temporary storage from

get the specified file's stats. The file is specified by filename, instead of using a pre-opened file.

Parameters:
finfoWhere to store the information about the file, which is never touched if the call fails.
fnameThe name of the file to stat.
wantedThe desired apr_finfo_t fields, as a bit flag of APR_FINFO_ values
poolthe pool to use to allocate the new file.
Note:
If APR_INCOMPLETE is returned all the fields in finfo may not be filled in, and you need to check the finfo->valid bitmask to verify that what you're looking for is there.

Open the specified directory.

Parameters:
new_dirThe opened directory descriptor.
dirnameThe full path to the directory (use / on all systems)
poolThe pool to use.

close the specified directory.

Parameters:
thedirthe directory descriptor to close.

Read the next entry from the specified directory.

Parameters:
finfothe file info structure and filled in by apr_dir_read
wantedThe desired apr_finfo_t fields, as a bit flag of APR_FINFO_ values
thedirthe directory descriptor returned from apr_dir_open
Remarks:
No ordering is guaranteed for the entries read.
Note:
If APR_INCOMPLETE is returned all the fields in finfo may not be filled in, and you need to check the finfo->valid bitmask to verify that what you're looking for is there. When no more entries are available, APR_ENOENT is returned.

Rewind the directory to the first entry.

Parameters:
thedirthe directory descriptor to rewind.

Extract the rootpath from the given filepath

Parameters:
rootpaththe root file path returned with APR_SUCCESS or APR_EINCOMPLETE
filepaththe pathname to parse for its root component
flagsthe desired rules to apply, from
      APR_FILEPATH_NATIVE    Use native path seperators (e.g. '\' on Win32)
      APR_FILEPATH_TRUENAME  Tests that the root exists, and makes it proper
 
pthe pool to allocate the new path string from
Remarks:
on return, filepath points to the first non-root character in the given filepath. In the simplest example, given a filepath of "/foo", returns the rootpath of "/" and filepath points at "foo". This is far more complex on other platforms, which will canonicalize the root form to a consistant format, given the APR_FILEPATH_TRUENAME flag, and also test for the validity of that root (e.g., that a drive d:/ or network share //machine/foovol/). The function returns APR_ERELATIVE if filepath isn't rooted (an error), APR_EINCOMPLETE if the root path is ambigious (but potentially legitimate, e.g. "/" on Windows is incomplete because it doesn't specify the drive letter), or APR_EBADPATH if the root is simply invalid. APR_SUCCESS is returned if filepath is an absolute path.

Merge additional file path onto the previously processed rootpath

Parameters:
newpaththe merged paths returned
rootpaththe root file path (NULL uses the current working path)
addpaththe path to add to the root path
flagsthe desired APR_FILEPATH_ rules to apply when merging
pthe pool to allocate the new path string from
Remarks:
if the flag APR_FILEPATH_TRUENAME is given, and the addpath contains wildcard characters ('*', '?') on platforms that don't support such characters within filenames, the paths will be merged, but the result code will be APR_EPATHWILD, and all further segments will not reflect the true filenames including the wildcard and following segments.

Split a search path into separate components

Parameters:
patheltsthe returned components of the search path
liststrthe search path (e.g., getenv("PATH"))
pthe pool to allocate the array and path components from
Remarks:
empty path componenta do not become part of pathelts.
the path separator in liststr is system specific; e.g., ':' on Unix, ';' on Windows, etc.

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

Parameters:
liststrthe returned search path; may be NULL if pathelts is empty
patheltsthe components of the search path
pthe pool to allocate the search path from
Remarks:
emtpy strings in the source array are ignored.
the path separator in liststr is system specific; e.g., ':' on Unix, ';' on Windows, etc.

Return the default file path (for relative file names)

Parameters:
paththe default path string returned
flagsoptional flag APR_FILEPATH_NATIVE to retrieve the default file path in os-native format.
pthe pool to allocate the default path string from

Set the default file path (for relative file names)

Parameters:
paththe default path returned
pthe pool to allocate any working storage

Determine the encoding used internally by the FilePath functions

Parameters:
stylepoints to a variable which receives the encoding style flag
pthe pool to allocate any working storage
Remarks:
Use apr_os_locale_encoding and/or apr_os_default_encoding to get the name of the path encoding if it's not UTF-8.

Open the specified file.

Parameters:
newfThe opened file descriptor.
fnameThe full path to the file (using / on all systems)
flagOr'ed value of:
         APR_READ              open for reading
         APR_WRITE             open for writing
         APR_CREATE            create the file if not there
         APR_APPEND            file ptr is set to end prior to all writes
         APR_TRUNCATE          set length to zero if file exists
         APR_BINARY            not a text file (This flag is ignored on 
                               UNIX because it has no meaning)
         APR_BUFFERED          buffer the data.  Default is non-buffered
         APR_EXCL              return error if APR_CREATE and file exists
         APR_DELONCLOSE        delete the file after closing.
         APR_XTHREAD           Platform dependent tag to open the file
                               for use across multiple threads
         APR_SHARELOCK         Platform dependent support for higher
                               level locked read/write access to support
                               writes across process/machines
         APR_FILE_NOCLEANUP    Do not register a cleanup with the pool 
                               passed in on the pool argument (see below).
                               The apr_os_file_t handle in apr_file_t will not
                               be closed when the pool is destroyed.
         APR_SENDFILE_ENABLED  Open with appropriate platform semantics
                               for sendfile operations.  Advisory only,
                               apr_socket_sendfile does not check this flag.
 
permAccess permissions for file.
poolThe pool to use.
Remarks:
If perm is APR_OS_DEFAULT and the file is being created, appropriate default permissions will be used.
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().

Close the specified file.

Parameters:
fileThe file descriptor to close.

Delete the specified file.

Parameters:
pathThe full path to the file (using / on all systems)
poolThe pool to use.
Remarks:
If the file is open, it won't be removed until all instances are closed.

Rename the specified file.

Parameters:
from_pathThe full path to the original file (using / on all systems)
to_pathThe full path to the new file (using / on all systems)
poolThe pool to use.
Warning:
If a file exists at the new location, then it will be overwritten. Moving files or directories across devices may not be possible.

Create a hard link to the specified file.

Parameters:
from_pathThe full path to the original file (using / on all systems)
to_pathThe full path to the new file (using / on all systems)
Remarks:
Both files must reside on the same device.

Copy the specified file to another file.

Parameters:
from_pathThe full path to the original file (using / on all systems)
to_pathThe full path to the new file (using / on all systems)
permsAccess permissions for the new file if it is created. In place of the usual or'd combination of file permissions, the value APR_FILE_SOURCE_PERMS may be given, in which case the source file's permissions are copied.
poolThe pool to use.
Remarks:
The new file does not need to exist, it will be created if required.
Warning:
If the new file already exists, its contents will be overwritten.

Append the specified file to another file.

Parameters:
from_pathThe full path to the source file (use / on all systems)
to_pathThe full path to the destination file (use / on all systems)
permsAccess permissions for the destination file if it is created. In place of the usual or'd combination of file permissions, the value APR_FILE_SOURCE_PERMS may be given, in which case the source file's permissions are copied.
poolThe pool to use.
Remarks:
The new file does not need to exist, it will be created if required.

Are we at the end of the file

Parameters:
fptrThe apr file we are testing.
Remarks:
Returns APR_EOF if we are at the end of file, APR_SUCCESS otherwise.

Open standard error as an apr file pointer.

Parameters:
thefileThe apr file to use as stderr.
poolThe pool to allocate the file out of.
Remarks:
The only reason that the apr_file_open_std* functions exist is that you may not always have a stderr/out/in on Windows. This is generally a problem with newer versions of Windows and services.
The other problem is that the C library functions generally work differently on Windows and Unix. So, by using apr_file_open_std* functions, you can get a handle to an APR struct that works with the APR functions which are supposed to work identically on all platforms.

open standard output as an apr file pointer.

Parameters:
thefileThe apr file to use as stdout.
poolThe pool to allocate the file out of.
Remarks:
See remarks for apr_file_open_stderr.

open standard input as an apr file pointer.

Parameters:
thefileThe apr file to use as stdin.
poolThe pool to allocate the file out of.
Remarks:
See remarks for apr_file_open_stderr.

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

Parameters:
thefileThe apr file to use as stderr.
flagsThe flags to open the file with. Only the APR_EXCL, APR_BUFFERED, APR_XTHREAD, APR_SHARELOCK, APR_SENDFILE_ENABLED and APR_LARGEFILE flags should be used. The APR_WRITE flag will be set unconditionally.
poolThe pool to allocate the file out of.
Remarks:
See remarks for apr_file_open_stderr.

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

Parameters:
thefileThe apr file to use as stdout.
flagsThe flags to open the file with. Only the APR_EXCL, APR_BUFFERED, APR_XTHREAD, APR_SHARELOCK, APR_SENDFILE_ENABLED and APR_LARGEFILE flags should be used. The APR_WRITE flag will be set unconditionally.
poolThe pool to allocate the file out of.
Remarks:
See remarks for apr_file_open_stderr.

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

Parameters:
thefileThe apr file to use as stdin.
flagsThe flags to open the file with. Only the APR_EXCL, APR_BUFFERED, APR_XTHREAD, APR_SHARELOCK, APR_SENDFILE_ENABLED and APR_LARGEFILE flags should be used. The APR_READ flag will be set unconditionally.
poolThe pool to allocate the file out of.
Remarks:
See remarks for apr_file_open_stderr.

Read data from the specified file.

Parameters:
thefileThe file descriptor to read from.
bufThe buffer to store the data to.
nbytesOn entry, the number of bytes to read; on exit, the number of bytes read.
Remarks:
apr_file_read will read up to the specified number of bytes, but never more. If there isn't enough data to fill that number of bytes, all of the available data is read. The third argument is modified to reflect the number of bytes read. If a char was put back into the stream via ungetc, it will be the first character returned.
It is not possible for both bytes to be read and an APR_EOF or other error to be returned. APR_EINTR is never returned.

Write data to the specified file.

Parameters:
thefileThe file descriptor to write to.
bufThe buffer which contains the data.
nbytesOn entry, the number of bytes to write; on exit, the number of bytes written.
Remarks:
apr_file_write will write up to the specified number of bytes, but never more. If the OS cannot write that many bytes, it will write as many as it can. The third argument is modified to reflect the * number of bytes written.
It is possible for both bytes to be written and an error to be returned. APR_EINTR is never returned.

Write data from iovec array to the specified file.

Parameters:
thefileThe file descriptor to write to.
vecThe array from which to get the data to write to the file.
nvecThe 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.
nbytesThe number of bytes written.
Remarks:
It is possible for both bytes to be written and an error to be returned. APR_EINTR is never returned.
apr_file_writev is available even if the underlying operating system doesn't provide writev().

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

Parameters:
thefileThe file descriptor to read from.
bufThe buffer to store the data to.
nbytesThe number of bytes to read.
bytes_readIf non-NULL, this will contain the number of bytes read.
Remarks:
apr_file_read will read up to the specified number of bytes, but never more. If there isn't enough data to fill that number of bytes, then the process/thread will block until it is available or EOF is reached. If a char was put back into the stream via ungetc, it will be the first character returned.
It is possible for both bytes to be read and an error to be returned. And if *bytes_read is less than nbytes, an accompanying error is _always_ returned.
APR_EINTR is never returned.

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

Parameters:
thefileThe file descriptor to write to.
bufThe buffer which contains the data.
nbytesThe number of bytes to write.
bytes_writtenIf non-NULL, set to the number of bytes written.
Remarks:
apr_file_write will write up to the specified number of bytes, but never more. If the OS cannot write that many bytes, the process/thread will block until they can be written. Exceptional error such as "out of space" or "pipe closed" will terminate with an error.
It is possible for both bytes to be written and an error to be returned. And if *bytes_written is less than nbytes, an accompanying error is _always_ returned.
APR_EINTR is never returned.

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

Parameters:
thefileThe file descriptor to write to.
vecThe array from which to get the data to write to the file.
nvecThe 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.
nbytesThe number of bytes written.
Remarks:
apr_file_writev_full is available even if the underlying operating system doesn't provide writev().

Write a character into the specified file.

Parameters:
chThe character to write.
thefileThe file descriptor to write to

Read a character from the specified file.

Parameters:
chThe character to read into
thefileThe file descriptor to read from

Put a character back onto a specified stream.

Parameters:
chThe character to write.
thefileThe file descriptor to write to

Read a line from the specified file

Parameters:
strThe buffer to store the string in.
lenThe length of the string
thefileThe file descriptor to read from
Remarks:
The buffer will be NUL-terminated if any characters are stored. The newline at the end of the line will not be stripped.

Write the string into the specified file.

Parameters:
strThe string to write.
thefileThe file descriptor to write to

Flush the file's buffer.

Parameters:
thefileThe file descriptor to flush

Transfer all file modified data and metadata to disk.

Parameters:
thefileThe file descriptor to sync

Transfer all file modified data to disk.

Parameters:
thefileThe file descriptor to sync

Duplicate the specified file descriptor.

Parameters:
new_fileThe structure to duplicate into.
old_fileThe file to duplicate.
pThe pool to use for the new file.
Remarks:
*new_file must point to a valid apr_file_t, or point to NULL.

Duplicate the specified file descriptor and close the original

Parameters:
new_fileThe old file that is to be closed and reused
old_fileThe file to duplicate
pThe pool to use for the new file
Remarks:
new_file MUST point at a valid apr_file_t. It cannot be NULL.

Move the specified file descriptor to a new pool

Parameters:
new_filePointer in which to return the new apr_file_t
old_fileThe file to move
pThe pool to which the descriptor is to be moved
Remarks:
Unlike apr_file_dup2(), this function doesn't do an OS dup() operation on the underlying descriptor; it just moves the descriptor's apr_file_t wrapper to a new pool.
The new pool need not be an ancestor of old_file's pool.
After calling this function, old_file may not be used

Give the specified apr file handle a new buffer

Parameters:
thefileThe file handle that is to be modified
bufferThe buffer
bufsizeThe size of the buffer
Remarks:
It is possible to add a buffer to previously unbuffered file handles, the APR_BUFFERED flag will be added to the file handle's flags. Likewise, with buffer=NULL and bufsize=0 arguments it is possible to make a previously buffered file handle unbuffered.

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

Parameters:
thefileThe file descriptor
whereHow to move the pointer, one of:
            APR_SET  --  set the offset to offset
            APR_CUR  --  add the offset to the current position 
            APR_END  --  add the offset to the current file size 
 
offsetThe offset to move the pointer to.
Remarks:
The third argument is modified to be the offset the pointer was actually moved to.

Create an anonymous pipe.

Parameters:
inThe newly created pipe's file for reading.
outThe newly created pipe's file for writing.
poolThe pool to operate on.
Remarks:
By default, the returned file descriptors will be inherited by child processes created using apr_proc_create(). This can be changed using apr_file_inherit_unset().
Bug:
Some platforms cannot toggle between blocking and nonblocking, and when passing a pipe as a standard handle to an application which does not expect it, a non-blocking stream will fluxor the client app.
Deprecated:
See also:
apr_file_pipe_create_ex

Create an anonymous pipe which portably supports async timeout options.

Parameters:
inThe newly created pipe's file for reading.
outThe newly created pipe's file for writing.
blockingone of these values defined in apr_thread_proc.h;
poolThe pool to operate on.
       APR_FULL_BLOCK
       APR_READ_BLOCK
       APR_WRITE_BLOCK
       APR_FULL_NONBLOCK
 
Remarks:
By default, the returned file descriptors will be inherited by child processes created using apr_proc_create(). This can be changed using apr_file_inherit_unset().
Some platforms cannot toggle between blocking and nonblocking, and when passing a pipe as a standard handle to an application which does not expect it, a non-blocking stream will fluxor the client app. Use this function rather than apr_file_pipe_create to create pipes where one or both ends require non-blocking semantics.

Create a named pipe.

Parameters:
filenameThe filename of the named pipe
permThe permissions for the newly created pipe.
poolThe pool to operate on.

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

Parameters:
thepipeThe pipe we are getting a timeout for.
timeoutThe current timeout value in microseconds.

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

Parameters:
thepipeThe pipe we are setting a timeout on.
timeoutThe timeout value in microseconds. Values < 0 mean wait forever, 0 means do not wait at all.

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

Parameters:
thefileThe file to lock.
typeThe type of lock to establish on the file.

Remove any outstanding locks on the file.

Parameters:
thefileThe file to unlock.

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

Parameters:
new_pathThe path of the file.
thefileThe currently open file.

Return the data associated with the current file.

Parameters:
dataThe user data associated with the file.
keyThe key to use for retrieving data associated with this file.
fileThe currently open file.

Set the data associated with the current file.

Parameters:
fileThe currently open file.
dataThe user data to associate with the file.
keyThe key to use for associating data with the file.
cleanupThe cleanup routine to use when the file is destroyed.

set the specified file's permission bits.

Parameters:
fnameThe file (name) to apply the permissions to.
permsThe permission bits to apply to the file.
Warning:
Some platforms may not be able to apply all of the available permission bits; APR_INCOMPLETE will be returned if some permissions are specified which could not be set.
Platforms which do not implement this feature will return APR_ENOTIMPL.

Set attributes of the specified file.

Parameters:
fnameThe full path to the file (using / on all systems)
attributesOr'd combination of
            APR_FILE_ATTR_READONLY   - make the file readonly
            APR_FILE_ATTR_EXECUTABLE - make the file executable
            APR_FILE_ATTR_HIDDEN     - make the file hidden
 
attr_maskMask of valid bits in attributes.
poolthe pool to use.
Remarks:
This function should be used in preference to explicit manipulation of the file permissions, because the operations to provide these attributes are platform specific and may involve more than simply setting permission bits.
Warning:
Platforms which do not implement this feature will return APR_ENOTIMPL.

Set the mtime of the specified file.

Parameters:
fnameThe full path to the file (using / on all systems)
mtimeThe mtime to apply to the file.
poolThe pool to use.
Warning:
Platforms which do not implement this feature will return APR_ENOTIMPL.

Create a new directory on the file system.

Parameters:
paththe path for the directory to be created. (use / on all systems)
permPermissions for the new directory.
poolthe pool to use.

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

Parameters:
paththe path for the directory to be created. (use / on all systems)
permPermissions for the new directory.
poolthe pool to use.

Remove directory from the file system.

Parameters:
paththe path for the directory to be removed. (use / on all systems)
poolthe pool to use.
Remarks:
Removing a directory which is in-use (e.g., the current working directory, or during apr_dir_read, or with an open file) is not portable.

get the specified file's stats.

Parameters:
finfoWhere to store the information about the file.
wantedThe desired apr_finfo_t fields, as a bit flag of APR_FINFO_ values
thefileThe file to get information about.

Truncate the file's length to the specified offset

Parameters:
fpThe file to truncate
offsetThe offset to truncate to.
Remarks:
The read/write file offset is repositioned to offset.

Open a temporary file

Parameters:
fpThe apr file to use as a temporary file.
templThe template to use when creating a temp file.
flagsThe flags to open the file with. If this is zero, the file is opened with APR_CREATE | APR_READ | APR_WRITE | APR_EXCL | APR_DELONCLOSE
pThe pool to allocate the file out of.
Remarks:
This function generates a unique temporary file name from template. The last six characters of template must be XXXXXX and these are replaced with a string that makes the filename unique. Since it will be modified, template must not be a string constant, but should be declared as a character array.

Find an existing directory suitable as a temporary storage location.

Parameters:
temp_dirThe temp directory.
pThe pool to use for any necessary allocations.
Remarks:
This function uses an algorithm to search for a directory that an an application can use for temporary storage.

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.

Remarks:
See apr_app_initialize if this is an application, rather than a library consumer of apr.

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

Parameters:
argcPointer to the argc that may be corrected
argvPointer to the argv that may be corrected
envPointer to the env that may be corrected, may be NULL
Remarks:
See apr_initialize if this is a library consumer of apr. Otherwise, this call is identical to apr_initialize, and must be closed with a call to apr_terminate at the end of program execution.

Initialize the arguments for parsing by apr_getopt().

Parameters:
osThe options structure created for apr_getopt()
contThe pool to operate on
argcThe number of arguments to parse
argvThe array of arguments to parse
Remarks:
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().

Parameters:
osThe apr_opt_t structure returned by apr_getopt_init()
optsA string of characters that are acceptable options to the program. Characters followed by ":" are required to have an option associated
option_chThe next option character parsed
option_argThe argument following the option character:
Returns:
There are four potential status values on exit. They are:
             APR_EOF      --  No more options to parse
             APR_BADCH    --  Found a bad option character
             APR_BADARG   --  No argument followed the option flag
             APR_SUCCESS  --  The next option was found.
 

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

Parameters:
osThe apr_getopt_t structure created by apr_getopt_init()
optsA pointer to a list of apr_getopt_option_t structures, which can be initialized with { "name", optch, has_args }. has_args is nonzero if the option requires an argument. A structure with an optch value of 0 terminates the list.
option_chReceives the value of "optch" from the apr_getopt_option_t structure corresponding to the next option matched.
option_argReceives the argument following the option, if any.
Returns:
There are four potential status values on exit. They are:
             APR_EOF      --  No more options to parse
             APR_BADCH    --  Found a bad option character
             APR_BADARG   --  No argument followed the option flag
             APR_SUCCESS  --  The next option was found.
 
When APR_SUCCESS is returned, os->ind gives the index of the first non-option argument. On error, a message will be printed to stdout unless os->err is set to 0. If os->interleave is set to nonzero, options can come after arguments, and os->argv will be permuted to leave non-option arguments at the end (the original argv is unaffected).

Create and initialize a mutex that can be used to synchronize both processes and threads. Note: There is considerable overhead in using this API if only cross-process or cross-thread mutual exclusion is required. See apr_proc_mutex.h and apr_thread_mutex.h for more specialized lock routines.

Parameters:
mutexthe memory address where the newly created mutex will be stored.
fnameA file name to use if the lock mechanism requires one. This argument should always be provided. The lock code itself will determine if it should be used.
mechThe mechanism to use for the interprocess lock, if any; one of
            APR_LOCK_FCNTL
            APR_LOCK_FLOCK
            APR_LOCK_SYSVSEM
            APR_LOCK_POSIXSEM
            APR_LOCK_PROC_PTHREAD
            APR_LOCK_DEFAULT     pick the default mechanism for the platform
 
poolthe pool from which to allocate the mutex.
Warning:
Check APR_HAS_foo_SERIALIZE defines to see if the platform supports APR_LOCK_foo. Only APR_LOCK_DEFAULT is portable.

Re-open a mutex in a child process.

Parameters:
mutexThe newly re-opened mutex structure.
fnameA file name to use if the mutex mechanism requires one. This argument should always be provided. The mutex code itself will determine if it should be used. This filename should be the same one that was passed to apr_global_mutex_create().
poolThe pool to operate on.
Remarks:
This function must be called to maintain portability, even if the underlying lock mechanism does not require it.

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

Parameters:
mutexthe mutex on which to acquire the lock.

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

Parameters:
mutexthe mutex on which to attempt the lock acquiring.

Release the lock for the given mutex.

Parameters:
mutexthe mutex from which to release the lock.

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

Parameters:
mutexthe mutex to destroy.

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

Parameters:
compfunction will be invoked for every element in the hash table.
compThe function to run
recThe data to pass as the first argument to the function
htThe hash table to iterate over
Returns:
FALSE if one of the comp() iterations returned zero; TRUE if all iterations returned non-zero
See also:
apr_hash_do_callback_fn_t

apr_vformatter() is a generic printf-style formatting routine with some extensions.

Parameters:
flush_funcThe function to call when the buffer is full
cThe buffer to write to
fmtThe format string
apThe arguments to use to fill out the format string.
Remarks:
 The extensions are:

%pA takes a struct in_addr *, and prints it as a.b.c.d %pI takes an apr_sockaddr_t * and prints it as a.b.c.d:port or [ipv6-address]:port %pT takes an apr_os_thread_t * and prints it in decimal ('0' is printed if !APR_HAS_THREADS) %pt takes an apr_os_thread_t * and prints it in hexadecimal ('0' is printed if !APR_HAS_THREADS) %pm takes an apr_status_t * and prints the appropriate error string (from apr_strerror) corresponding to that error code. %pp takes a void * and outputs it in hex %pB takes a apr_uint32_t * as bytes and outputs it's apr_strfsize %pF same as above, but takes a apr_off_t * %pS same as above, but takes a apr_size_t *

 %pA, %pI, %pT, %pp are available from APR 1.0.0 onwards (and in 0.9.x).
 %pt is only available from APR 1.2.0 onwards.
 %pm, %pB, %pF and %pS are only available from APR 1.3.0 onwards.
 The %p hacks are to force gcc's printf warning code to skip
 over a pointer argument without complaining.  This does
 mean that the ANSI-style %p (output a void * in hex format) won't
 work as expected at all, but that seems to be a fair trade-off
 for the increased robustness of having printf-warnings work.
 Additionally, apr_vformatter allows for arbitrary output methods
 using the apr_vformatter_buff and flush_func.
 The apr_vformatter_buff has two elements curpos and endpos.
 curpos is where apr_vformatter will write the next byte of output.
 It proceeds writing output to curpos, and updating curpos, until
 either the end of output is reached, or curpos == endpos (i.e. the
 buffer is full).
 If the end of output is reached, apr_vformatter returns the
 number of bytes written.
 When the buffer is full, the flush_func is called.  The flush_func
 can return -1 to indicate that no further output should be attempted,
 and apr_vformatter will return immediately with -1.  Otherwise
 the flush_func should flush the buffer in whatever manner is
 appropriate, re apr_pool_t nitialize curpos and endpos, and return 0.
 Note that flush_func is only invoked as a result of attempting to
 write another byte at curpos when curpos >= endpos.  So for
 example, it's possible when the output exactly matches the buffer
 space available that curpos == endpos will be true when
 apr_vformatter returns.
 apr_vformatter does not call out to any other code, it is entirely
 self-contained.  This allows the callers to do things which are
 otherwise "unsafe".  For example, apr_psprintf uses the "scratch"
 space at the unallocated end of a block, and doesn't actually
 complete the allocation until apr_vformatter returns.  apr_psprintf
 would be completely broken if apr_vformatter were to call anything
 that used this same pool.  Similarly http_bprintf() uses the "scratch"
 space at the end of its output buffer, and doesn't actually note
 that the space is in use until it either has to flush the buffer
 or until apr_vformatter returns.
 

Display a prompt and read in the password from stdin.

Parameters:
promptThe prompt to display
pwbufBuffer to store the password
bufsizeThe length of the password buffer.
Remarks:
If the password entered must be truncated to fit in the provided buffer, APR_ENAMETOOLONG will be returned. Note that the bufsize paramater is passed by reference for no reason; its value will never be modified by the apr_password_get() function.

Create a socket.

Parameters:
new_sockThe new socket that has been set up.
familyThe address family of the socket (e.g., APR_INET).
typeThe type of the socket (e.g., SOCK_STREAM).
protocolThe protocol of the socket (e.g., APR_PROTO_TCP).
contThe pool for the apr_socket_t and associated storage.

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

Parameters:
thesocketThe socket to close
howHow to shutdown the socket. One of:
            APR_SHUTDOWN_READ         no longer allow read requests
            APR_SHUTDOWN_WRITE        no longer allow write requests
            APR_SHUTDOWN_READWRITE    no longer allow read or write requests 
 
See also:
apr_shutdown_how_e
Remarks:
This does not actually close the socket descriptor, it just controls which calls are still valid on the socket.

Close a socket.

Parameters:
thesocketThe socket to close

Bind the socket to its associated port

Parameters:
sockThe socket to bind
saThe socket address to bind to
Remarks:
This may be where we will find out if there is any other process using the selected port.

Listen to a bound socket for connections.

Parameters:
sockThe socket to listen on
backlogThe number of outstanding connections allowed in the sockets listen queue. If this value is less than zero, the listen queue size is set to zero.

Accept a new connection request

Parameters:
new_sockA 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.
sockThe socket we are listening on.
connection_poolThe pool for the new socket.

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

Parameters:
sockThe socket we wish to use for our side of the connection
saThe address of the machine we wish to connect to.

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

Parameters:
sockThe socket to check
atreadeofIf APR_SUCCESS is returned, *atreadeof is set to non-zero if a subsequent read would return APR_EOF
Returns:
an error is returned if it was not possible to determine the status, in which case *atreadeof is not changed.

Create apr_sockaddr_t from hostname, address family, and port.

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

Look up the host name from an apr_sockaddr_t.

Parameters:
hostnameThe hostname.
saThe apr_sockaddr_t.
flagsSpecial processing flags.

Parse hostname/IP address with scope id and port.

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

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

Parameters:
addrThe new buffer containing just the hostname. On output, *addr will be NULL if no hostname/IP address was specfied.
scope_idThe new buffer containing just the scope id. On output, *scope_id will be NULL if no scope id was specified.
portThe port number. On output, *port will be 0 if no port was specified. ### FIXME: 0 is a legal port (per RFC 1700). this should ### return something besides zero if the port is missing.
strThe input string to be parsed.
pThe pool from which *addr and *scope_id are allocated.
Remarks:
If scope id shouldn't be allowed, check for scope_id != NULL in addition to checking the return code. If addr/hostname should be required, check for addr == NULL in addition to checking the return code.

Get name of the current machine

Parameters:
bufA buffer to store the hostname in.
lenThe maximum length of the hostname that can be stored in the buffer provided. The suggested length is APRMAXHOSTLEN + 1.
contThe pool to use.
Remarks:
If the buffer was not large enough, an error will be returned.

Return the data associated with the current socket

Parameters:
dataThe user data associated with the socket.
keyThe key to associate with the user data.
sockThe currently open socket.

Set the data associated with the current socket.

Parameters:
sockThe currently open socket.
dataThe user data to associate with the socket.
keyThe key to associate with the data.
cleanupThe cleanup to call when the socket is destroyed.

Send data over a network.

Parameters:
sockThe socket to send the data over.
bufThe buffer which contains the data to be sent.
lenOn entry, the number of bytes to send; on exit, the number of bytes sent.
Remarks:
 This functions acts like a blocking write by default.  To change 
 this behavior, use apr_socket_timeout_set() or the APR_SO_NONBLOCK
 socket option.

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

 APR_EINTR is never returned.
 

Send multiple packets of data over a network.

Parameters:
sockThe socket to send the data over.
vecThe array of iovec structs containing the data to send
nvecThe number of iovec structs in the array
lenReceives the number of bytes actually written
Remarks:
 This functions acts like a blocking write by default.  To change 
 this behavior, use apr_socket_timeout_set() or the APR_SO_NONBLOCK
 socket option.
 The number of bytes actually sent is stored in argument 3.

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

 APR_EINTR is never returned.
 
Parameters:
sockThe socket to send from
whereThe apr_sockaddr_t describing where to send the data
flagsThe flags to use
bufThe data to send
lenThe length of the data to send

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

Parameters:
fromUpdated with the address from which the data was received
sockThe socket to use
flagsThe flags to use
bufThe buffer to use
lenThe length of the available buffer

Read data from a network.

Parameters:
sockThe socket to read the data from.
bufThe buffer to store the data in.
lenOn entry, the number of bytes to receive; on exit, the number of bytes received.
Remarks:
 This functions acts like a blocking read by default.  To change 
 this behavior, use apr_socket_timeout_set() or the APR_SO_NONBLOCK
 socket option.
 The number of bytes actually received is stored in argument 3.

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

 APR_EINTR is never returned.
 

Setup socket options for the specified socket

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

Setup socket timeout for the specified socket

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

Query socket options for the specified socket

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

Query socket timeout for the specified socket

Parameters:
sockThe socket to query
tSocket timeout returned from the query.

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

Parameters:
sockThe socket to query
atmarkIs set to true if socket is at the OOB/urgent mark, otherwise is set to false.

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

Parameters:
saThe returned apr_sockaddr_t.
whichWhether to retrieve the local or remote address
sockThe socket to use

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

Parameters:
addrThe IP address.
sockaddrThe socket address to reference.

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

Parameters:
sockaddrThe socket address to reference.

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

Parameters:
addr1One of the APR socket addresses.
addr2The other APR socket address.
Remarks:
The return value will be non-zero if the addresses are equivalent.

Return the type of the socket.

Parameters:
sockThe socket to query.
typeThe returned type (e.g., SOCK_STREAM).

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

Parameters:
sockaddrThe apr_sockaddr_t that will have its port set
servnameThe name of the service you wish to use

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

Parameters:
ipsubThe new ip-subnet representation
ipstrThe input IP address string
mask_or_numbitsThe input netmask or number-of-bits string, or NULL
pThe pool to allocate from

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

Parameters:
ipsubThe ip-subnet representation
saThe socket address to test
Returns:
non-zero if the socket address is within the subnet, 0 otherwise

Return the protocol of the socket.

Parameters:
sockThe socket to query.
protocolThe returned protocol (e.g., APR_PROTO_TCP).

Join a Multicast Group

Parameters:
sockThe socket to join a multicast group
joinThe address of the multicast group to join
ifaceAddress of the interface to use. If NULL is passed, the default multicast interface will be used. (OS Dependent)
sourceSource Address to accept transmissions from (non-NULL implies Source-Specific Multicast)

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

Parameters:
sockThe socket to leave a multicast group
addrThe address of the multicast group to leave
ifaceAddress of the interface to use. If NULL is passed, the default multicast interface will be used. (OS Dependent)
sourceSource Address to accept transmissions from (non-NULL implies Source-Specific Multicast)

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

Parameters:
sockThe socket to set the multicast ttl
ttlTime to live to Assign. 0-255, default=1
Remarks:
If the TTL is 0, packets will only be seen by sockets on the local machine, and only when multicast loopback is enabled.

Toggle IP Multicast Loopback

Parameters:
sockThe socket to set multicast loopback
opt0=disable, 1=enable

Set the Interface to be used for outgoing Multicast Transmissions.

Parameters:
sockThe socket to set the multicast interface on
ifaceAddress of the interface to use for Multicast

Set up a pollset object

Parameters:
pollsetThe pointer in which to return the newly created object
sizeThe maximum number of descriptors that this pollset can hold
pThe pool from which to allocate the pollset
flagsOptional flags to modify the operation of the pollset.
Remarks:
If flags contains APR_POLLSET_THREADSAFE, then a pollset is created on which it is safe to make concurrent calls to apr_pollset_add(), apr_pollset_remove() and apr_pollset_poll() from separate threads. This feature is only supported on some platforms; the apr_pollset_create() call will fail with APR_ENOTIMPL on platforms where it is not supported.
If flags contains APR_POLLSET_WAKEABLE, then a pollset is created with an additional internal pipe object used for the apr_pollset_wakeup() call. The actual size of pollset is in that case size + 1. This feature is only supported on some platforms; the apr_pollset_create() call will fail with APR_ENOTIMPL on platforms where it is not supported.
If flags contains APR_POLLSET_NOCOPY, then the apr_pollfd_t structures passed to apr_pollset_add() are not copied and must have a lifetime at least as long as the pollset.
Some poll methods (including APR_POLLSET_KQUEUE, APR_POLLSET_PORT, and APR_POLLSET_EPOLL) do not have a fixed limit on the size of the pollset. For these methods, the size parameter controls the maximum number of descriptors that will be returned by a single call to apr_pollset_poll().

Set up a pollset object

Parameters:
pollsetThe pointer in which to return the newly created object
sizeThe maximum number of descriptors that this pollset can hold
pThe pool from which to allocate the pollset
flagsOptional flags to modify the operation of the pollset.
methodPoll method to use. See apr_pollset_method_e. If this method cannot be used, the default method will be used unless the APR_POLLSET_NODEFAULT flag has been specified.
Remarks:
If flags contains APR_POLLSET_THREADSAFE, then a pollset is created on which it is safe to make concurrent calls to apr_pollset_add(), apr_pollset_remove() and apr_pollset_poll() from separate threads. This feature is only supported on some platforms; the apr_pollset_create_ex() call will fail with APR_ENOTIMPL on platforms where it is not supported.
If flags contains APR_POLLSET_WAKEABLE, then a pollset is created with additional internal pipe object used for the apr_pollset_wakeup() call. The actual size of pollset is in that case size + 1. This feature is only supported on some platforms; the apr_pollset_create_ex() call will fail with APR_ENOTIMPL on platforms where it is not supported.
If flags contains APR_POLLSET_NOCOPY, then the apr_pollfd_t structures passed to apr_pollset_add() are not copied and must have a lifetime at least as long as the pollset.
Some poll methods (including APR_POLLSET_KQUEUE, APR_POLLSET_PORT, and APR_POLLSET_EPOLL) do not have a fixed limit on the size of the pollset. For these methods, the size parameter controls the maximum number of descriptors that will be returned by a single call to apr_pollset_poll().

Destroy a pollset object

Parameters:
pollsetThe pollset to destroy

Add a socket or file descriptor to a pollset

Parameters:
pollsetThe pollset to which to add the descriptor
descriptorThe descriptor to add
Remarks:
If you set client_data in the descriptor, that value will be returned in the client_data field whenever this descriptor is signalled in apr_pollset_poll().
If the pollset has been created with APR_POLLSET_THREADSAFE and thread T1 is blocked in a call to apr_pollset_poll() for this same pollset that is being modified via apr_pollset_add() in thread T2, the currently executing apr_pollset_poll() call in T1 will either: (1) automatically include the newly added descriptor in the set of descriptors it is watching or (2) return immediately with APR_EINTR. Option (1) is recommended, but option (2) is allowed for implementations where option (1) is impossible or impractical.
If the pollset has been created with APR_POLLSET_NOCOPY, the apr_pollfd_t structure referenced by descriptor will not be copied and must have a lifetime at least as long as the pollset.
Do not add the same socket or file descriptor to the same pollset multiple times, even if the requested events differ for the different calls to apr_pollset_add(). If the events of interest for a descriptor change, you must first remove the descriptor from the pollset with apr_pollset_remove(), then add it again specifying all requested events.

Remove a descriptor from a pollset

Parameters:
pollsetThe pollset from which to remove the descriptor
descriptorThe descriptor to remove
Remarks:
If the pollset has been created with APR_POLLSET_THREADSAFE and thread T1 is blocked in a call to apr_pollset_poll() for this same pollset that is being modified via apr_pollset_remove() in thread T2, the currently executing apr_pollset_poll() call in T1 will either: (1) automatically exclude the newly added descriptor in the set of descriptors it is watching or (2) return immediately with APR_EINTR. Option (1) is recommended, but option (2) is allowed for implementations where option (1) is impossible or impractical.
apr_pollset_remove() cannot be used to remove a subset of requested events for a descriptor. The reqevents field in the apr_pollfd_t parameter must contain the same value when removing as when adding.

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

Parameters:
pollsetThe pollset to use
timeoutThe amount of time in microseconds to wait. This is a maximum, not a minimum. If a descriptor is signalled, the function will return before this time. If timeout is negative, the function will block until a descriptor is signalled or until apr_pollset_wakeup() has been called.
numNumber of signalled descriptors (output parameter)
descriptorsArray of signalled descriptors (output parameter)
Remarks:
APR_EINTR will be returned if the pollset has been created with APR_POLLSET_WAKEABLE, apr_pollset_wakeup() has been called while waiting for activity, and there were no signalled descriptors at the time of the wakeup call.
Multiple signalled conditions for the same descriptor may be reported in one or more returned apr_pollfd_t structures, depending on the implementation.
Bug:
With versions 1.4.2 and prior on Windows, a call with no descriptors and timeout will return immediately with the wrong error code.

Interrupt the blocked apr_pollset_poll() call.

Parameters:
pollsetThe pollset to use
Remarks:
If the pollset was not created with APR_POLLSET_WAKEABLE the return value is APR_EINIT.

Poll the descriptors in the poll structure

Parameters:
aprsetThe poll structure we will be using.
numsockThe number of descriptors we are polling
nsdsThe number of descriptors signalled (output parameter)
timeoutThe amount of time in microseconds to wait. This is a maximum, not a minimum. If a descriptor is signalled, the function will return before this time. If timeout is negative, the function will block until a descriptor is signalled or until apr_pollset_wakeup() has been called.
Remarks:
The number of descriptors signalled is returned in the third argument. This is a blocking call, and it will not return until either a descriptor has been signalled or the timeout has expired.
The rtnevents field in the apr_pollfd_t array will only be filled- in if the return value is APR_SUCCESS.
Bug:
With versions 1.4.2 and prior on Windows, a call with no descriptors and timeout will return immediately with the wrong error code.

Set up a pollcb object

Parameters:
pollcbThe pointer in which to return the newly created object
sizeThe maximum number of descriptors that a single _poll can return.
pThe pool from which to allocate the pollcb
flagsOptional flags to modify the operation of the pollcb.
Remarks:
Pollcb is only supported on some platforms; the apr_pollcb_create() call will fail with APR_ENOTIMPL on platforms where it is not supported.

Set up a pollcb object

Parameters:
pollcbThe pointer in which to return the newly created object
sizeThe maximum number of descriptors that a single _poll can return.
pThe pool from which to allocate the pollcb
flagsOptional flags to modify the operation of the pollcb.
methodPoll method to use. See apr_pollset_method_e. If this method cannot be used, the default method will be used unless the APR_POLLSET_NODEFAULT flag has been specified.
Remarks:
Pollcb is only supported on some platforms; the apr_pollcb_create_ex() call will fail with APR_ENOTIMPL on platforms where it is not supported.

Add a socket or file descriptor to a pollcb

Parameters:
pollcbThe pollcb to which to add the descriptor
descriptorThe descriptor to add
Remarks:
If you set client_data in the descriptor, that value will be returned in the client_data field whenever this descriptor is signalled in apr_pollcb_poll().
Unlike the apr_pollset API, the descriptor is not copied, and users must retain the memory used by descriptor, as the same pointer will be returned to them from apr_pollcb_poll.
Do not add the same socket or file descriptor to the same pollcb multiple times, even if the requested events differ for the different calls to apr_pollcb_add(). If the events of interest for a descriptor change, you must first remove the descriptor from the pollcb with apr_pollcb_remove(), then add it again specifying all requested events.

Remove a descriptor from a pollcb

Parameters:
pollcbThe pollcb from which to remove the descriptor
descriptorThe descriptor to remove
Remarks:
apr_pollcb_remove() cannot be used to remove a subset of requested events for a descriptor. The reqevents field in the apr_pollfd_t parameter must contain the same value when removing as when adding.

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

Parameters:
pollcbThe pollcb to use
timeoutThe amount of time in microseconds to wait. This is a maximum, not a minimum. If a descriptor is signalled, the function will return before this time. If timeout is negative, the function will block until a descriptor is signalled.
funcCallback function to call for each active descriptor.
batonOpaque baton passed to the callback function.
Remarks:
Multiple signalled conditions for the same descriptor may be reported in one or more calls to the callback function, depending on the implementation.
Bug:
With versions 1.4.2 and prior on Windows, a call with no descriptors and timeout will return immediately with the wrong error code.

Setup all of the internal structures required to use pools

Remarks:
Programs do NOT need to call this directly. APR will call this automatically from apr_initialize.

Create a new pool.

Parameters:
newpoolThe pool we have just created.
parentThe parent pool. If this is NULL, the new pool is a root pool. If it is non-NULL, the new pool will inherit all of its parent pool's attributes, except the apr_pool_t will be a sub-pool.
abort_fnA function to use if the pool cannot allocate more memory.
allocatorThe allocator to use with the new pool. If NULL the allocator of the parent pool will be used.
Remarks:
This function is thread-safe, in the sense that multiple threads can safely create subpools of the same parent pool concurrently. Similarly, a subpool can be created by one thread at the same time that another thread accesses the parent pool.

Create a new pool.

Deprecated:
See also:
apr_pool_create_unmanaged_ex.

Create a new unmanaged pool.

Parameters:
newpoolThe pool we have just created.
abort_fnA function to use if the pool cannot allocate more memory.
allocatorThe allocator to use with the new pool. If NULL a new allocator will be crated with newpool as owner.
Remarks:
An unmanaged pool is a special pool without a parent; it will NOT be destroyed upon apr_terminate. It must be explicitly destroyed by calling apr_pool_destroy, to prevent memory leaks. Use of this function is discouraged, think twice about whether you really really need it.

Debug version of apr_pool_create_ex.

Parameters:
newpool
See also:
apr_pool_create.
Parameters:
parent
See also:
apr_pool_create.
Parameters:
abort_fn
See also:
apr_pool_create.
Parameters:
allocator
See also:
apr_pool_create.
Parameters:
file_lineWhere the function is called from. This is usually APR_POOL__FILE_LINE__.
Remarks:
Only available when APR_POOL_DEBUG is defined. Call this directly if you have you apr_pool_create_ex calls in a wrapper function and wish to override the file_line argument to reflect the caller of your wrapper function. If you do not have apr_pool_create_ex in a wrapper, trust the macro and don't call apr_pool_create_ex_debug directly.

Debug version of apr_pool_create_core_ex.

Deprecated:
See also:
apr_pool_create_unmanaged_ex_debug.

Debug version of apr_pool_create_unmanaged_ex.

Parameters:
newpool
See also:
apr_pool_create_unmanaged.
Parameters:
abort_fn
See also:
apr_pool_create_unmanaged.
Parameters:
allocator
See also:
apr_pool_create_unmanaged.
Parameters:
file_lineWhere the function is called from. This is usually APR_POOL__FILE_LINE__.
Remarks:
Only available when APR_POOL_DEBUG is defined. Call this directly if you have you apr_pool_create_unmanaged_ex calls in a wrapper function and wish to override the file_line argument to reflect the caller of your wrapper function. If you do not have apr_pool_create_core_ex in a wrapper, trust the macro and don't call apr_pool_create_core_ex_debug directly.

Determine if pool a is an ancestor of pool b.

Parameters:
aThe pool to search
bThe pool to search for
Returns:
True if a is an ancestor of b, NULL is considered an ancestor of all pools.
Remarks:
if compiled with APR_POOL_DEBUG, this function will also return true if A is a pool which has been guaranteed by the caller (using apr_pool_join) to have a lifetime at least as long as some ancestor of pool B.

Set the data associated with the current pool

Parameters:
dataThe user data associated with the pool.
keyThe key to use for association
cleanupThe cleanup program to use to cleanup the data (NULL if none)
poolThe current pool
Warning:
The data to be attached to the pool should have a life span at least as long as the pool it is being attached to.

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

Set the data associated with the current pool

Parameters:
dataThe user data associated with the pool.
keyThe key to use for association
cleanupThe cleanup program to use to cleanup the data (NULL if none)
poolThe current pool
Note:
same as apr_pool_userdata_set(), except that this version doesn't make a copy of the key (this function is useful, for example, when the key is a string literal)
Warning:
This should NOT be used if the key could change addresses by any means between the apr_pool_userdata_setn() call and a subsequent apr_pool_userdata_get() on that key, such as if a static string is used as a userdata key in a DSO and the DSO could be unloaded and reloaded between the _setn() and the _get(). You MUST use apr_pool_userdata_set() in such cases.
More generally, the key and the data to be attached to the pool should have a life span at least as long as the pool itself.

Return the data associated with the current pool.

Parameters:
dataThe user data associated with the pool.
keyThe key for the data to retrieve
poolThe current pool.

convert the file from apr type to os specific type.

Parameters:
thefileThe os specific file we are converting to
fileThe apr file to convert.
Remarks:
On Unix, it is only possible to get a file descriptor from an apr file type.

convert the dir from apr type to os specific type.

Parameters:
thedirThe os specific dir we are converting to
dirThe apr dir to convert.

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

Parameters:
thesockThe socket to convert.
sockThe os specific equivalent of the apr socket..

Convert the proc mutex from os specific type to apr type

Parameters:
ospmutexThe os specific proc mutex we are converting to.
pmutexThe apr proc mutex to convert.

Get the exploded time in the platforms native format.

Parameters:
ostimethe native time format
aprtimethe time to convert

Get the imploded time in the platforms native format.

Parameters:
ostimethe native time format
aprtimethe time to convert

convert the shm from apr type to os specific type.

Parameters:
osshmThe os specific shm representation
shmThe apr shm to convert.

convert the file from os specific type to apr type.

Parameters:
fileThe apr file we are converting to.
thefileThe os specific file to convert
flagsThe flags that were used to open this file.
contThe pool to use if it is needed.
Remarks:
On Unix, it is only possible to put a file descriptor into an apr file type.

convert the file from os specific type to apr type.

Parameters:
fileThe apr file we are converting to.
thefileThe os specific pipe to convert
contThe pool to use if it is needed.
Remarks:
On Unix, it is only possible to put a file descriptor into an apr file type.

convert the file from os specific type to apr type.

Parameters:
fileThe apr file we are converting to.
thefileThe os specific pipe to convert
register_cleanupA cleanup will be registered on the apr_file_t to issue apr_file_close().
contThe pool to use if it is needed.
Remarks:
On Unix, it is only possible to put a file descriptor into an apr file type.

convert the dir from os specific type to apr type.

Parameters:
dirThe apr dir we are converting to.
thedirThe os specific dir to convert
contThe pool to use when creating to apr directory.

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

Parameters:
sockThe pool to use.
thesockThe socket to convert to.
contThe socket we are converting to an apr type.
Remarks:
If it is a true socket, it is best to call apr_os_sock_make() and provide APR with more information about the socket.

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

Parameters:
apr_sockThe new socket that has been set up
os_sock_infoThe os representation of the socket handle and other characteristics of the socket
contThe pool to use
Remarks:
If you only know the descriptor/handle or if it isn't really a true socket, use apr_os_sock_put() instead.

Convert the proc mutex from os specific type to apr type

Parameters:
pmutexThe apr proc mutex we are converting to.
ospmutexThe os specific proc mutex to convert.
contThe pool to use if it is needed.

Put the imploded time in the APR format.

Parameters:
aprtimethe APR time format
ostimethe time to convert
contthe pool to use if necessary

Put the exploded time in the APR format.

Parameters:
aprtimethe APR time format
ostimethe time to convert
contthe pool to use if necessary

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

Parameters:
shmThe apr shm representation of osshm
osshmThe os specific shm identity
contThe pool to use if it is needed.
Remarks:
On fork()ed architectures, this is typically nothing more than the memory block mapped. On non-fork architectures, this is typically some internal handle to pass the mapping from process to process.

Create and initialize a mutex that can be used to synchronize processes.

Parameters:
mutexthe memory address where the newly created mutex will be stored.
fnameA file name to use if the lock mechanism requires one. This argument should always be provided. The lock code itself will determine if it should be used.
mechThe mechanism to use for the interprocess lock, if any; one of
            APR_LOCK_FCNTL
            APR_LOCK_FLOCK
            APR_LOCK_SYSVSEM
            APR_LOCK_POSIXSEM
            APR_LOCK_PROC_PTHREAD
            APR_LOCK_DEFAULT     pick the default mechanism for the platform
 
poolthe pool from which to allocate the mutex.
See also:
apr_lockmech_e
Warning:
Check APR_HAS_foo_SERIALIZE defines to see if the platform supports APR_LOCK_foo. Only APR_LOCK_DEFAULT is portable.

Re-open a mutex in a child process.

Parameters:
mutexThe newly re-opened mutex structure.
fnameA file name to use if the mutex mechanism requires one. This argument should always be provided. The mutex code itself will determine if it should be used. This filename should be the same one that was passed to apr_proc_mutex_create().
poolThe pool to operate on.
Remarks:
This function must be called to maintain portability, even if the underlying lock mechanism does not require it.

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

Parameters:
mutexthe mutex on which to acquire the lock.

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

Parameters:
mutexthe mutex on which to attempt the lock acquiring.

Release the lock for the given mutex.

Parameters:
mutexthe mutex from which to release the lock.

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

Parameters:
mutexthe mutex to destroy.

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

Parameters:
mutexthe mutex to destroy.
Note:
This function is generally used to kill a cleanup on an already created mutex

Generate cryptographically insecure random bytes.

Parameters:
gThe RNG state
randomBuffer to fill with random bytes
bytesLength of buffer in bytes

Generate cryptographically secure random bytes.

Parameters:
gThe RNG state
randomBuffer to fill with random bytes
bytesLength of buffer in bytes

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

Parameters:
rThe RNG state

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

Parameters:
rThe PRNG state

Create and make accessable a shared memory segment.

Parameters:
mThe shared memory structure to create.
reqsizeThe desired size of the segment.
filenameThe file to use for shared memory on platforms that require it.
poolthe pool from which to allocate the shared memory structure.
Remarks:
A note about Anonymous vs. Named shared memory segments: Not all plaforms support anonymous shared memory segments, but in some cases it is prefered over other types of shared memory implementations. Passing a NULL 'file' parameter to this function will cause the subsystem to use anonymous shared memory segments. If such a system is not available, APR_ENOTIMPL is returned.
A note about allocation sizes: On some platforms it is necessary to store some metainformation about the segment within the actual segment. In order to supply the caller with the requested size it may be necessary for the implementation to request a slightly greater segment length from the subsystem. In all cases, the apr_shm_baseaddr_get() function will return the first usable byte of memory.

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

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

Destroy a shared memory segment and associated memory.

Parameters:
mThe shared memory segment structure to destroy.

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

Parameters:
mThe shared memory structure to create.
filenameThe file used to create the original segment. (This MUST match the original filename.)
poolthe pool from which to allocate the shared memory structure for this process.

Detach from a shared memory segment without destroying it.

Parameters:
mThe shared memory structure representing the segment to detach from.

Create and initialize a new procattr variable

Parameters:
new_attrThe newly created procattr.
contThe pool to use

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

Parameters:
attrThe procattr we care about.
inShould stdin be a pipe back to the parent?
outShould stdout be a pipe back to the parent?
errShould stderr be a pipe back to the parent?
Note:
If APR_NO_PIPE, there will be no special channel, the child inherits the parent's corresponding stdio stream. If APR_NO_FILE is specified, that corresponding stream is closed in the child (and will be INVALID_HANDLE_VALUE when inspected on Win32). This can have ugly side effects, as the next file opened in the child on Unix will fall into the stdio stream fd slot!

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

Parameters:
attrThe procattr we care about.
child_inapr_file_t value to use as child_in. Must be a valid file.
parent_inapr_file_t value to use as parent_in. Must be a valid file.
Remarks:
This is NOT a required initializer function. This is useful if you have already opened a pipe (or multiple files) that you wish to use, perhaps persistently across multiple process invocations - such as a log file. You can save some extra function calls by not creating your own pipe since this creates one in the process space for you.
Bug:
Note that calling this function with two NULL files on some platforms creates an APR_FULL_BLOCK pipe, but this behavior is neither portable nor is it supported.
See also:
apr_procattr_io_set instead for simple pipes.

Set the child_out and parent_out values to existing apr_file_t values.

Parameters:
attrThe procattr we care about.
child_outapr_file_t value to use as child_out. Must be a valid file.
parent_outapr_file_t value to use as parent_out. Must be a valid file.
Remarks:
This is NOT a required initializer function. This is useful if you have already opened a pipe (or multiple files) that you wish to use, perhaps persistently across multiple process invocations - such as a log file.
Bug:
Note that calling this function with two NULL files on some platforms creates an APR_FULL_BLOCK pipe, but this behavior is neither portable nor is it supported.
See also:
apr_procattr_io_set instead for simple pipes.

Set the child_err and parent_err values to existing apr_file_t values.

Parameters:
attrThe procattr we care about.
child_errapr_file_t value to use as child_err. Must be a valid file.
parent_errapr_file_t value to use as parent_err. Must be a valid file.
Remarks:
This is NOT a required initializer function. This is useful if you have already opened a pipe (or multiple files) that you wish to use, perhaps persistently across multiple process invocations - such as a log file.
Bug:
Note that calling this function with two NULL files on some platforms creates an APR_FULL_BLOCK pipe, but this behavior is neither portable nor is it supported.
See also:
apr_procattr_io_set instead for simple pipes.

Set which directory the child process should start executing in.

Parameters:
attrThe procattr we care about.
dirWhich dir to start in. By default, this is the same dir as the parent currently resides in, when the createprocess call is made.

Set what type of command the child process will call.

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

Determine if the child should start in detached state.

Parameters:
attrThe procattr we care about.
detachShould the child start in detached state? Default is no.

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

Parameters:
attrThe procattr describing the child process to be created.
errfnThe function to call in the child process.
Remarks:
At the present time, it will only be called from apr_proc_create() on platforms where fork() is used. It will never be called on other platforms, on those platforms apr_proc_create() will return the error in the parent process rather than invoke the callback in the now-forked child process.

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

Parameters:
attrThe procattr describing the child process to be created.
chkFlag to indicate whether or not extra work should be done to try to report failures to the caller.
Remarks:
This flag only affects apr_proc_create() on platforms where fork() is used. This leads to extra overhead in the calling process, but that may help the application handle such errors more gracefully.

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

Parameters:
attrThe procattr we care about.
addrspaceShould the child start in its own address space? Default is no on NetWare and yes on other platforms.

Set the username used for running process

Parameters:
attrThe procattr we care about.
usernameThe username used
passwordUser password if needed. Password is needed on WIN32 or any other platform having APR_PROCATTR_USER_SET_REQUIRES_PASSWORD set.

Set the group used for running process

Parameters:
attrThe procattr we care about.
groupnameThe group name used

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

Parameters:
new_procThe resulting process handle.
prognameThe program to run
argsthe arguments to pass to the new program. The first one should be the program name.
envThe 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.
attrthe procattr we should use to determine how to create the new process
poolThe pool to use.
Note:
This function returns without waiting for the new process to terminate; use apr_proc_wait for that.

Wait for a child process to die

Parameters:
procThe process handle that corresponds to the desired child process
exitcodeThe 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.
exitwhyWhy the child died, the bitwise or of:
            APR_PROC_EXIT         -- process terminated normally
            APR_PROC_SIGNAL       -- process was killed by a signal
            APR_PROC_SIGNAL_CORE  -- process was killed by a signal, and
                                     generated a core dump.
 
waithowHow should we wait. One of:
            APR_WAIT   -- block until the child process dies.
            APR_NOWAIT -- return immediately regardless of if the 
                          child is dead or not.
 
Remarks:
The childs status is in the return code to this process. It is one of:
            APR_CHILD_DONE     -- child is no longer running.
            APR_CHILD_NOTDONE  -- child is still running.
 

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

Parameters:
procPointer to NULL on entry, will be filled out with child's information
exitcodeThe 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.
exitwhyWhy the child died, the bitwise or of:
            APR_PROC_EXIT         -- process terminated normally
            APR_PROC_SIGNAL       -- process was killed by a signal
            APR_PROC_SIGNAL_CORE  -- process was killed by a signal, and
                                     generated a core dump.
 
waithowHow should we wait. One of:
            APR_WAIT   -- block until the child process dies.
            APR_NOWAIT -- return immediately regardless of if the 
                          child is dead or not.
 
pPool to allocate child information out of.
Bug:
Passing proc as a *proc rather than **proc was an odd choice for some platforms... this should be revisited in 1.0

Detach the process from the controlling terminal.

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

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

Parameters:
procThe process to check
reasonThe reason code to pass to the maintenance function
statusThe status to pass to the maintenance function
Remarks:
An example of code using this behavior;
 rv = apr_proc_wait_all_procs(&proc, &exitcode, &status, APR_WAIT, p);
 if (APR_STATUS_IS_CHILD_DONE(rv)) {
 #if APR_HAS_OTHER_CHILD
     if (apr_proc_other_child_alert(&proc, APR_OC_REASON_DEATH, status)
             == APR_SUCCESS) {
         ;  (already handled)
     }
     else
 #endif
         [... handling non-otherchild processes death ...]
 

Terminate a process.

Parameters:
procThe process to terminate.
sigHow to kill the process.

convert an ansi time_t to an apr_time_t

Parameters:
resultthe resulting apr_time_t
inputthe time_t to convert

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

Parameters:
resultthe exploded time
inputthe time to explode
offsthe number of seconds offset to apply

convert a time to its human readable components in GMT timezone

Parameters:
resultthe exploded time
inputthe time to explode

convert a time to its human readable components in local timezone

Parameters:
resultthe exploded time
inputthe time to explode

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

Parameters:
resultthe resulting imploded time
inputthe input exploded time

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

Parameters:
resultthe resulting imploded time
inputthe input exploded time

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

Parameters:
date_strString to write to.
tthe time to convert

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

Parameters:
date_strString to write to.
tthe time to convert

formats the exploded time according to the format specified

Parameters:
sstring to write to
retsizeThe length of the returned string
maxThe maximum length of the string
formatThe format for the time string
tmThe time to convert
APR_DECLARE ( void  )

Destroy an allocator

Parameters:
allocatorThe allocator to be destroyed
Remarks:
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.

Parameters:
allocatorThe allocator to give the mem back to
memnodeThe memory node to return

Set the owner of the allocator

Parameters:
allocatorThe allocator to set the owner for
poolThe pool that is to own the allocator
Remarks:
Typically pool is the highest level pool using the allocator

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

Parameters:
allocatorThe allocator the set the threshold on
sizeThe threshold. 0 == unlimited.

Allocate a block of mem from the allocator

Parameters:
allocatorThe allocator to allocate from
sizeThe size of the mem to allocate (excluding the memnode structure)

Get the current owner of the allocator

Parameters:
allocatorThe allocator to get the owner from