jProcessUtil.h File Reference

#include "JPtrArray.h"
#include "JProcessError.h"
#include <unistd.h>
#include <sys/types.h>
#include <ace/Basic_Types.h>

Include dependency graph for jProcessUtil.h:

This graph shows which files directly or indirectly include this file:

Enumerations
enum	JExecuteAction {   kJIgnoreConnection ,   kJCreatePipe ,   kJAttachToFD ,   kJTossOutput ,   kJAttachToFromFD ,   kJForceNonblockingPipe }
enum	JChildExitReason {   kJChildFinished ,   kJChildSignalled ,   kJChildStopped }

Functions
bool	JWillIncludeCWDOnPath ()
void	JShouldIncludeCWDOnPath (const bool includeCWD)
bool	JProgramAvailable (const JString &programName)
JError	JExecute (const JString &cmd, pid_t *childPID, const JExecuteAction toAction=kJIgnoreConnection, int *toFD=nullptr, const JExecuteAction fromAction=kJIgnoreConnection, int *fromFD=nullptr, const JExecuteAction errAction=kJIgnoreConnection, int *errFD=nullptr)
JError	JExecute (const JPtrArray< JString > &argList, pid_t *childPID, const JExecuteAction toAction=kJIgnoreConnection, int *toFD=nullptr, const JExecuteAction fromAction=kJIgnoreConnection, int *fromFD=nullptr, const JExecuteAction errAction=kJIgnoreConnection, int *errFD=nullptr)
JError	JExecute (const JUtf8Byte *argv[], const JSize size, pid_t *childPID, const JExecuteAction toAction=kJIgnoreConnection, int *toFD=nullptr, const JExecuteAction fromAction=kJIgnoreConnection, int *fromFD=nullptr, const JExecuteAction errAction=kJIgnoreConnection, int *errFD=nullptr)
JError	JExecute (const JString &workingDirectory, const JString &cmd, pid_t *childPID, const JExecuteAction toAction=kJIgnoreConnection, int *toFD=nullptr, const JExecuteAction fromAction=kJIgnoreConnection, int *fromFD=nullptr, const JExecuteAction errAction=kJIgnoreConnection, int *errFD=nullptr)
JError	JExecute (const JString &workingDirectory, const JPtrArray< JString > &argList, pid_t *childPID, const JExecuteAction toAction=kJIgnoreConnection, int *toFD=nullptr, const JExecuteAction fromAction=kJIgnoreConnection, int *fromFD=nullptr, const JExecuteAction errAction=kJIgnoreConnection, int *errFD=nullptr)
JError	JExecute (const JString &workingDirectory, const JUtf8Byte *argv[], const JSize size, pid_t *childPID, const JExecuteAction toAction=kJIgnoreConnection, int *toFD=nullptr, const JExecuteAction fromAction=kJIgnoreConnection, int *fromFD=nullptr, const JExecuteAction errAction=kJIgnoreConnection, int *errFD=nullptr)
JString	JPrepArgForExec (const JString &arg)
void	JParseArgsForExec (const JString &cmd, JPtrArray< JString > *argList)
JError	JWaitForChild (const bool block, pid_t *pid, ACE_exitcode *status=nullptr)
JError	JWaitForChild (const pid_t pid, ACE_exitcode *status=nullptr)
JChildExitReason	JDecodeChildExitReason (const ACE_exitcode status, int *result)
JString	JPrintChildExitReason (const JChildExitReason reason, const int result)
JError	JSendSignalToProcess (const pid_t pid, const int signal)
JError	JSendSignalToGroup (const pid_t pgid, const int signal)
JError	JSetProcessPriority (const pid_t pid, const int priority)
JError	JGetPGID (const pid_t pid, pid_t *pgid)
JError	JRunProgram (const JString &cmd, JString *errOutput)

Enumeration Type Documentation

JChildExitReason

enum JChildExitReason

Enumerator
kJChildFinished
kJChildSignalled
kJChildStopped

JExecuteAction

enum JExecuteAction

Enumerator
kJIgnoreConnection
kJCreatePipe
kJAttachToFD
kJTossOutput
kJAttachToFromFD
kJForceNonblockingPipe

Function Documentation

JDecodeChildExitReason()

JChildExitReason JDecodeChildExitReason	(	const ACE_exitcode	status,
		int *	result
	)

Returns one of:

kJChildFinished  -- *result contains return value from main()
kJChildSignalled -- *result contains signal that was sent
kJChildStopped   -- *result contains signal that was sent

JExecute() [1/6]

JError JExecute	(	const JPtrArray< JString > &	argList,
		pid_t *	childPID,
		const JExecuteAction	toAction,
		int *	toFD,
		const JExecuteAction	fromAction,
		int *	fromFD,
		const JExecuteAction	errAction,
		int *	errFD
	)

Convenience version that calls JExecute(char**).

JExecute() [2/6]

JError JExecute	(	const JString &	cmd,
		pid_t *	childPID,
		const JExecuteAction	toAction,
		int *	toFD,
		const JExecuteAction	fromAction,
		int *	fromFD,
		const JExecuteAction	errAction,
		int *	errFD
	)

Splits up the given string by whitespace (except that which is quoted) and passes the resulting array of strings to the main version of JExecute().

JExecute() [3/6]

