Time Routines

Classes
struct	apr_time_exp_t
Defines
#define	APR_TIME_C(val)   APR_INT64_C(val)
#define	APR_TIME_T_FMT   APR_INT64_T_FMT
#define	APR_USEC_PER_SEC   APR_TIME_C(1000000)
#define	apr_time_sec(time)   ((time) / APR_USEC_PER_SEC)
#define	apr_time_usec(time)   ((time) % APR_USEC_PER_SEC)
#define	apr_time_msec(time)   (((time) / 1000) % 1000)
#define	apr_time_as_msec(time)   ((time) / 1000)
#define	apr_time_from_msec(msec)   ((apr_time_t)(msec) * 1000)
#define	apr_time_from_sec(sec)   ((apr_time_t)(sec) * APR_USEC_PER_SEC)
#define	apr_time_make(sec, usec)
#define	APR_RFC822_DATE_LEN   (30)
#define	APR_CTIME_LEN   (25)
Typedefs
typedef apr_int64_t	apr_time_t
typedef apr_int64_t	apr_interval_time_t
typedef apr_int32_t	apr_short_interval_time_t
typedef struct apr_time_exp_t	apr_time_exp_t
Functions
	APR_DECLARE (apr_time_t) apr_time_now(void)
	APR_DECLARE (apr_status_t) apr_time_ansi_put(apr_time_t *result
	APR_DECLARE (void) apr_sleep(apr_interval_time_t t)
Variables
APR_DECLARE_DATA const char	apr_month_snames [12][4]
APR_DECLARE_DATA const char	apr_day_snames [7][4]
time_t	input
apr_time_t apr_int32_t	offs
apr_time_t	t
apr_size_t *	retsize
apr_size_t apr_size_t	max
apr_size_t apr_size_t const char *	format
apr_size_t apr_size_t const char apr_time_exp_t *	tm

---

Define Documentation

#define APR_CTIME_LEN   (25)

length of a CTIME date

Definition at line 196 of file apr_time.h.

#define APR_RFC822_DATE_LEN   (30)

length of a RFC822 Date

Definition at line 184 of file apr_time.h.

#define apr_time_as_msec

(

time

)

((time) / 1000)

Returns:

apr_time_t as a msec

Definition at line 73 of file apr_time.h.

#define APR_TIME_C

(

val

)

APR_INT64_C(val)

mechanism to properly type apr_time_t literals

Definition at line 50 of file apr_time.h.

#define apr_time_from_msec

(

msec

)

((apr_time_t)(msec) * 1000)

Returns:

milliseconds as an apr_time_t

Definition at line 76 of file apr_time.h.

#define apr_time_from_sec

(

sec

)

((apr_time_t)(sec) * APR_USEC_PER_SEC)

Returns:

seconds as an apr_time_t

Definition at line 79 of file apr_time.h.

#define apr_time_make	(		sec,
			usec
	)

Value:

((apr_time_t)(sec) * APR_USEC_PER_SEC \
                                + (apr_time_t)(usec))

Returns:

a second and usec combination as an apr_time_t

Definition at line 82 of file apr_time.h.

#define apr_time_msec

(

time

)

(((time) / 1000) % 1000)

Returns:

apr_time_t as a msec

Definition at line 70 of file apr_time.h.

#define apr_time_sec

(

time

)

((time) / APR_USEC_PER_SEC)

Returns:

apr_time_t as a second

Definition at line 64 of file apr_time.h.

#define APR_TIME_T_FMT   APR_INT64_T_FMT

mechanism to properly print apr_time_t values

Definition at line 53 of file apr_time.h.

#define apr_time_usec

(

time

)

((time) % APR_USEC_PER_SEC)

Returns:

apr_time_t as a usec

Definition at line 67 of file apr_time.h.

#define APR_USEC_PER_SEC   APR_TIME_C(1000000)

number of microseconds per second

Definition at line 61 of file apr_time.h.

---

Typedef Documentation

typedef apr_int64_t apr_interval_time_t

intervals for I/O timeouts, in microseconds

Definition at line 56 of file apr_time.h.

typedef apr_int32_t apr_short_interval_time_t

short interval for I/O timeouts, in microseconds

Definition at line 58 of file apr_time.h.

typedef struct apr_time_exp_t apr_time_exp_t

See also:

apr_time_exp_t

Definition at line 91 of file apr_time.h.

typedef apr_int64_t apr_time_t

number of microseconds since 00:00:00 january 1, 1970 UTC

Definition at line 46 of file apr_time.h.

---

Function Documentation

