Apache Portable Runtime
Modules | Data Structures | Macros | Typedefs | Enumerations | Functions
Threads and Process Functions

Modules

 Other Child Flags
 

Data Structures

struct  apr_proc_t
 

Macros

#define APR_PROC_CHECK_EXIT(x)   (x & APR_PROC_EXIT)
 
#define APR_PROC_CHECK_SIGNALED(x)   (x & APR_PROC_SIGNAL)
 
#define APR_PROC_CHECK_CORE_DUMP(x)   (x & APR_PROC_SIGNAL_CORE)
 
#define APR_NO_PIPE   0
 
#define APR_FULL_BLOCK   1
 
#define APR_FULL_NONBLOCK   2
 
#define APR_PARENT_BLOCK   3
 
#define APR_CHILD_BLOCK   4
 
#define APR_NO_FILE   8
 
#define APR_NO_FILE   8
 
#define APR_READ_BLOCK   3
 
#define APR_WRITE_BLOCK   4
 
#define APR_LIMIT_CPU   0
 
#define APR_LIMIT_MEM   1
 
#define APR_LIMIT_NPROC   2
 
#define APR_LIMIT_NOFILE   3
 
#define APR_PROC_DETACH_FOREGROUND   0
 
#define APR_PROC_DETACH_DAEMONIZE   1
 

Typedefs

typedef struct apr_proc_t apr_proc_t
 
typedef void() apr_child_errfn_t(apr_pool_t *proc, apr_status_t err, const char *description)
 
typedef struct apr_thread_t apr_thread_t
 
typedef struct apr_threadattr_t apr_threadattr_t
 
typedef struct apr_procattr_t apr_procattr_t
 
typedef struct apr_thread_once_t apr_thread_once_t
 
typedef struct apr_threadkey_t apr_threadkey_t
 
typedef struct apr_other_child_rec_t apr_other_child_rec_t
 
typedef void *(APR_THREAD_FUNCapr_thread_start_t) (apr_thread_t *, void *)
 

Enumerations

enum  apr_cmdtype_e {
  APR_SHELLCMD, APR_PROGRAM, APR_PROGRAM_ENV, APR_PROGRAM_PATH,
  APR_SHELLCMD_ENV
}
 
enum  apr_wait_how_e { APR_WAIT, APR_NOWAIT }
 
enum  apr_exit_why_e { APR_PROC_EXIT = 1, APR_PROC_SIGNAL = 2, APR_PROC_SIGNAL_CORE = 4 }
 
enum  apr_kill_conditions_e {
  APR_KILL_NEVER, APR_KILL_ALWAYS, APR_KILL_AFTER_TIMEOUT, APR_JUST_WAIT,
  APR_KILL_ONLY_ONCE
}
 

Functions

apr_status_t apr_threadattr_create (apr_threadattr_t **new_attr, apr_pool_t *cont)
 
apr_status_t apr_threadattr_detach_set (apr_threadattr_t *attr, apr_int32_t on)
 
apr_status_t apr_threadattr_detach_get (apr_threadattr_t *attr)
 
apr_status_t apr_threadattr_stacksize_set (apr_threadattr_t *attr, apr_size_t stacksize)
 
apr_status_t apr_threadattr_guardsize_set (apr_threadattr_t *attr, apr_size_t guardsize)
 
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)
 
apr_status_t apr_thread_exit (apr_thread_t *thd, apr_status_t retval)
 
apr_status_t apr_thread_join (apr_status_t *retval, apr_thread_t *thd)
 
void apr_thread_yield (void)
 
apr_status_t apr_thread_once_init (apr_thread_once_t **control, apr_pool_t *p)
 
apr_status_t apr_thread_once (apr_thread_once_t *control, void(*func)(void))
 
apr_status_t apr_thread_detach (apr_thread_t *thd)
 
apr_status_t apr_thread_data_get (void **data, const char *key, apr_thread_t *thread)
 
apr_status_t apr_thread_data_set (void *data, const char *key, apr_status_t(*cleanup)(void *), apr_thread_t *thread)
 
