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:
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
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
Create a new process and execute a new program within that process.
Parameters:
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.
Note:
This function returns without waiting for the new process to terminate; use apr_proc_wait for that.
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
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.
Parameters:
reason
The reason code (e.g. APR_OC_REASON_RESTART) to running processes
Register an other_child -- a child associated to its registered maintence callback. This callback is invoked when the process dies, is disconnected or disappears.
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.
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.
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.
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.
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:
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.
Set the child_err and parent_err values to existing apr_file_t values.
Parameters:
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.
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.
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.
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:
attr
The procattr describing the child process to be created.
errfn
The 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.
Set the child_in and/or parent_in values to existing apr_file_t values.
Parameters:
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.
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.
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.
Set the child_out and parent_out values to existing apr_file_t values.
Parameters:
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.
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.
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.
Set what type of command the child process will call.
Parameters:
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
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:
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.
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 any of stdin, stdout, or stderr should be linked to pipes when starting a child process.
Parameters:
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?
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!
Run the specified function one time, regardless of how many threads call it.
Parameters:
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.
Set the stack guard area size of newly created threads.
Parameters:
attr
The threadattr to affect
guardsize
The stack guard area size in bytes
Note:
Thread library implementations commonly use a "guard area" after each thread's stack which is not readable or writable such that stack overflows cause a segfault; this consumes e.g. 4K of memory and increases memory management overhead. Setting the guard area size to zero hence trades off reliable behaviour on stack overflow for performance.
1.7.4