APR_DECLARE

(

apr_time_t

)

Returns:

the current time

APR_DECLARE

(

apr_status_t

)

convert an ansi time_t to an apr_time_t

Parameters:

result	the resulting apr_time_t
input	the time_t to convert

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

Parameters:

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

convert a time to its human readable components in GMT timezone

Parameters:

result	the exploded time
input	the time to explode

convert a time to its human readable components in local timezone

Parameters:

result	the exploded time
input	the time to explode

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

Parameters:

result	the resulting imploded time
input	the input exploded time

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

Parameters:

result	the resulting imploded time
input	the input exploded time

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

Parameters:

date_str	String to write to.
t	the time to convert

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

Parameters:

date_str	String to write to.
t	the time to convert

formats the exploded time according to the format specified

Parameters:

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

APR_DECLARE

(

void

)

Sleep for the specified number of micro-seconds.

Parameters:

t	desired amount of time to sleep.

Warning:

May sleep for longer than the specified time.

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

Parameters:

p	The pool to associate the finer clock resolution

Destroy an allocator

Parameters:

allocator

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

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

Set the owner of the allocator

Parameters:

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

Remarks:

Typically pool is the highest level pool using the allocator

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

Parameters:

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

Associate a value with a key in a hash table.

Parameters:

ht	The hash table
key	Pointer to the key
klen	Length of the key. Can be APR_HASH_KEY_STRING to use the string length.
val	Value 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:

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

Remarks:

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

Clear any key/value pairs in the hash table.

Parameters:

ht	The hash table

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:

p	The pool to clear

Remarks:

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

See also:

apr_pool_destroy()

Debug version of apr_pool_clear.

Parameters:

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

Remarks:

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

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

Parameters:

p	The pool to destroy

Remarks:

This will actually free the memory

Debug version of apr_pool_destroy.

Parameters:

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

Remarks:

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

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:

pool	The pool to tag
tag	The tag

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

Parameters:

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

Remove a previously registered cleanup function.

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

Parameters:

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

Remarks:

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

Replace the child cleanup function of a previously registered cleanup.

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

Parameters:

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

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

Initialize a PRNG state

Parameters:

g	The PRNG state
p	The pool to allocate from
pool_hash	Pool hash functions
key_hash	Key hash functions
prng_hash	PRNG hash functions

Mix the randomness pools.

Parameters:

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

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

Parameters:

g	The RNG state

Mix the randomness pools after forking.

Parameters:

proc	The resulting process handle from apr_proc_fork()

Remarks:

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

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

Remove all elements from an array.

Parameters:

arr	The 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:

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

Delete all of the elements from a table.

Parameters:

t	The table to clear

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

Parameters:

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

Remarks:

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

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

Parameters:

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

Warning:

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

Remove data from the table.

Parameters:

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

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

Parameters:

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

Remarks:

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

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

Parameters:

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

Remarks:

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

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

Parameters:

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

Remarks:

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

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

Parameters:

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

Remarks:

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

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

Parameters:

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

Remarks:

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

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

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

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

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

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

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

Parameters:

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

Remarks:

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

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:

proc	The child process to register.
maintenance	maintenance is a function that is invoked with a reason and the data pointer passed here.
data	Opaque context data passed to the maintenance function.
write_fd	An fd that is probed for writing. If it is ever unwritable then the maintenance is invoked with reason OC_REASON_UNWRITABLE.
p	The pool to use for allocating memory.

Bug:

write_fd duplicates the proc->out stream, it's really redundant and should be replaced in the APR 1.0 API with a bitflag of which proc->in/out/err handles should be health checked.

no platform currently tests the pipes health.

Stop watching the specified other child.

Parameters:

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

Warning:

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

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

Parameters:

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

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

Parameters:

reason

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

Register a process to be killed when a pool dies.

Parameters:

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

---

Variable Documentation

APR_DECLARE_DATA const char apr_day_snames[7][4]

day names

APR_DECLARE_DATA const char apr_month_snames[12][4]

month names

apr_size_t apr_size_t const char* format

Definition at line 217 of file apr_time.h.

const unsigned char * input

Definition at line 129 of file apr_time.h.

apr_size_t apr_size_t max

Definition at line 217 of file apr_time.h.

apr_time_t apr_int32_t offs

Definition at line 139 of file apr_time.h.

apr_size_t* retsize

Definition at line 217 of file apr_time.h.

apr_time_t t

Definition at line 193 of file apr_time.h.

apr_size_t apr_size_t const char apr_time_exp_t* tm

Definition at line 217 of file apr_time.h.