OW_NAMESPACE::Exec Namespace Reference

Classes

class OutputCallback

class InputCallback

class ProcessStatus

Enumerations

enum EOutputSource { E_STDOUT, E_STDERR }

enum EProcessRunning { E_PROCESS_RUNNING, E_PROCESS_EXITED }

Functions

int safeSystem (const Array< String > &command, const EnvVars &envVars)

Execute a command.

int safeSystem (const Array< String > &command, const char *const envp[]=0)

Execute a command.

PopenStreams safePopen (const Array< String > &command, const String &initialInput)

The use of initialInput is deprecated, because it's not safe to use it in a portable manner.

PopenStreams safePopen (const Array< String > &command, const EnvVars &envVars)

Execute a command.

PopenStreams safePopen (const Array< String > &command, const char *const envp[]=0)

Execute a command.

void executeProcessAndGatherOutput (const Array< String > &command, String &output, int &processstatus, int timeoutsecs=INFINITE_TIMEOUT, int outputlimit=-1, const String &input=String())

Run a process, collect the output, and wait for it to exit.

void executeProcessAndGatherOutput (const Array< String > &command, String &output, int &processstatus, const EnvVars &envVars, int timeoutsecs=INFINITE_TIMEOUT, int outputlimit=-1, const String &input=String())

Run a process, collect the output, and wait for it to exit.

void gatherOutput (String &output, PopenStreams &streams, int &processstatus, int timeoutsecs=INFINITE_TIMEOUT, int outputlimit=-1)

Wait for output from a child process.

void processInputOutput (OutputCallback &output, Array< PopenStreams > &streams, Array< ProcessStatus > &processStatuses, InputCallback &input, int timeoutSecs=INFINITE_TIMEOUT)

Send input and wait for output from child processes.

Variables

const int INFINITE_TIMEOUT = -1

Enumeration Type Documentation

enum OW_NAMESPACE::Exec::EOutputSource

Enumerator:

E_STDOUT

E_STDERR

Definition at line 323 of file OW_Exec.hpp.

enum OW_NAMESPACE::Exec::EProcessRunning

Enumerator:

E_PROCESS_RUNNING

E_PROCESS_EXITED

Definition at line 351 of file OW_Exec.hpp.

Function Documentation

void OW_NAMESPACE::Exec::executeProcessAndGatherOutput ( const Array< String > & command,

String & output,

int & processstatus,

const EnvVars & envVars,

int timeoutsecs = INFINITE_TIMEOUT,

int outputlimit = -1,

const String & input = String()

)

Run a process, collect the output, and wait for it to exit.
The function returns when the process exits. In the case that the child process doesn't exit, if a timout is specified, then an ExecTimeoutException is thrown. If the process outputs more bytes than outputlimit, an ExecBufferFullException is thrown. This function will not search the path for command[0], so the absolute path to the binary should be specified. If the path needs to be searched, you can set command[0] = "/bin/sh"; command[1] = "-c"; and then fill in the rest of the array with the command you wish to execute. Exercise caution when doing this, as you may be creating a security hole. If the process does not terminate by itself, or if an exception is thrown because a limit has been reached (time or output), then the the following steps will be taken to attempt to terminate the child process. 1. The input and output pipes will be closed. This may cause the child to get a SIGPIPE which may terminate it. 2. If the child still hasn't terminated after 10 seconds, a SIGTERM is sent. 3. If the child still hasn't terminated after 10 seconds, a SIGKILL is sent.

Parameters:

command command[0] is the binary to be executed. command[1] .. command[n] are the command line parameters to the command.

output An out parameter, the process output will be appended to this string.

streams The connection to the child process.

processstatus An out parameter, which will contain the process status. It is only valid if the funtion returns. In the case an exception is thrown, it's undefined. It should be evaluated using the family of macros (WIFEXITED(), WEXITSTATUS(), etc.) from "sys/wait.h"

envVars An EnvVars object that contains the environment variables which will be pass as the environment to the new process. If envVars doesn't contain any environment variables, then the current process's environment variables will be used.

timeoutsecs Specifies the number of seconds to wait for the process to exit. If the process hasn't exited after timeoutsecs seconds, an ExecTimeoutException will be thrown, and the process will be killed. If timeoutsecs == INFINITE_TIMEOUT, the timeout will be infinite, and a ExecTimeoutException will not be thrown.

outputlimit Specifies the maximum size of the parameter output, in order to constrain possible memory usage. If the process outputs more data than will fit into output, then an ExecBufferFullException is thrown, and the process will be killed. If outputlimit < 0, the limit will be infinite, and an ExecBufferFullException will not be thrown.

input Data to be written to the child's stdin. After the data has been written, stdin will be closed.