apr_status_t apr_threadkey_private_create (apr_threadkey_t **key, void(*dest)(void *), apr_pool_t *cont)
 
apr_status_t apr_threadkey_private_get (void **new_mem, apr_threadkey_t *key)
 
apr_status_t apr_threadkey_private_set (void *priv, apr_threadkey_t *key)
 
apr_status_t apr_threadkey_private_delete (apr_threadkey_t *key)
 
apr_status_t apr_threadkey_data_get (void **data, const char *key, apr_threadkey_t *threadkey)
 
apr_status_t apr_threadkey_data_set (void *data, const char *key, apr_status_t(*cleanup)(void *), apr_threadkey_t *threadkey)
 
apr_status_t apr_procattr_create (apr_procattr_t **new_attr, apr_pool_t *cont)
 
apr_status_t apr_procattr_io_set (apr_procattr_t *attr, apr_int32_t in, apr_int32_t out, apr_int32_t err)
 
apr_status_t apr_procattr_child_in_set (struct apr_procattr_t *attr, apr_file_t *child_in, apr_file_t *parent_in)
 
apr_status_t apr_procattr_child_out_set (struct apr_procattr_t *attr, apr_file_t *child_out, apr_file_t *parent_out)
 
apr_status_t apr_procattr_child_err_set (struct apr_procattr_t *attr, apr_file_t *child_err, apr_file_t *parent_err)
 
apr_status_t apr_procattr_dir_set (apr_procattr_t *attr, const char *dir)
 
apr_status_t apr_procattr_cmdtype_set (apr_procattr_t *attr, apr_cmdtype_e cmd)
 
apr_status_t apr_procattr_detach_set (apr_procattr_t *attr, apr_int32_t detach)
 
apr_status_t apr_procattr_limit_set (apr_procattr_t *attr, apr_int32_t what, struct rlimit *limit)
 
apr_status_t apr_procattr_child_errfn_set (apr_procattr_t *attr, apr_child_errfn_t *errfn)
 
apr_status_t apr_procattr_error_check_set (apr_procattr_t *attr, apr_int32_t chk)
 
apr_status_t apr_procattr_addrspace_set (apr_procattr_t *attr, apr_int32_t addrspace)
 
apr_status_t apr_procattr_user_set (apr_procattr_t *attr, const char *username, const char *password)
 
apr_status_t apr_procattr_group_set (apr_procattr_t *attr, const char *groupname)
 
apr_status_t apr_procattr_perms_set_register (apr_procattr_t *attr, apr_perms_setfn_t *perms_set_fn, void *data, apr_fileperms_t perms)
 
apr_status_t apr_proc_fork (apr_proc_t *proc, apr_pool_t *cont)
 
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)
 
apr_status_t apr_proc_wait (apr_proc_t *proc, int *exitcode, apr_exit_why_e *exitwhy, apr_wait_how_e waithow)
 
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)
 
apr_status_t apr_proc_detach (int daemonize)
 
void apr_proc_other_child_register (apr_proc_t *proc, void(*maintenance)(int reason, void *, int status), void *data, apr_file_t *write_fd, apr_pool_t *p)
 
void apr_proc_other_child_unregister (void *data)
 
apr_status_t apr_proc_other_child_alert (apr_proc_t *proc, int reason, int status)
 
void apr_proc_other_child_refresh (apr_other_child_rec_t *ocr, int reason)
 
void apr_proc_other_child_refresh_all (int reason)
 
apr_status_t apr_proc_kill (apr_proc_t *proc, int sig)
 
void apr_pool_note_subprocess (apr_pool_t *a, apr_proc_t *proc, apr_kill_conditions_e how)
 
apr_status_t apr_setup_signal_thread (void)
 
apr_status_t apr_signal_thread (int(*signal_handler)(int signum))
 
apr_pool_tapr_thread_pool_get (const apr_thread_t *thethread)
 

Detailed Description

Macro Definition Documentation

◆ APR_CHILD_BLOCK

#define APR_CHILD_BLOCK   4

◆ APR_FULL_BLOCK

#define APR_FULL_BLOCK   1

◆ APR_FULL_NONBLOCK

#define APR_FULL_NONBLOCK   2

