process Class Reference

#include <process.h>

Static Public Member Functions
static int64_t	checkForPidFile (const char *filename)
static bool	createPidFile (const char *filename, mode_t permissions)
static pid_t	getProcessId ()
static pid_t	getParentProcessId ()
static pid_t	getProcessGroupId ()
static pid_t	getProcessGroupId (pid_t pid)
static bool	setProcessGroupId ()
static bool	setProcessGroupId (pid_t pgid)
static bool	setProcessGroupId (pid_t pid, pid_t pgid)
static pid_t	getSessionId ()
static pid_t	getSessionId (pid_t pid)
static pid_t	createNewSession ()
static uid_t	getUserId ()
static uid_t	getEffectiveUserId ()
static bool	setUserId (uid_t uid)
static bool	setUser (const char *username)
static bool	setEffectiveUserId (uid_t uid)
static bool	setEffectiveUser (const char *username)
static bool	setRealAndEffectiveUserId (uid_t uid, uid_t euid)
static gid_t	getGroupId ()
static gid_t	getEffectiveGroupId ()
static bool	setGroupId (gid_t gid)
static bool	setGroup (const char *groupname)
static bool	setEffectiveGroupId (gid_t gid)
static bool	setEffectiveGroup (const char *groupname)
static bool	setRealAndEffectiveGroupId (gid_t gid, gid_t egid)
static mode_t	setFileCreationMask (mode_t mask)
static pid_t	fork ()
static bool	supportsFork ()
static bool	exec (const char *command, const char *const *args)
static pid_t	spawn (const char *command, const char *const *args, bool detached)
static bool	detach ()
static void	exit (int32_t status)
static void	exitImmediately (int32_t status)
static bool	sendSignal (pid_t processid, int32_t signum)
static bool	raiseSignal (int32_t signum)
static void	exitOnCrashOrShutDown ()
static void	exitOnShutDown ()
static void	exitOnCrash ()
static void	setShutDownFlagOnCrashOrShutDown ()
static void	setShutDownFlagOnShutDown ()
static void	setShutDownFlagOnCrash ()
static bool	registerExitHandler (void(*handler)(void))
static void	setShutDownHandler (void(*shutdownhandler)(int32_t))
static void	setCrashHandler (void(*crashhandler)(int32_t))
static void	setShutDownFlag (bool shutdownflag)
static bool	getShutDownFlag ()
static void	setShutDownSignal (int32_t signum)
static int32_t	getShutDownSignal ()
static signalhandler *	getCrashSignalHandler ()
static signalhandler *	getShutDownSignalHandler ()
static void	setWaitForChildren (bool wait)
static bool	wait (pid_t pid)
static bool	wait (pid_t pid, int32_t *exitstatus)
static pid_t	getChildStateChange (pid_t pid, bool wait, bool ignorestop, bool ignorecontinue, childstatechange *newstate, int32_t *exitstatus, int32_t *signum, bool *coredump)
static bool	supportsGetChildStateChange ()
static void	setRetryFailedFork (bool retry)
static bool	getRetryFailedFork ()
static void	writeBacktrace (output *out, uint32_t maxframes)
static void	writeBacktrace (output *out)
static void	writeBacktrace (const char *filename)
static void	writeBacktrace (const char *filename, mode_t perms, uint32_t maxframes)

Detailed Description

The process class provides static methods for accessing information about and controlling processes, including methods for forking, spawning and executing child processes.

Member Function Documentation

checkForPidFile()

static int64_t process::checkForPidFile ( const char * filename )

static

Checks for filename "filename" and reads the process id out of it, if it exists. Returns the process id on success or -1 on failure.

createNewSession()

static pid_t process::createNewSession ( )

static

Creates a new session, sets the calling process to be the process group leader and detaches from the controlling terminal. Returns the session id on success or -1 if an error occurred.

createPidFile()

static bool process::createPidFile ( const char * filename, mode_t permissions )

static

Create's file "filename" with permissions "permissions" and puts the current process id in it. Note that when you delete this file during shutdown you must use the full pathname since the process::detach() method changes directories to "/". Returns true on success and false on failure.

detach()