Exceptions:

ExecErrorException on error.

ExecTimeoutException if the process hasn't finished within timeoutsecs.

ExecBufferFullException if the process output exceeds outputlimit bytes.

Definition at line 860 of file OW_Exec.cpp.
References command, processInputOutput(), OW_NAMESPACE::Array< T >::push_back(), and safePopen().

void OW_NAMESPACE::Exec::executeProcessAndGatherOutput ( const Array< String > & command,

String & output,

int & processstatus,

int timeoutsecs = INFINITE_TIMEOUT,

int outputlimit = -1,

const String & input = String()

)

Run a process, collect the output, and wait for it to exit.
The function returns when the process exits. In the case that the child process doesn't exit, if a timout is specified, then an ExecTimeoutException is thrown. If the process outputs more bytes than outputlimit, an ExecBufferFullException is thrown. This function will not search the path for command[0], so the absolute path to the binary should be specified. If the path needs to be searched, you can set command[0] = "/bin/sh"; command[1] = "-c"; and then fill in the rest of the array with the command you wish to execute. Exercise caution when doing this, as you may be creating a security hole. If the process does not terminate by itself, or if an exception is thrown because a limit has been reached (time or output), then the the following steps will be taken to attempt to terminate the child process. 1. The input and output pipes will be closed. This may cause the child to get a SIGPIPE which may terminate it. 2. If the child still hasn't terminated after 10 seconds, a SIGTERM is sent. 3. If the child still hasn't terminated after 10 seconds, a SIGKILL is sent.

Parameters:

command command[0] is the binary to be executed. command[1] .. command[n] are the command line parameters to the command.

output An out parameter, the process output will be appended to this string.

streams The connection to the child process.

processstatus An out parameter, which will contain the process status. It is only valid if the funtion returns. In the case an exception is thrown, it's undefined. It should be evaluated using the family of macros (WIFEXITED(), WEXITSTATUS(), etc.) from "sys/wait.h"

timeoutsecs Specifies the number of seconds to wait for the process to exit. If the process hasn't exited after timeoutsecs seconds, an ExecTimeoutException will be thrown, and the process will be killed. If timeoutsecs == INFINITE_TIMEOUT, the timeout will be infinite, and a ExecTimeoutException will not be thrown.

outputlimit Specifies the maximum size of the parameter output, in order to constrain possible memory usage. If the process outputs more data than will fit into output, then an ExecBufferFullException is thrown, and the process will be killed. If outputlimit < 0, the limit will be infinite, and an ExecBufferFullException will not be thrown.

input Data to be written to the child's stdin. After the data has been written, stdin will be closed.

Exceptions:

ExecErrorException on error.

ExecTimeoutException if the process hasn't finished within timeoutsecs.

ExecBufferFullException if the process output exceeds outputlimit bytes.

Definition at line 851 of file OW_Exec.cpp.
References command.

void OW_NAMESPACE::Exec::gatherOutput ( String & output,

PopenStreams & streams,

int & processstatus,

int timeoutsecs = INFINITE_TIMEOUT,

int outputlimit = -1

)

Wait for output from a child process.
The function returns when the process exits. In the case that the child process doesn't exit, if a timout is specified, then an ExecTimeoutException is thrown. If the process outputs more bytes than outputlimit, an ExecBufferFullException is thrown.

Parameters:

output An out parameter, the process output will be appended to this string.

streams The connection to the child process.

processstatus An out parameter, which will contain the process status. It is only valid if the funtion returns. In the case an exception is thrown, it's undefined. It should be evaluated using the family of macros (WIFEXITED(), WEXITSTATUS(), etc.) from "sys/wait.h"

timeoutsecs Specifies the number of seconds to wait for the process to exit. If the process hasn't exited after timeoutsecs seconds, an ExecTimeoutException will be thrown. If timeoutsecs == INFINITE_TIMEOUT, the timeout will be infinite, and no exception will ever be thrown.

outputlimit Specifies the maximum size of the parameter output, in order to constrain possible memory usage. If the process outputs more data than will fit into output, then an ExecBufferFullException is thrown. If outputlimit < 0, the limit will be infinite, and an ExecBufferFullException will never be thrown.

Exceptions:

ProcessError on error.

ProcessTimeout if the process hasn't finished within timeoutsecs.

ProcessBufferFull if the process output exceeds outputlimit bytes.

Definition at line 891 of file OW_Exec.cpp.
References processInputOutput(), and OW_NAMESPACE::Array< T >::push_back().
Referenced by OW_NAMESPACE::runHelper().

void OW_NAMESPACE::Exec::processInputOutput ( OutputCallback & output,

Array< PopenStreams > & streams,

Array< ProcessStatus > & processStatuses,

InputCallback & input,

int timeoutSecs = INFINITE_TIMEOUT

)

