GME  13
Functions | Variables
Library initialization and termination

Functions

 APR_DECLARE (apr_status_t) apr_initialize(void)
 APR_DECLARE_NONSTD (void) apr_terminate(void)
 APR_DECLARE (void) apr_terminate2(void)

Variables

char const *const ** argv
char const *const char const
*const ** 
env

Function Documentation

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

Tear down any APR internal data structures which aren't torn down automatically, same as apr_terminate

Remarks:
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 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.

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.

Associate a value with a key in a hash table.

Parameters:
htThe hash table
keyPointer to the key
klenLength of the key. Can be APR_HASH_KEY_STRING to use the string length.
valValue to associate with the key
Remarks:
If the value is NULL the hash entry is deleted.

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

Parameters:
hiThe iteration state
keyReturn pointer for the pointer to the key.
klenReturn pointer for the key length.
valReturn pointer for the associated value.
Remarks:
The return pointers should point to a variable that will be set to the corresponding data, or they may be NULL if the data isn't interesting.

Clear any key/value pairs in the hash table.

Parameters:
htThe hash table

Tear down 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_terminate.

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

Parameters:
pThe pool to clear
Remarks:
This does not actually free the memory, it just allows the pool to re-use this memory for the next allocation.
See also:
apr_pool_destroy()

Debug version of apr_pool_clear.

Parameters:
pSee: apr_pool_clear.
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_clear calls in a wrapper function and wish to override the file_line argument to reflect the caller of your wrapper function. If you do not have apr_pool_clear in a wrapper, trust the macro and don't call apr_pool_destroy_clear directly.

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

Parameters:
pThe pool to destroy
Remarks:
This will actually free the memory

Debug version of apr_pool_destroy.

Parameters:
pSee: apr_pool_destroy.
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_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.

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

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

Tag a pool (give it a name)

Parameters:
poolThe pool to tag
tagThe tag

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

Parameters:
pThe pool register the cleanup with
dataThe data to pass to the cleanup function.
plain_cleanupThe function to call when the pool is cleared or destroyed
child_cleanupThe function to call when a child process is about to exec - this function is called in the child, obviously!

Remove a previously registered cleanup function.

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

Parameters:
pThe pool to remove the cleanup from
dataThe data of the registered cleanup
cleanupThe function to remove from cleanup
Remarks:
For some strange reason only the plain_cleanup is handled by this function

Replace the child cleanup function of a previously registered cleanup.

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

Parameters:
pThe pool of the registered cleanup
dataThe data of the registered cleanup
plain_cleanupThe plain cleanup function of the registered cleanup
child_cleanupThe function to register as the child cleanup

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

Initialize a PRNG state

Parameters:
gThe PRNG state
pThe pool to allocate from
pool_hashPool hash functions
key_hashKey hash functions
prng_hashPRNG hash functions

Mix the randomness pools.

Parameters:
gThe PRNG state
entropy_Entropy buffer
bytesLength of entropy_ in bytes

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

Parameters:
gThe RNG state

Mix the randomness pools after forking.

Parameters:
procThe resulting process handle from apr_proc_fork()
Remarks:
Call this in the child after forking to mix the randomness pools. Note that its generally a bad idea to fork a process with a real PRNG in it - better to have the PRNG externally and get the randomness from there. However, if you really must do it, then you should supply all your entropy to all the PRNGs - don't worry, they won't produce the same output.
Note that apr_proc_fork() calls this for you, so only weird applications need ever call it themselves.

Remove all elements from an array.

Parameters:
arrThe array to remove all elements from.
Remarks:
As the underlying storage is allocated from a pool, no memory is freed by this operation, but is available for reuse.

Concatenate two arrays together.

Parameters:
dstThe destination array, and the one to go first in the combined array
srcThe source array to add to the destination array

Delete all of the elements from a table.

Parameters:
tThe table to clear

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

Parameters:
tThe table to add the data to.
keyThe key to use (case does not matter)
valThe value to add
Remarks:
When adding data, this function makes a copy of both the key and the value.

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