◆ APR_LIMIT_CPU

#define APR_LIMIT_CPU   0

◆ APR_LIMIT_MEM

#define APR_LIMIT_MEM   1

◆ APR_LIMIT_NOFILE

#define APR_LIMIT_NOFILE   3

◆ APR_LIMIT_NPROC

#define APR_LIMIT_NPROC   2

◆ APR_NO_FILE [1/2]

#define APR_NO_FILE   8
See also
apr_procattr_io_set
apr_procattr_io_set
Note
Win32 only effective with version 1.2.12, portably introduced in 1.3.0

◆ APR_NO_FILE [2/2]

#define APR_NO_FILE   8
See also
apr_procattr_io_set
apr_procattr_io_set
Note
Win32 only effective with version 1.2.12, portably introduced in 1.3.0

◆ APR_NO_PIPE

#define APR_NO_PIPE   0

◆ APR_PARENT_BLOCK

#define APR_PARENT_BLOCK   3

◆ APR_PROC_CHECK_CORE_DUMP

#define APR_PROC_CHECK_CORE_DUMP (   x)    (x & APR_PROC_SIGNAL_CORE)

did we get core

◆ APR_PROC_CHECK_EXIT

#define APR_PROC_CHECK_EXIT (   x)    (x & APR_PROC_EXIT)

did we exit the process

◆ APR_PROC_CHECK_SIGNALED

#define APR_PROC_CHECK_SIGNALED (   x)    (x & APR_PROC_SIGNAL)

did we get a signal

◆ APR_PROC_DETACH_DAEMONIZE

#define APR_PROC_DETACH_DAEMONIZE   1

Detach

◆ APR_PROC_DETACH_FOREGROUND

#define APR_PROC_DETACH_FOREGROUND   0

Do not detach

◆ APR_READ_BLOCK

#define APR_READ_BLOCK   3

◆ APR_WRITE_BLOCK

#define APR_WRITE_BLOCK   4

Typedef Documentation

◆ apr_child_errfn_t

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:

Parameters
poolPool associated with the apr_proc_t. If your child error function needs user data, associate it with this pool.
errAPR error code describing the error
descriptionText description of type of processing which failed

◆ apr_other_child_rec_t

Opaque record of child process.

◆ apr_proc_t

typedef struct apr_proc_t apr_proc_t

The APR process type

◆ apr_procattr_t

Opaque Process attributes structure.

◆ apr_thread_once_t

Opaque control variable for one-time atomic variables.

◆ apr_thread_start_t

typedef void*(APR_THREAD_FUNC * apr_thread_start_t) (apr_thread_t *, void *)

The prototype for any APR thread worker functions.

◆ apr_thread_t

typedef struct apr_thread_t apr_thread_t

Opaque Thread structure.

◆ apr_threadattr_t

Opaque Thread attributes structure.

◆ apr_threadkey_t

Opaque thread private address space.

Enumeration Type Documentation

◆ apr_cmdtype_e

Enumerator
APR_SHELLCMD 

use the shell to invoke the program

APR_PROGRAM 

invoke the program directly, no copied env

APR_PROGRAM_ENV 

invoke the program, replicating our environment

APR_PROGRAM_PATH 

find program on PATH, use our environment

APR_SHELLCMD_ENV 

use the shell to invoke the program, replicating our environment

◆ apr_exit_why_e

Enumerator
APR_PROC_EXIT 

process exited normally

APR_PROC_SIGNAL 

process exited due to a signal

APR_PROC_SIGNAL_CORE 

process exited and dumped a core file

◆ apr_kill_conditions_e

Enumerator
APR_KILL_NEVER 

process is never killed (i.e., never sent any signals), but it will be reaped if it exits before the pool is cleaned up

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_wait_how_e

Enumerator
APR_WAIT 

wait for the specified process to finish

APR_NOWAIT 

do not wait – just see if it has finished

Function Documentation

◆ apr_pool_note_subprocess()

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.

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

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.

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.

◆ apr_proc_detach()

apr_status_t apr_proc_detach ( int  daemonize)

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.

◆ apr_proc_fork()

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.