Send input and wait for output from child processes.
The function returns when the processes have exited. In the case that a child process doesn't exit, if a timout is specified, then an ExecTimeoutException is thrown. If an exception is thrown by the OutputCallback or InputCallback, it will not be caught.

Parameters:

output A callback, whenever data is received from a process, it will be passed to output.handleData().

streams The connections to the child processes.

processstatus An out parameter, which will contain a enum flag indicating if the process has exited, and if it has, the processes' status. The ProcessStatus::status value, if ProcessStatus::running == E_PROCESS_RUNNING, should be evaluated using the family of macros (WIFEXITED(), WEXITSTATUS(), etc.) from "sys/wait.h" Each status corresponds to the element at the same index in streams. If processStatuses.size() != streams.size(), it will be resized. Each element will be set to (E_PROCESS_RUNNING, 0) or else (E_PROCESS_EXITED, the status of the exited process).

timeoutSecs Specifies the number of seconds to wait for all the processes to exit. If no output has been received and all the processes haven't exited after timeoutSecs seconds, an ExecTimeoutException will be thrown. If timeoutSecs == INFINITE_TIMEOUT, the timeout will be infinite, and no exception will ever be thrown.

input Callback to provide data to be written to the process(es) standard input. input.getData() will be called once for each stream, and subsequently once every time data has been written to a process. output.handleData() may also provide input data via the inputBuffer parameter, it is called every time data is read from a process.

Exceptions:

ExecErrorException on error.

ExecTimeoutException if the process hasn't finished within timeoutSecs.

Definition at line 952 of file OW_Exec.cpp.
References OW_NAMESPACE::Array< T >::clear(), OW_NAMESPACE::Exec::InputCallback::getData(), OW_NAMESPACE::Array< T >::resize(), and OW_NAMESPACE::Array< T >::size().
Referenced by executeProcessAndGatherOutput(), and gatherOutput().

PopenStreams OW_NAMESPACE::Exec::safePopen ( const Array< String > & command,

const char *const envp[] = 0

)

Execute a command.
The command's stdin, stdout, and stderr will be connected via pipes to the parent process that can be accessed from the return value. This function will not search the path for command[0], so the absolute path to the binary should be specified. If the path needs to be searched, you can set command[0] = "/bin/sh"; command[1] = "-c"; and then fill in the rest of the array with the command you wish to execute. This function does *not* block until the child process exits. If the binary specified in command[0] does not exist, execv() will fail, and the return code of the sub-process will be 127. However, this is not distinguishable from the command process returning 127.

Parameters:

command command[0] is the binary to be executed. command[1] .. command[n] are the command line parameters to the command.

envp an array of strings of the form "key=value", which are passed as environment to the new program. envp must be terminated by a null pointer. envp may be 0, in which case the current process's environment variables will be used.

Returns:
A PopenStreams object which can be used to access the child process and/or get it's return value.

Exceptions:

IOException If writing initialInput to the child process input fails. ExecErrorException If command.size() == 0 or if fork() fails.

Definition at line 589 of file OW_Exec.cpp.
References command, and OW_THROW.

PopenStreams OW_NAMESPACE::Exec::safePopen ( const Array< String > & command,

const EnvVars & envVars

)

Execute a command.
The command's stdin, stdout, and stderr will be connected via pipes to the parent process that can be accessed from the return value. This function will not search the path for command[0], so the absolute path to the binary should be specified. If the path needs to be searched, you can set command[0] = "/bin/sh"; command[1] = "-c"; and then fill in the rest of the array with the command you wish to execute. This function does *not* block until the child process exits. If the binary specified in command[0] does not exist, execv() will fail, and the return code of the sub-process will be 127. However, this is not distinguishable from the command process returning 127.

Parameters:

command command[0] is the binary to be executed. command[1] .. command[n] are the command line parameters to the command.

envVars An EnvVars object that contains the environment variables which will be pass as the environment to the new process. If envVars doesn't contain any environment variables, then the current process's environment variables will be used.

Returns:
A PopenStreams object which can be used to access the child process and/or get it's return value.

Exceptions:

IOException If writing initialInput to the child process input fails. ExecErrorException If command.size() == 0 or if fork() fails.

Definition at line 581 of file OW_Exec.cpp.
References command, OW_NAMESPACE::EnvVars::getenvp(), safePopen(), and OW_NAMESPACE::EnvVars::size().

PopenStreams OW_NAMESPACE::Exec::safePopen ( const Array< String > & command,

const String & initialInput

)