Parameters:
tThe table to add the data to.
keyThe key to use (case does not matter)
valThe value to add
Warning:
When adding data, this function does not make a copy of the key or the value, so care should be taken to ensure that the values will not change after they have been added..

Remove data from the table.

Parameters:
tThe table to remove data from
keyThe key of the data being removed (case does not matter)

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

Parameters:
tThe table to search for the data
keyThe key to merge data for (case does not matter)
valThe data to add
Remarks:
If the key is not found, then this function acts like apr_table_add

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

Parameters:
tThe table to search for the data
keyThe key to merge data for (case does not matter)
valThe data to add
Remarks:
If the key is not found, then this function acts like apr_table_addn

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

Parameters:
tThe table to add to
keyThe key to use
valThe value to add.
Remarks:
When adding data, this function makes a copy of both the key and the value.

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

Parameters:
tThe table to add to
keyThe key to use
valThe value to add.
Remarks:
When adding data, this function does not make a copy of the key or the value, so care should be taken to ensure that the values will not change after they have been added.

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

Parameters:
aThe table to add the data to.
bThe table to iterate over, adding its data to table a
flagsHow to add the table to table a. One of: APR_OVERLAP_TABLES_SET Use apr_table_setn APR_OVERLAP_TABLES_MERGE Use apr_table_mergen
Remarks:
When merging duplicates, the two values are concatenated, separated by the string ", ".
This function is highly optimized, and uses less memory and CPU cycles than a function that just loops through table b calling other functions. Conceptually, apr_table_overlap does this:
  apr_array_header_t *barr = apr_table_elts(b);
  apr_table_entry_t *belt = (apr_table_entry_t *)barr->elts;
  int i;
  for (i = 0; i < barr->nelts; ++i) {
      if (flags & APR_OVERLAP_TABLES_MERGE) {
          apr_table_mergen(a, belt[i].key, belt[i].val);
      }
      else {
          apr_table_setn(a, belt[i].key, belt[i].val);
      }
  }
 

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

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

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

Parameters:
tTable.
flagsAPR_OVERLAP_TABLES_MERGE to merge, or APR_OVERLAP_TABLES_SET to overwrite
Remarks:
When merging duplicates, the two values are concatenated, separated by the string ", ".

Register an other_child -- a child associated to its registered maintence callback. This callback is invoked when the process dies, is disconnected or disappears.

Parameters:
procThe child process to register.
maintenancemaintenance is a function that is invoked with a reason and the data pointer passed here.
dataOpaque context data passed to the maintenance function.
write_fdAn fd that is probed for writing. If it is ever unwritable then the maintenance is invoked with reason OC_REASON_UNWRITABLE.
pThe 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.

no platform currently tests the pipes health.

Stop watching the specified other child.

Parameters:
dataThe 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.

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

Parameters:
ocrThe registered other child
reasonThe reason code (e.g. APR_OC_REASON_RESTART) if still running

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

Parameters:
reasonThe reason code (e.g. APR_OC_REASON_RESTART) to running processes

Register a process to be killed when a pool dies.

Parameters:
aThe pool to use to define the processes lifetime
procThe process to register
howHow to kill the process, one of:
         APR_KILL_NEVER         -- process is never sent any signals
         APR_KILL_ALWAYS        -- process is sent SIGKILL on apr_pool_t cleanup
         APR_KILL_AFTER_TIMEOUT -- SIGTERM, wait 3 seconds, SIGKILL
         APR_JUST_WAIT          -- wait forever for the process to complete
         APR_KILL_ONLY_ONCE     -- send SIGTERM and then wait
 
APR_DECLARE_NONSTD ( void  )

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

Remarks:
An APR program must call this function at termination once it has stopped using APR services. The APR developers suggest using atexit 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.

Variable Documentation

char const* const* * argv

Definition at line 192 of file apr_general.h.

char const* const char const* const* * env

Definition at line 192 of file apr_general.h.