static bool process::detach ( )

static

Detaches the current process from the controlling tty, creates a new session, changes directory to / and sets the file creation mask to 0. Use this method to "fork your process into the background." Returns true on success and false on failure.

exec()

static bool process::exec ( const char * command, const char *const * args )

static

Runs "command" with arguments "args", replacing the current running process with this new process. Whether the new process retains the process id of the current process is platform-specific. Note that the first element of array "args" should be the name of the command that you want to run, typically the same as "command". "args" should be NULL terminated. Returns false if an error occurred and otherwise does not return at all.

exit()

static void process::exit ( int32_t status )

static

Terminates the calling process and sets the exit status to "status".

exitImmediately()

static void process::exitImmediately ( int32_t status )

static

Terminates the calling process "immediately" (without calling any functions registered to run at exit) and sets the exit status to "status".

exitOnCrash()

static void process::exitOnCrash ( )

static

Sets up a default handler that calls exitImmediately() if the process crashes with a program error signal - SIGABRT, SIGFPE, SIGILL, SIGSEGV, SIGBUS, SIGIOT, SIGEMT or SIGSYS.

exitOnCrashOrShutDown()

static void process::exitOnCrashOrShutDown ( )

static

Calls exitOnShutDown(), exitOnCrash() below.

exitOnShutDown()

static void process::exitOnShutDown ( )

static

Sets up a default handler that calls exitImmediately() when the process receives with a shutdown signal:

• SIGINT - interrupt (ctrl-C)
• SIGTERM - terminate (kill)
• SIGQUIT - quit (ctrl-)
• SIGHUP - hangup (terminal disconnected)
• SIGXCPU - cpu consumption soft limit exceeded
• SIGXFZ - file size limit exceeded
• SIGPWR - ACPI (or similar) power down

fork()

static pid_t process::fork ( )

static

Creates a child process. The child is a duplicate of the parent inheriting file descriptors and a copy of the parent's address space. The child does not have access to the parent's address space. In the parent process, the process id of the child is returned. In the child process, 0 is returned. -1 is returned if an error occurred and no child is forked.

getChildStateChange()

static pid_t process::getChildStateChange ( pid_t pid, bool wait, bool ignorestop, bool ignorecontinue, childstatechange * newstate, int32_t * exitstatus, int32_t * signum, bool * coredump )

static

This method causes the process to get information about a change in process state for the specified child process id "pid" (ie. whether it was stopped, continued or killed).

Returns the process id of the child that changed state, -1 if an error occurred, and 0 if "wait" is set false and no child has changed state.

Setting "pid" to -1 causes the method to get information on any child of the current process.

Waiting on child processes to exit prevents so-called "zombie" processes from occurring. However, this method only waits when called. To configure a process to automatically wait on and respond when any child process exits, use setWaitForChildren(true).

If "wait" is set true then the method waits until a child state-change occurs. Otherwise the method returns immediately.

If "ignorestop" is set true then the method ignores when a child process has been stopped.

If "ignorecontinue" is set true then the method ignores when a child process has been continued.

On exit, if "newstate" is non-NULL then it is populated with one of the members of the childstatechange enum, indicating the new state of the child process.

If "newstate" is EXIT_CHILDSTATECHANGE and "exitstatus" is non-null then "exitstatus" is populated with the exit status of the child process.

If "newstate" is TERMINATED_CHILDSTATECHANGE or STOPPED_CHILDSTATECHANGE and "signum" is non-null then "signum" is populated with the signum that terminated or stopped the child process.

If "newstate" is TERMINATED_CHILDSTATECHANGE and "coredump" is non-null then "coredump" is set true if a core dump was produced and false otherwise.

getCrashSignalHandler()

static signalhandler * process::getCrashSignalHandler ( )

static

Returns the signalhandler used internally to handle a crash. Calls to exitOnCrash(), exitOnCrashOrShutDown(), setShutDownFlagOnCrash(), or setShutDownFlagOnCrashOrShutDown() configure this set to include a standard set of crash signals. If you would like to add signals, or change the signal handler from the default to a custom handler, then you can use this method to get the signalhandler.

getEffectiveGroupId()