The use of initialInput is deprecated, because it's not safe to use it in a portable manner.
Either use the input parameter to processInputOutput or do it manually (not that you must be careful not to cause a deadlock).
Definition at line 563 of file OW_Exec.cpp.
References OW_NAMESPACE::String::c_str(), command, OW_NAMESPACE::PopenStreams::in(), OW_NAMESPACE::String::length(), and OW_THROW_ERRNO_MSG.
Referenced by executeProcessAndGatherOutput(), OW_NAMESPACE::runHelper(), and safePopen().

int OW_NAMESPACE::Exec::safeSystem ( const Array< String > & command,

const char *const envp[] = 0

)

Execute a command.
The command will inherit stdin, stdout, and stderr from the parent process. This function will not search the path for command[0], so the absolute path to the binary should be specified. If the path needs to be searched, you can set command[0] = "/bin/sh"; command[1] = "-c"; and then fill in the rest of the array with the command you wish to execute. This function blocks until the child process exits. Be careful that the command you run doesn't hang. It is recommended to use executeProcessAndGatherOutput() if the command is untrusted.

Parameters:

command command[0] is the binary to be executed. command[1] .. command[n] are the command line parameters to the command.

envp an array of strings of the form "key=value", which are passed as environment to the new program. envp must be terminated by a null pointer. envp may be 0, in which case the current process's environment variables will be used.

Returns:
127 if the execve() call for command[0] fails, -1 if there was another error and the return code of the command otherwise.

Definition at line 449 of file OW_Exec.cpp.
References command.

int OW_NAMESPACE::Exec::safeSystem ( const Array< String > & command,

const EnvVars & envVars

)

Execute a command.
The command will inherit stdin, stdout, and stderr from the parent process. This function will not search the path for command[0], so the absolute path to the binary should be specified. If the path needs to be searched, you can set command[0] = "/bin/sh"; command[1] = "-c"; and then fill in the rest of the array with the command you wish to execute. This function blocks until the child process exits. Be careful that the command you run doesn't hang. It is recommended to use executeProcessAndGatherOutput() if the command is untrusted.

Parameters:

command command[0] is the binary to be executed. command[1] .. command[n] are the command line parameters to the command.

envVars An EnvVars object that contains the environment variables which will be pass as the environment to the new process. If envVars doesn't contain any environment variables, then the current process's environment variables will be used.

Returns:
127 if the execve() call for command[0] fails, -1 if there was another error and the return code of the command otherwise.

Definition at line 441 of file OW_Exec.cpp.
References command, OW_NAMESPACE::EnvVars::getenvp(), and OW_NAMESPACE::EnvVars::size().

Variable Documentation

const int OW_NAMESPACE::Exec::INFINITE_TIMEOUT = -1

Definition at line 291 of file OW_Exec.hpp.
Referenced by OW_NAMESPACE::Select::selectRWPoll(), and OW_NAMESPACE::Select::selectRWSelect().

Generated on Thu Feb 9 09:17:13 2006 for openwbem by

1.4.6


Classes
class	OutputCallback
class	InputCallback
class	ProcessStatus
Enumerations
enum	EOutputSource { E_STDOUT, E_STDERR }
enum	EProcessRunning { E_PROCESS_RUNNING, E_PROCESS_EXITED }
Functions
int	safeSystem (const Array< String > &command, const EnvVars &envVars)
	Execute a command.
int	safeSystem (const Array< String > &command, const char *const envp[]=0)
	Execute a command.
PopenStreams	safePopen (const Array< String > &command, const String &initialInput)
	The use of initialInput is deprecated, because it's not safe to use it in a portable manner.
PopenStreams	safePopen (const Array< String > &command, const EnvVars &envVars)
	Execute a command.
PopenStreams	safePopen (const Array< String > &command, const char *const envp[]=0)
	Execute a command.
void	executeProcessAndGatherOutput (const Array< String > &command, String &output, int &processstatus, int timeoutsecs=INFINITE_TIMEOUT, int outputlimit=-1, const String &input=String())
	Run a process, collect the output, and wait for it to exit.
void	executeProcessAndGatherOutput (const Array< String > &command, String &output, int &processstatus, const EnvVars &envVars, int timeoutsecs=INFINITE_TIMEOUT, int outputlimit=-1, const String &input=String())
	Run a process, collect the output, and wait for it to exit.
void	gatherOutput (String &output, PopenStreams &streams, int &processstatus, int timeoutsecs=INFINITE_TIMEOUT, int outputlimit=-1)
	Wait for output from a child process.
void	processInputOutput (OutputCallback &output, Array< PopenStreams > &streams, Array< ProcessStatus > &processStatuses, InputCallback &input, int timeoutSecs=INFINITE_TIMEOUT)
	Send input and wait for output from child processes.
Variables
const int	INFINITE_TIMEOUT = -1