jProcessUtil.cpp File Reference

#include "jProcessUtil.h"
#include "JThisProcess.h"
#include "JPtrArray-JString.h"
#include "JProcessError.h"
#include "JRegex.h"
#include "JStringIterator.h"
#include "JStringMatch.h"
#include "JStdError.h"
#include "jStreamUtil.h"
#include "jGlobals.h"
#include <unistd.h>
#include <stdlib.h>
#include <stdio.h>
#include "jSignal.h"
#include "jFileUtil.h"
#include "jDirUtil.h"
#include "jSysUtil.h"
#include <ace/OS_NS_sys_wait.h>
#include "jErrno.h"
#include "jAssert.h"

Include dependency graph for jProcessUtil.cpp:

Functions
void	JCleanArg (JString *arg)
bool	JProgramAvailable (const JString &programName, JString *fixedName)
JString	JPrepArgForExec (const JString &arg)
void	JParseArgsForExec (const JString &cmd, JPtrArray< JString > *argList)
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)
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)
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)
JError	JExecute (const JString &cmd, pid_t *childPID, const JExecuteAction toAction, int *toFD, const JExecuteAction fromAction, int *fromFD, const JExecuteAction errAction, int *errFD)
JError	JExecute (const JPtrArray< JString > &argList, pid_t *childPID, const JExecuteAction toAction, int *toFD, const JExecuteAction fromAction, int *fromFD, const JExecuteAction errAction, int *errFD)
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)
JError	JWaitForChild (const bool block, pid_t *pid, ACE_exitcode *status)
JError	JWaitForChild (const pid_t pid, ACE_exitcode *status)
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)
bool	JProgramAvailable (const JString &programName)
bool	JWillIncludeCWDOnPath ()
void	JShouldIncludeCWDOnPath (const bool includeCWD)

Function Documentation

JCleanArg()

void JCleanArg

(

JString *

arg

)

Removes single backslashes and unbackslashed quotes.

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.

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() [1/2]

bool JProgramAvailable

(

const JString &

programName

)

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

JProgramAvailable() [2/2]

bool JProgramAvailable	(	const JString &	programName,
		JString *	fixedName
	)

JSendSignalToProcess()

JError JSendSignalToProcess	(	const pid_t	pid,
		const int	signal
	)

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
	)

JWillIncludeCWDOnPath()

bool JWillIncludeCWDOnPath

(

)

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