static gid_t process::getEffectiveGroupId ( )

static

Returns the effective group id of the current process.

getEffectiveUserId()

static uid_t process::getEffectiveUserId ( )

static

Returns the effective user id of the current process.

getGroupId()

static gid_t process::getGroupId ( )

static

Returns the real group id of the current process.

getParentProcessId()

static pid_t process::getParentProcessId ( )

static

Returns the process id of the parent process of the current process.

getProcessGroupId() [1/2]

static pid_t process::getProcessGroupId ( )

static

Returns the process group id of the current process.

getProcessGroupId() [2/2]

static pid_t process::getProcessGroupId ( pid_t pid )

static

Returns the process group id of the process pid.

getProcessId()

static pid_t process::getProcessId ( )

static

Returns the process id of the current process.

getRetryFailedFork()

static bool process::getRetryFailedFork ( )

static

Returns true if failed fork() calls will be retried and false otherwise.

getSessionId() [1/2]

static pid_t process::getSessionId ( )

static

Returns the session id of the current process.

getSessionId() [2/2]

static pid_t process::getSessionId ( pid_t pid )

static

Returns the session id of the process pid.

getShutDownFlag()

static bool process::getShutDownFlag ( )

static

Returns the value of a global shutdown flag indicating whether or not the process has been asked to shut down.

For example...

The "shutdownhandler" of setShutDownHandler() may simply call setShutDownFlag(true) and then return.

The process may then call getShutDownFlag() at strategic points to see if a shutdown has been requested and shut down gracefully if it has.

All rudiments methods that retry interrupted system calls (see retryInterrupted*() methods of various classes) exit if this flag is set upon return from the system call.

getShutDownSignal()

static int32_t process::getShutDownSignal ( )

static

Returns the value of a global variable indicating which signal was received that initiated the process shut down.

For example...

The "shutdownhandler" of setShutDownHandler() may call setShutDownSignal(signum), passing it the value of its "signum" parameter.