Parameters
procThe resulting process handle.
contThe pool to use.
Remarks
returns APR_INCHILD for the child, and APR_INPARENT for the parent or an error.

◆ apr_proc_kill()

apr_status_t apr_proc_kill ( apr_proc_t proc,
int  sig 
)

Terminate a process.

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

◆ apr_proc_other_child_alert()

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.

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 ...]

◆ apr_proc_other_child_refresh()

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.

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

◆ apr_proc_other_child_refresh_all()

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
reasonThe reason code (e.g. APR_OC_REASON_RESTART) to running processes

◆ apr_proc_other_child_register()

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.

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.

◆ apr_proc_other_child_unregister()

void apr_proc_other_child_unregister ( void *  data)

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.

◆ apr_proc_wait()

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

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 child's 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.

◆ apr_proc_wait_all_procs()

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.

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

◆ apr_procattr_addrspace_set()

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

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.

◆ apr_procattr_child_err_set()

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.

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.

◆ apr_procattr_child_errfn_set()

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.

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.

◆ apr_procattr_child_in_set()

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.

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.

◆ apr_procattr_child_out_set()

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.

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.

◆ apr_procattr_cmdtype_set()

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.

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

◆ apr_procattr_create()

apr_status_t apr_procattr_create ( apr_procattr_t **  new_attr,
apr_pool_t cont 
)

Create and initialize a new procattr variable

Parameters
new_attrThe newly created procattr.
contThe pool to use

◆ apr_procattr_detach_set()

apr_status_t apr_procattr_detach_set ( apr_procattr_t attr,
apr_int32_t  detach 
)

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.

◆ apr_procattr_dir_set()

apr_status_t apr_procattr_dir_set ( apr_procattr_t attr,
const char *  dir 
)

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.

◆ apr_procattr_error_check_set()

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.

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.

◆ apr_procattr_group_set()

apr_status_t apr_procattr_group_set ( apr_procattr_t attr,
const char *  groupname 
)

Set the group used for running process

Parameters
attrThe procattr we care about.
groupnameThe group name used

◆ apr_procattr_io_set()

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.

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!

◆ apr_procattr_limit_set()

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.

Parameters
attrThe procattr we care about.
whatWhich limit to set, one of:
                APR_LIMIT_CPU
                APR_LIMIT_MEM
                APR_LIMIT_NPROC
                APR_LIMIT_NOFILE
limitValue to set the limit to.

◆ apr_procattr_perms_set_register()

apr_status_t apr_procattr_perms_set_register ( apr_procattr_t attr,
apr_perms_setfn_t perms_set_fn,
void *  data,
apr_fileperms_t  perms 
)

Register permission set function

Parameters
attrThe procattr we care about.
perms_set_fnPermission set callback
dataData to pass to permission callback function
permsPermissions to set

◆ apr_procattr_user_set()

apr_status_t apr_procattr_user_set ( apr_procattr_t attr,
const char *  username,
const char *  password 
)

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.

◆ apr_setup_signal_thread()

apr_status_t apr_setup_signal_thread ( void  )

Setup the process for a single thread to be used for all signal handling.

Warning
This must be called before any threads are created

◆ apr_signal_thread()

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.

Parameters
signal_handlerThe function to call when a signal is received apr_status_t apr_signal_thread((int)(*signal_handler)(int signum))
Note
Synchronous signals like SIGABRT/SIGSEGV/SIGBUS/... are ignored by apr_signal_thread() and thus can't be waited by this function (they remain handled by the operating system or its native signals interface).
Remarks
In APR version 1.6 and ealier, SIGUSR2 was part of these ignored signals and thus was never passed in to the signal_handler. From APR 1.7 this is no more the case so SIGUSR2 can be handled in signal_handler and acted upon like the other asynchronous signals.

◆ apr_thread_create()

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

Parameters
new_threadThe newly created thread handle.
attrThe threadattr to use to determine how to create the thread
funcThe function to start the new thread in
dataAny data to be passed to the starting function
contThe pool to use

◆ apr_thread_data_get()

apr_status_t apr_thread_data_get ( void **  data,
const char *  key,
apr_thread_t thread 
)