JError JExecute	(	const JString &	workingDirectory,
		const JPtrArray< JString > &	argList,
		pid_t *	childPID,
		const JExecuteAction	toAction,
		int *	toFD,
		const JExecuteAction	fromAction,
		int *	fromFD,
		const JExecuteAction	errAction,
		int *	errFD
	)

Convenience version that specifies a working directory.

JExecute() [4/6]

JError JExecute	(	const JString &	workingDirectory,
		const JString &	cmd,
		pid_t *	childPID,
		const JExecuteAction	toAction,
		int *	toFD,
		const JExecuteAction	fromAction,
		int *	fromFD,
		const JExecuteAction	errAction,
		int *	errFD
	)

Convenience version that specifies a working directory.

JExecute() [5/6]

JError JExecute	(	const JString &	workingDirectory,
		const JUtf8Byte *	argv[],
		const JSize	size,
		pid_t *	childPID,
		const JExecuteAction	toAction,
		int *	toFD,
		const JExecuteAction	fromAction,
		int *	fromFD,
		const JExecuteAction	errAction,
		int *	errFD
	)

Convenience version that specifies a working directory.

JExecute() [6/6]

JError JExecute	(	const JUtf8Byte *	argv[],
		const JSize	size,
		pid_t *	childPID,
		const JExecuteAction	toAction,
		int *	toFD,
		const JExecuteAction	origFromAction,
		int *	fromFD,
		const JExecuteAction	errAction,
		int *	errFD
	)

argv[0] can either be a full path or just a name. If it is just a name, we search for it just like the shell would.

argv[] must be terminated with a nullptr entry.

size must be sizeof(argv[]). JExecute automatically divides by sizeof(char*). We required this so we can check that argv is nullptr terminated. It is way too easy to forget to do this otherwise.

If childPID != nullptr, it is set to the pid of the child process. Otherwise, JExecute() blocks until the child exits.

Actions:

kJIgnoreConnection  don't create a pipe, use default connection

kJCreatePipe        create a pipe and return the end that the
                    parent should use

kJAttachToFD        connect the child to the descriptor passed in
                    via the corresponding int* (don't create pipe)

kJTossOutput        connects output to /dev/null
                    (only works for fromAction and errAction)

kJAttachToFromFD    connect stderr to stdout
                    (only works for errAction)

kJForceNonblockingPipe  same as kJCreatePipe, but monitors and turns
                        off non-blocking mode
                        (only works for fromAction)

For kJAttachToFD, toFD has to be something that can be read from, and fromFD and errFD have to be something that can be written to.

Can return JProgramNotAvailable, JNoProcessMemory, JNoKernelMemory.

Security Note:
This function calls execvp(), which uses the current search path to
find the program to run.  In most cases, this is desirable because
each UNIX system has its own ideas about where to put "standard"
programs.  For suid root programs, however, this is dangerous.
Therefore, when writing suid root programs, always call this function
with a full path so you know exactly which binary is being run.

JGetPGID()

JError JGetPGID	(	const pid_t	pid,
		pid_t *	pgid
	)

On FreeBSD, getpgid() isn't implemented because POSIX decided that it wasn't necessary since shells don't need it! Morons!

So we use the proc file system's 'status' file, which has the format

name pid ppid pgid ...

FreeBSD implementation written by Ivan Pascal pasca.nosp@m.l@in.nosp@m.fo.ts.nosp@m.u.ru

JParseArgsForExec()

void JParseArgsForExec	(	const JString &	cmd,
		JPtrArray< JString > *	argList
	)

Splits up the given string by whitespace (except that which is quoted). Unquoted semi-colons are converted to separate arguments.

JPrepArgForExec()

JString JPrepArgForExec

(

const JString &

arg

)

Inserts backslashes in front of metacharacters and then puts double quotes around the entire string if it contains spaces.

JPrintChildExitReason()

JString JPrintChildExitReason	(	const JChildExitReason	reason,
		const int	result
	)

JProgramAvailable()

bool JProgramAvailable

(

const JString &

programName

)

Returns true if the given program can be run by JExecute().

JRunProgram()

JError JRunProgram	(	const JString &	cmd,
		JString *	errOutput
	)

This convenience function runs the specified command and blocks until it finishes. If the program prints anything to stderr, *errOutput contains the text.

If you don't want to block, use JSimpleProcess.

JSendSignalToGroup()

JError JSendSignalToGroup	(	const pid_t	pgid,
		const int	signal
	)

JSendSignalToProcess()

JError JSendSignalToProcess	(	const pid_t	pid,
		const int	signal
	)

JSetProcessPriority()

JError JSetProcessPriority	(	const pid_t	pid,
		const int	priority
	)

JShouldIncludeCWDOnPath()

void JShouldIncludeCWDOnPath

(

const bool

includeCWD

)

JWaitForChild() [1/2]

JError JWaitForChild	(	const bool	block,
		pid_t *	pid,
		ACE_exitcode *	status
	)

Wait until a child process finishes. If !block and no child has finished, *pid=0.

status can be nullptr.

JWaitForChild() [2/2]

JError JWaitForChild	(	const pid_t	pid,
		ACE_exitcode *	status = nullptr
	)

JWillIncludeCWDOnPath()

bool JWillIncludeCWDOnPath

(

)

Turn this option on to automatically include ./ on the execution path.