Once the process determines that a shutdown has been initiated (perhaps by checking getShutDownFlag(), it may then call getShutDownSignal() to query which signal was received that initiated the shutdown and respond differently to different signals.

getShutDownSignalHandler()

static signalhandler * process::getShutDownSignalHandler ( )

static

Returns the signalhandler used internally to handle a shut down. Calls to exitOnShutDown(), exitOnCrashOrShutDown(), setShutDownFlagOnShutDown(), or setShutDownFlagOnCrashOrShutDown() configure this set to include a standard set of shutdown signals. If you would like to add signals, or change the signal handler from the default to a custom handler, then you can use this method to get the signalhandler.

getUserId()

static uid_t process::getUserId ( )

static

Returns the real user id of the current process.

raiseSignal()

static bool process::raiseSignal ( int32_t signum )

static

Send signal "signum" to self. Returns true on success and false on failure.

registerExitHandler()

static bool process::registerExitHandler ( void(*)(void) handler )

static

Allows you to register a function to run when the process exits normally.

May be called multiple times to register multiple functions to be run at exit. The functions will be called in the reverse order of their registration.

Note that there is no way to deregister a function from running at exit once it has been registered.

Returns true on success and false on failure.

sendSignal()

static bool process::sendSignal ( pid_t processid, int32_t signum )

static

Send signal "signum" to process "processid". Returns true on success and false on failure.

setCrashHandler()

static void process::setCrashHandler ( void(*)(int32_t) crashhandler )

static

Allows you to designate a function to run if the process crashes with a program error signal - SIGABRT, SIGFPE, SIGILL, SIGSEGV, SIGBUS, SIGIOT, SIGEMT or SIGSYS.

Each time setCrashHandler() is called, the crash handler replaces the previously designated handler.

setEffectiveGroup()

static bool process::setEffectiveGroup ( const char * groupname )

static

Sets the effective group id of the current process to the group id of "groupname". Does not set the real or saved group ids.

Returns true on success and false on failure.

setEffectiveGroupId()

static bool process::setEffectiveGroupId ( gid_t gid )

static

Sets the effective group id of the current process to gid. Does not set the real or saved group ids.

Returns true on success and false on failure.

setEffectiveUser()

static bool process::setEffectiveUser ( const char * username )

static

Sets the effective user id of the current process to the user id of "username". Does not set the real or saved user ids.

Returns true on success and false on failure.

setEffectiveUserId()

static bool process::setEffectiveUserId ( uid_t uid )

static

Sets the effective user id of the current process to uid. Does not set the real or saved user ids.

Returns true on success and false on failure.

setFileCreationMask()

static mode_t process::setFileCreationMask ( mode_t mask )

static

Set file/directory creation mode mask to "mask". Returns the mask that was previously in effect.

setGroup()

static bool process::setGroup ( const char * groupname )

static

Sets the effective group id of the current process to the group id of "groupname". If the effective group id is root, the real and saved group ids are also set.

Returns true on success and false on failure.

setGroupId()

static bool process::setGroupId ( gid_t gid )

static

Sets the effective group id of the current process to gid. If the effective group id is root, the real and saved group ids are also set.

Returns true on success and false on failure.

setProcessGroupId() [1/3]

static bool process::setProcessGroupId ( )

static

Sets the process group id of the current process to the current process id.

setProcessGroupId() [2/3]

static bool process::setProcessGroupId ( pid_t pgid )

static

Sets the process group id of the current process to pgid.

setProcessGroupId() [3/3]

static bool process::setProcessGroupId ( pid_t pid, pid_t pgid )

static

Sets the process group id of the process pid to pgid.

setRealAndEffectiveGroupId()

static bool process::setRealAndEffectiveGroupId ( gid_t gid, gid_t egid )

static

Sets the real group id of the current process to gid and the effective group id of the current process to egid. If the real group id is set or the effective group id is set to a value not equal to the previous real group id, the saved group id is set to the new effective group id.

Returns true on success and false on failure.

setRealAndEffectiveUserId()

static bool process::setRealAndEffectiveUserId ( uid_t uid, uid_t euid )

static

Sets the real user id of the current process to uid and the effective user id of the current process to euid. If the real user id is set or the effective user id is set to a value not equal to the previous real user id, the saved user id is set to the new effective user id.

Returns true on success and false on failure.

setRetryFailedFork()

static void process::setRetryFailedFork ( bool retry )

static

If "retry" is true then fork() calls will be automatically retried if they fail eg. because of insufficient system resources. If "retry" is set false then, if a fork() fails, the system error is set to EAGAIN and fork() returns -1.

Defaults to true.

setShutDownFlag()

static void process::setShutDownFlag ( bool shutdownflag )

static

Sets a global shutdown flag indicating whether or not the process has been asked to shut down.

For example...

The "shutdownhandler" of setShutDownHandler() may simply call setShutDownFlag(true) and then return.

The process may then call getShutDownFlag() at strategic points to see if a shutdown has been requested and shut down gracefully if it has.

All rudiments methods that retry interrupted system calls (see retryInterrupted*() methods of various classes) exit if this flag is set upon return from the system call.

setShutDownFlagOnCrash()

static void process::setShutDownFlagOnCrash ( )

static

Sets up a default handler that sets the global shutdown flag (see setShutDownFlag()) to true the process crashes with a program error signal - SIGABRT, SIGFPE, SIGILL, SIGSEGV, SIGBUS, SIGIOT, SIGEMT or SIGSYS.

setShutDownFlagOnCrashOrShutDown()

static void process::setShutDownFlagOnCrashOrShutDown ( )

static

Calls setShutDownFlagOnShutDown(), setShutDownFlagOnCrash() below.

setShutDownFlagOnShutDown()

static void process::setShutDownFlagOnShutDown ( )

static

Sets up a default handler that sets the global shutdown flag (see setShutDownFlag()) to true when the process receives a termination signal:

• SIGINT - interrupt (ctrl-C)
• SIGTERM - terminate (kill)
• SIGQUIT - quit (ctrl-)
• SIGHUP - hangup (terminal disconnected)
• SIGXCPU - cpu consumption soft limit exceeded
• SIGXFSZ - file size limit exceeded
• SIGPWR - ACPI (or similar) power down

setShutDownHandler()

static void process::setShutDownHandler ( void(*)(int32_t) shutdownhandler )

static

Allows you to designate a function to run when the process receives a termination signal:

• SIGINT - interrupt (ctrl-C)
• SIGTERM - terminate (kill)
• SIGQUIT - quit (ctrl-)
• SIGHUP - hangup (terminal disconnected)
• SIGXCPU - cpu consumption soft limit exceeded
• SIGXFZ - file size limit exceeded
• SIGPWR - ACPI (or similar) power down

Each time setShutDownHandler() is called, the shut down handler replaces the previously designated handler.

setShutDownSignal()

static void process::setShutDownSignal ( int32_t signum )

static

Sets a global variable indicating which signal was received that initiated the process shut down.

For example...

The "shutdownhandler" of setShutDownHandler() may call setShutDownSignal(signum), passing it the value of its "signum" parameter.

Once the process determines that a shutdown has been initiated (perhaps by checking getShutDownFlag(), it may then call getShutDownSignal() to query which signal was received that initiated the shutdown and respond differently to different signals.

setUser()

static bool process::setUser ( const char * username )

static

Sets the effective user id of the current process to the user id of "username". If the effective user id is root, the real and saved user ids are also set.

Returns true on success and false on failure.

setUserId()

static bool process::setUserId ( uid_t uid )

static

Sets the effective user id of the current process to uid. If the effective user id is root, the real and saved user ids are also set.

Returns true on success and false on failure.

setWaitForChildren()

static void process::setWaitForChildren ( bool wait )

static

If "wait" is true then this method causes the process will automatically wait on child processes which have exited, preventing so-called "zombie" processes from occurring.

If "wait" is false then this method causes the process not to wait on child processes which have exited. Ordinarily, you'd want to wait on child processes, but that interferes with the behavior of WEXITSTATUS() after a call to system() (and possibly other calls). This method allows you to disable waiting on child processes.

Defaults to false.

spawn()

static pid_t process::spawn ( const char * command, const char *const * args, bool detached )

static

Runs "command" with arguments "args" as a new process. If "detached" is true then the process is started in the background. Use this instead of a combinination of fork() and exec() as it is more efficient on some platforms. Note that the first element of array "args" should be the name of the command that you want to run, typically the same as "command". "args" should be NULL terminated. Returns the process id of the child process or -1 if an error occurred.

supportsFork()

static bool process::supportsFork ( )

static

Returns true of this platform supports fork() and false otherwise.

supportsGetChildStateChange()

static bool process::supportsGetChildStateChange ( )

static

Returns true if the platform supports waiting for a child process to exit or change state and false otherwise.

wait() [1/2]

static bool process::wait ( pid_t pid )

static

This methods causes the process to wait until child process "pid" exits. Returns true on success and false on failure.

wait() [2/2]

static bool process::wait ( pid_t pid, int32_t * exitstatus )

static

This methods causes the process to wait until child process "pid" exits. If "exitstatus" is non-null then it is populated with the exit status of the child process. Returns true on success and false on failure.

writeBacktrace() [1/4]

static void process::writeBacktrace ( const char * filename )

static

Appends the backtrace for the current thread to "filename".

If "filename" doesn't already exist then it will be created with rw----— permissions.

A maximum of 128 stack frames will be included in the backtrace.

(Not supported on all platforms.)

writeBacktrace() [2/4]

static void process::writeBacktrace ( const char * filename, mode_t perms, uint32_t maxframes )

static

Appends the backtrace for the current thread to "filename".

If "filename" doesn't already exist then it will be created with "perms" permissions.

A maximum of "maxframes" stack frames will be included in the backtrace.

(Not supported on all platforms.)

writeBacktrace() [3/4]

static void process::writeBacktrace ( output * out )

static

Writes the backtrace for the current thread to "buffer".

A maximum of 128 stack frames will be included in the backtrace.

(Not supported on all platforms.)

writeBacktrace() [4/4]

static void process::writeBacktrace ( output * out, uint32_t maxframes )

static

Writes the backtrace for the current thread to "buffer".

"maxframes" indicates the maximum number of stack frames to include in the backtrace.

(Not supported on all platforms.)