Return user data associated with the current thread.

Parameters
dataThe user data associated with the thread.
keyThe key to associate with the data
threadThe currently open thread.

◆ apr_thread_data_set()

apr_status_t apr_thread_data_set ( void *  data,
const char *  key,
apr_status_t(*)(void *)  cleanup,
apr_thread_t thread 
)

Set user data associated with the current thread.

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

◆ apr_thread_detach()

apr_status_t apr_thread_detach ( apr_thread_t thd)

detach a thread

Parameters
thdThe thread to detach

◆ apr_thread_exit()

apr_status_t apr_thread_exit ( apr_thread_t thd,
apr_status_t  retval 
)

stop the current thread

Parameters
thdThe thread to stop
retvalThe return value to pass back to any thread that cares

◆ apr_thread_join()

apr_status_t apr_thread_join ( apr_status_t retval,
apr_thread_t thd 
)

block until the desired thread stops executing.

Parameters
retvalThe return value from the dead thread.
thdThe thread to join

◆ apr_thread_once()

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.

Parameters
controlThe 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.
funcThe function to call.

◆ apr_thread_once_init()

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.

Parameters
controlThe control variable to initialize
pThe pool to allocate data from.

◆ apr_thread_pool_get()

apr_pool_t* apr_thread_pool_get ( const apr_thread_t thethread)

Get the child-pool used by the thread from the thread info.

Returns
apr_pool_t the pool

◆ apr_thread_yield()

void apr_thread_yield ( void  )

force the current thread to yield the processor

◆ apr_threadattr_create()

apr_status_t apr_threadattr_create ( apr_threadattr_t **  new_attr,
apr_pool_t cont 
)

Create and initialize a new threadattr variable

Parameters
new_attrThe newly created threadattr.
contThe pool to use

◆ apr_threadattr_detach_get()

apr_status_t apr_threadattr_detach_get ( apr_threadattr_t attr)

Get the detach state for this threadattr.

Parameters
attrThe threadattr to reference
Returns
APR_DETACH if threads are to be detached, or APR_NOTDETACH if threads are to be joinable.

◆ apr_threadattr_detach_set()

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.

Parameters
attrThe threadattr to affect
onNon-zero if detached threads should be created.

◆ apr_threadattr_guardsize_set()

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.

Parameters
attrThe threadattr to affect
guardsizeThe 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.

◆ apr_threadattr_stacksize_set()

apr_status_t apr_threadattr_stacksize_set ( apr_threadattr_t attr,
apr_size_t  stacksize 
)

Set the stack size of newly created threads.

Parameters
attrThe threadattr to affect
stacksizeThe stack size in bytes

◆ apr_threadkey_data_get()

apr_status_t apr_threadkey_data_get ( void **  data,
const char *  key,
apr_threadkey_t threadkey 
)

Return the pool associated with the current threadkey.

Parameters
dataThe user data associated with the threadkey.
keyThe key associated with the data
threadkeyThe currently open threadkey.

◆ apr_threadkey_data_set()

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.

Parameters
dataThe data to set.
keyThe key to associate with the data.
cleanupThe cleanup routine to use when the file is destroyed.
threadkeyThe currently open threadkey.

◆ apr_threadkey_private_create()

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

Parameters
keyThe thread private handle.
destThe destructor to use when freeing the private memory.
contThe pool to use

◆ apr_threadkey_private_delete()

apr_status_t apr_threadkey_private_delete ( apr_threadkey_t key)

Free the thread private memory

Parameters
keyThe handle for the desired thread private memory

◆ apr_threadkey_private_get()

apr_status_t apr_threadkey_private_get ( void **  new_mem,
apr_threadkey_t key 
)

Get a pointer to the thread private memory

Parameters
new_memThe data stored in private memory
keyThe handle for the desired thread private memory

◆ apr_threadkey_private_set()

apr_status_t apr_threadkey_private_set ( void *  priv,
apr_threadkey_t key 
)

Set the data to be stored in thread private memory

Parameters
privThe data to be stored in private memory
keyThe handle for the desired thread private memory