|
Apache Portable Runtime
|
|
Apache Portable Runtime
|
| #define APR_CHILD_BLOCK 4 |
| #define APR_FULL_BLOCK 1 |
| #define APR_FULL_NONBLOCK 2 |
| #define APR_LIMIT_CPU 0 |
| #define APR_LIMIT_MEM 1 |
| #define APR_LIMIT_NOFILE 3 |
| #define APR_LIMIT_NPROC 2 |
| #define APR_NO_FILE 8 |
| #define APR_NO_FILE 8 |
| #define APR_NO_PIPE 0 |
| #define APR_PARENT_BLOCK 3 |
| #define APR_PROC_CHECK_CORE_DUMP | ( | x | ) | (x & APR_PROC_SIGNAL_CORE) |
did we get core
| #define APR_PROC_CHECK_EXIT | ( | x | ) | (x & APR_PROC_EXIT) |
did we exit the process
| #define APR_PROC_CHECK_SIGNALED | ( | x | ) | (x & APR_PROC_SIGNAL) |
did we get a signal
| #define APR_PROC_DETACH_DAEMONIZE 1 |
Detach
| #define APR_PROC_DETACH_FOREGROUND 0 |
Do not detach
| #define APR_READ_BLOCK 3 |
| #define APR_WRITE_BLOCK 4 |
| typedef void( apr_child_errfn_t)(apr_pool_t *proc, apr_status_t err, const char *description) |
The prototype for APR child errfn functions. (See the description of apr_procattr_child_errfn_set() for more information.) It is passed the following parameters:
| pool | Pool associated with the apr_proc_t. If your child error function needs user data, associate it with this pool. |
| err | APR error code describing the error |
| description | Text description of type of processing which failed |
| typedef struct apr_other_child_rec_t apr_other_child_rec_t |
Opaque record of child process.
| typedef struct apr_proc_t apr_proc_t |
The APR process type
| typedef struct apr_procattr_t apr_procattr_t |
Opaque Process attributes structure.
| typedef struct apr_thread_once_t apr_thread_once_t |
Opaque control variable for one-time atomic variables.
| typedef void*(APR_THREAD_FUNC * apr_thread_start_t)(apr_thread_t *, void *) |
The prototype for any APR thread worker functions.
| typedef struct apr_thread_t apr_thread_t |
Opaque Thread structure.
| typedef struct apr_threadattr_t apr_threadattr_t |
Opaque Thread attributes structure.
| typedef struct apr_threadkey_t apr_threadkey_t |
Opaque thread private address space.
| enum apr_cmdtype_e |
| enum apr_exit_why_e |
| enum apr_wait_how_e |
| void apr_pool_note_subprocess | ( | apr_pool_t * | a, |
| apr_proc_t * | proc, | ||
| apr_kill_conditions_e | how | ||
| ) |
Register a process to be killed when a pool dies.
| 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
|
| apr_status_t apr_proc_create | ( | apr_proc_t * | new_proc, |
| const char * | progname, | ||
| const char *const * | args, | ||
| const char *const * | env, | ||
| apr_procattr_t * | attr, | ||
| apr_pool_t * | pool | ||
| ) |
Create a new process and execute a new program within that process.
| new_proc | The resulting process handle. |
| progname | The program to run |
| args | the arguments to pass to the new program. The first one should be the program name. |
| env | The new environment table for the new process. This should be a list of NULL-terminated strings. This argument is ignored for APR_PROGRAM_ENV, APR_PROGRAM_PATH, and APR_SHELLCMD_ENV types of commands. |
| attr | the procattr we should use to determine how to create the new process |
| pool | The pool to use. |
| apr_status_t apr_proc_detach | ( | int | daemonize | ) |
Detach the process from the controlling terminal.
| daemonize | set to non-zero if the process should daemonize and become a background process, else it will stay in the foreground. |
| apr_status_t apr_proc_fork | ( | apr_proc_t * | proc, |
| apr_pool_t * | cont | ||
| ) |
This is currently the only non-portable call in APR. This executes a standard unix fork.
| proc | The resulting process handle. |
| cont | The pool to use. |
| apr_status_t apr_proc_kill | ( | apr_proc_t * | proc, |
| int | sig | ||
| ) |
Terminate a process.
| proc | The process to terminate. |
| sig | How to kill the process. |
| apr_status_t apr_proc_other_child_alert | ( | apr_proc_t * | proc, |
| int | reason, | ||
| int | status | ||
| ) |
Notify the maintenance callback of a registered other child process that application has detected an event, such as death.
| proc | The process to check |
| reason | The reason code to pass to the maintenance function |
| status | The status to pass to the maintenance function |
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 ...]
| void apr_proc_other_child_refresh | ( | apr_other_child_rec_t * | ocr, |
| int | reason | ||
| ) |
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.
| ocr | The registered other child |
| reason | The reason code (e.g. APR_OC_REASON_RESTART) if still running |
| void apr_proc_other_child_refresh_all | ( | int | reason | ) |
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.
| reason | The reason code (e.g. APR_OC_REASON_RESTART) to running processes |
| void apr_proc_other_child_register | ( | apr_proc_t * | proc, |
| void(*)(int reason, void *, int status) | maintenance, | ||
| void * | data, | ||
| apr_file_t * | write_fd, | ||
| apr_pool_t * | p | ||
| ) |
Register an other_child -- a child associated to its registered maintence callback. This callback is invoked when the process dies, is disconnected or disappears.
| 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. |
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.
| void apr_proc_other_child_unregister | ( | void * | data | ) |
Stop watching the specified other child.
| data | The data to pass to the maintenance function. This is used to find the process to unregister. |
| apr_status_t apr_proc_wait | ( | apr_proc_t * | proc, |
| int * | exitcode, | ||
| apr_exit_why_e * | exitwhy, | ||
| apr_wait_how_e | waithow | ||
| ) |
Wait for a child process to die
| proc | The process handle that corresponds to the desired child process |
| exitcode | The returned exit status of the child, if a child process dies, or the signal that caused the child to die. On platforms that don't support obtaining this information, the status parameter will be returned as APR_ENOTIMPL. |
| exitwhy | Why the child died, the bitwise or of:
APR_PROC_EXIT -- process terminated normally
APR_PROC_SIGNAL -- process was killed by a signal
APR_PROC_SIGNAL_CORE -- process was killed by a signal, and
generated a core dump.
|
| waithow | How should we wait. One of:
APR_WAIT -- block until the child process dies.
APR_NOWAIT -- return immediately regardless of if the
child is dead or not.
|
APR_CHILD_DONE -- child is no longer running.
APR_CHILD_NOTDONE -- child is still running.
| apr_status_t apr_proc_wait_all_procs | ( | apr_proc_t * | proc, |
| int * | exitcode, | ||
| apr_exit_why_e * | exitwhy, | ||
| apr_wait_how_e | waithow, | ||
| apr_pool_t * | p | ||
| ) |
Wait for any current child process to die and return information about that child.
| proc | Pointer to NULL on entry, will be filled out with child's information |
| exitcode | The returned exit status of the child, if a child process dies, or the signal that caused the child to die. On platforms that don't support obtaining this information, the status parameter will be returned as APR_ENOTIMPL. |
| exitwhy | Why the child died, the bitwise or of:
APR_PROC_EXIT -- process terminated normally
APR_PROC_SIGNAL -- process was killed by a signal
APR_PROC_SIGNAL_CORE -- process was killed by a signal, and
generated a core dump.
|
| waithow | How should we wait. One of:
APR_WAIT -- block until the child process dies.
APR_NOWAIT -- return immediately regardless of if the
child is dead or not.
|
| p | Pool to allocate child information out of. |
| apr_status_t apr_procattr_addrspace_set | ( | apr_procattr_t * | attr, |
| apr_int32_t | addrspace | ||
| ) |
Determine if the child should start in its own address space or using the current one from its parent
| attr | The procattr we care about. |
| addrspace | Should the child start in its own address space? Default is no on NetWare and yes on other platforms. |
| apr_status_t apr_procattr_child_err_set | ( | struct apr_procattr_t * | attr, |
| apr_file_t * | child_err, | ||
| apr_file_t * | parent_err | ||
| ) |
Set the child_err and parent_err values to existing apr_file_t values.
| attr | The procattr we care about. |
| child_err | apr_file_t value to use as child_err. Must be a valid file. |
| parent_err | apr_file_t value to use as parent_err. Must be a valid file. |
| apr_status_t apr_procattr_child_errfn_set | ( | apr_procattr_t * | attr, |
| apr_child_errfn_t * | errfn | ||
| ) |
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.
| attr | The procattr describing the child process to be created. |
| errfn | The function to call in the child process. |
| apr_status_t apr_procattr_child_in_set | ( | struct apr_procattr_t * | attr, |
| apr_file_t * | child_in, | ||
| apr_file_t * | parent_in | ||
| ) |
Set the child_in and/or parent_in values to existing apr_file_t values.
| attr | The procattr we care about. |
| child_in | apr_file_t value to use as child_in. Must be a valid file. |
| parent_in | apr_file_t value to use as parent_in. Must be a valid file. |
| apr_status_t apr_procattr_child_out_set | ( | struct apr_procattr_t * | attr, |
| apr_file_t * | child_out, | ||
| apr_file_t * | parent_out | ||
| ) |
Set the child_out and parent_out values to existing apr_file_t values.
| attr | The procattr we care about. |
| child_out | apr_file_t value to use as child_out. Must be a valid file. |
| parent_out | apr_file_t value to use as parent_out. Must be a valid file. |
| apr_status_t apr_procattr_cmdtype_set | ( | apr_procattr_t * | attr, |
| apr_cmdtype_e | cmd | ||
| ) |
Set what type of command the child process will call.
| attr | The procattr we care about. |
| cmd | The type of command. One of:
APR_SHELLCMD -- Anything that the shell can handle
APR_PROGRAM -- Executable program (default)
APR_PROGRAM_ENV -- Executable program, copy environment
APR_PROGRAM_PATH -- Executable program on PATH, copy env
|
| apr_status_t apr_procattr_create | ( | apr_procattr_t ** | new_attr, |
| apr_pool_t * | cont | ||
| ) |
Create and initialize a new procattr variable
| new_attr | The newly created procattr. |
| cont | The pool to use |
| apr_status_t apr_procattr_detach_set | ( | apr_procattr_t * | attr, |
| apr_int32_t | detach | ||
| ) |
Determine if the child should start in detached state.
| attr | The procattr we care about. |
| detach | Should the child start in detached state? Default is no. |
| apr_status_t apr_procattr_dir_set | ( | apr_procattr_t * | attr, |
| const char * | dir | ||
| ) |
Set which directory the child process should start executing in.
| attr | The procattr we care about. |
| dir | Which dir to start in. By default, this is the same dir as the parent currently resides in, when the createprocess call is made. |
| apr_status_t apr_procattr_error_check_set | ( | apr_procattr_t * | attr, |
| apr_int32_t | chk | ||
| ) |
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.
| attr | The procattr describing the child process to be created. |
| chk | Flag to indicate whether or not extra work should be done to try to report failures to the caller. |
| apr_status_t apr_procattr_group_set | ( | apr_procattr_t * | attr, |
| const char * | groupname | ||
| ) |
Set the group used for running process
| attr | The procattr we care about. |
| groupname | The group name used |
| apr_status_t apr_procattr_io_set | ( | apr_procattr_t * | attr, |
| apr_int32_t | in, | ||
| apr_int32_t | out, | ||
| apr_int32_t | err | ||
| ) |
Determine if any of stdin, stdout, or stderr should be linked to pipes when starting a child process.
| attr | The procattr we care about. |
| in | Should stdin be a pipe back to the parent? |
| out | Should stdout be a pipe back to the parent? |
| err | Should stderr be a pipe back to the parent? |
| apr_status_t apr_procattr_limit_set | ( | apr_procattr_t * | attr, |
| apr_int32_t | what, | ||
| struct rlimit * | limit | ||
| ) |
Set the Resource Utilization limits when starting a new process.
| attr | The procattr we care about. |
| what | Which limit to set, one of:
APR_LIMIT_CPU
APR_LIMIT_MEM
APR_LIMIT_NPROC
APR_LIMIT_NOFILE
|
| limit | Value to set the limit to. |
| apr_status_t apr_procattr_user_set | ( | apr_procattr_t * | attr, |
| const char * | username, | ||
| const char * | password | ||
| ) |
Set the username used for running process
| attr | The procattr we care about. |
| username | The username used |
| password | User password if needed. Password is needed on WIN32 or any other platform having APR_PROCATTR_USER_SET_REQUIRES_PASSWORD set. |
| apr_status_t apr_setup_signal_thread | ( | void | ) |
Setup the process for a single thread to be used for all signal handling.
| apr_status_t apr_signal_thread | ( | int(*)(int signum) | signal_handler | ) |
Make the current thread listen for signals. This thread will loop forever, calling a provided function whenever it receives a signal. That functions should return 1 if the signal has been handled, 0 otherwise.
| signal_handler | The function to call when a signal is received apr_status_t apr_signal_thread((int)(*signal_handler)(int signum)) |
| apr_status_t apr_thread_create | ( | apr_thread_t ** | new_thread, |
| apr_threadattr_t * | attr, | ||
| apr_thread_start_t | func, | ||
| void * | data, | ||
| apr_pool_t * | cont | ||
| ) |
Create a new thread of execution
| new_thread | The newly created thread handle. |
| attr | The threadattr to use to determine how to create the thread |
| func | The function to start the new thread in |
| data | Any data to be passed to the starting function |
| cont | The pool to use |
| apr_status_t apr_thread_data_get | ( | void ** | data, |
| const char * | key, | ||
| apr_thread_t * | thread | ||
| ) |
Return the pool associated with the current thread.
| data | The user data associated with the thread. |
| key | The key to associate with the data |
| thread | The currently open thread. |
| apr_status_t apr_thread_data_set | ( | void * | data, |
| const char * | key, | ||
| apr_status_t(*)(void *) | cleanup, | ||
| apr_thread_t * | thread | ||
| ) |
Return the pool associated with the current thread.
| data | The user data to associate with the thread. |
| key | The key to use for associating the data with the thread |
| cleanup | The cleanup routine to use when the thread is destroyed. |
| thread | The currently open thread. |
| apr_status_t apr_thread_detach | ( | apr_thread_t * | thd | ) |
detach a thread
| thd | The thread to detach |
| apr_status_t apr_thread_exit | ( | apr_thread_t * | thd, |
| apr_status_t | retval | ||
| ) |
stop the current thread
| thd | The thread to stop |
| retval | The return value to pass back to any thread that cares |
| apr_status_t apr_thread_join | ( | apr_status_t * | retval, |
| apr_thread_t * | thd | ||
| ) |
block until the desired thread stops executing.
| retval | The return value from the dead thread. |
| thd | The thread to join |
| apr_status_t apr_thread_once | ( | apr_thread_once_t * | control, |
| void(*)(void) | func | ||
| ) |
Run the specified function one time, regardless of how many threads call it.
| control | The control variable. The same variable should be passed in each time the function is tried to be called. This is how the underlying functions determine if the function has ever been called before. |
| func | The function to call. |
| apr_status_t apr_thread_once_init | ( | apr_thread_once_t ** | control, |
| apr_pool_t * | p | ||
| ) |
Initialize the control variable for apr_thread_once. If this isn't called, apr_initialize won't work.
| control | The control variable to initialize |
| p | The pool to allocate data from. |
| apr_pool_t* apr_thread_pool_get | ( | const apr_thread_t * | thethread | ) |
Get the child-pool used by the thread from the thread info.
| void apr_thread_yield | ( | void | ) |
force the current thread to yield the processor
| apr_status_t apr_threadattr_create | ( | apr_threadattr_t ** | new_attr, |
| apr_pool_t * | cont | ||
| ) |
Create and initialize a new threadattr variable
| new_attr | The newly created threadattr. |
| cont | The pool to use |
| apr_status_t apr_threadattr_detach_get | ( | apr_threadattr_t * | attr | ) |
Get the detach state for this threadattr.
| attr | The threadattr to reference |
| apr_status_t apr_threadattr_detach_set | ( | apr_threadattr_t * | attr, |
| apr_int32_t | on | ||
| ) |
Set if newly created threads should be created in detached state.
| attr | The threadattr to affect |
| on | Non-zero if detached threads should be created. |
| apr_status_t apr_threadattr_guardsize_set | ( | apr_threadattr_t * | attr, |
| apr_size_t | guardsize | ||
| ) |
Set the stack guard area size of newly created threads.
| attr | The threadattr to affect |
| guardsize | The stack guard area size in bytes |
| apr_status_t apr_threadattr_stacksize_set | ( | apr_threadattr_t * | attr, |
| apr_size_t | stacksize | ||
| ) |
Set the stack size of newly created threads.
| attr | The threadattr to affect |
| stacksize | The stack size in bytes |
| apr_status_t apr_threadkey_data_get | ( | void ** | data, |
| const char * | key, | ||
| apr_threadkey_t * | threadkey | ||
| ) |
Return the pool associated with the current threadkey.
| data | The user data associated with the threadkey. |
| key | The key associated with the data |
| threadkey | The currently open threadkey. |
| apr_status_t apr_threadkey_data_set | ( | void * | data, |
| const char * | key, | ||
| apr_status_t(*)(void *) | cleanup, | ||
| apr_threadkey_t * | threadkey | ||
| ) |
Return the pool associated with the current threadkey.
| data | The data to set. |
| key | The key to associate with the data. |
| cleanup | The cleanup routine to use when the file is destroyed. |
| threadkey | The currently open threadkey. |
| apr_status_t apr_threadkey_private_create | ( | apr_threadkey_t ** | key, |
| void(*)(void *) | dest, | ||
| apr_pool_t * | cont | ||
| ) |
Create and initialize a new thread private address space
| key | The thread private handle. |
| dest | The destructor to use when freeing the private memory. |
| cont | The pool to use |
| apr_status_t apr_threadkey_private_delete | ( | apr_threadkey_t * | key | ) |
Free the thread private memory
| key | The handle for the desired thread private memory |
| apr_status_t apr_threadkey_private_get | ( | void ** | new_mem, |
| apr_threadkey_t * | key | ||
| ) |
Get a pointer to the thread private memory
| new_mem | The data stored in private memory |
| key | The handle for the desired thread private memory |
| apr_status_t apr_threadkey_private_set | ( | void * | priv, |
| apr_threadkey_t * | key | ||
| ) |
Set the data to be stored in thread private memory
| priv | The data to be stored in private memory |
| key | The handle for the desired thread private memory |
1.7.5