BLOCXX_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 using current process's environment, 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 executeProcessAndGatherOutput (const Array< String > &command, String &stdOutput, String &errOutput, int &processstatus, const EnvVars &envVars, int timeoutsecs=INFINITE_TIMEOUT, int outputlimit=-1, const String &input=String())
 Run a process, collect the standard output and standard error outputs separately, 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 BLOCXX_NAMESPACE::Exec::EOutputSource
 

Enumerator:
E_STDOUT 
E_STDERR 

Definition at line 323 of file Exec.hpp.

enum BLOCXX_NAMESPACE::Exec::EProcessRunning
 

Enumerator:
E_PROCESS_RUNNING 
E_PROCESS_EXITED 

Definition at line 351 of file Exec.hpp.


Function Documentation

void BLOCXX_NAMESPACE::Exec::executeProcessAndGatherOutput const Array< String > &  command,
String &  stdOutput,
String &  errOutput,
int &  processstatus,
const EnvVars &  envVars,
int  timeoutsecs = INFINITE_TIMEOUT,
int  outputlimit = -1,
const String &  input = String()
 

Run a process, collect the standard output and standard error outputs separately, 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.
stdOutput An out parameter, the standard output (stdout) of the process will be appended to this string.
errOutput An out parameter, the standard error output (stderr) of the process will be appended to this string.
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 a empty (default) process environment 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 899 of file Exec.cpp.

References processInputOutput(), BLOCXX_NAMESPACE::Array< T >::push_back(), and safePopen().

void BLOCXX_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.
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 a empty (default) process environment 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 869 of file Exec.cpp.

References processInputOutput(), BLOCXX_NAMESPACE::Array< T >::push_back(), and safePopen().

void BLOCXX_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 using current process's environment, 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.
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 859 of file Exec.cpp.

void BLOCXX_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 931 of file Exec.cpp.

References processInputOutput(), and BLOCXX_NAMESPACE::Array< T >::push_back().

void BLOCXX_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.
processStatuses 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).
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.
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.
Exceptions:
ExecErrorException on error.
ExecTimeoutException if the process hasn't finished within timeoutSecs.

Definition at line 993 of file Exec.cpp.

References BLOCXX_NAMESPACE::Array< T >::clear(), BLOCXX_NAMESPACE::Exec::InputCallback::getData(), BLOCXX_NAMESPACE::Array< T >::resize(), and BLOCXX_NAMESPACE::Array< T >::size().

Referenced by executeProcessAndGatherOutput(), and gatherOutput().

PopenStreams BLOCXX_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 587 of file Exec.cpp.

References BLOCXX_THROW, and BLOCXX_NAMESPACE::Array< T >::size().

PopenStreams BLOCXX_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 a empty (default) process environment 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 580 of file Exec.cpp.

References BLOCXX_NAMESPACE::EnvVars::getenvp(), and safePopen().

PopenStreams BLOCXX_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 562 of file Exec.cpp.

References BLOCXX_THROW_ERRNO_MSG, BLOCXX_NAMESPACE::String::c_str(), BLOCXX_NAMESPACE::PopenStreams::in(), and BLOCXX_NAMESPACE::String::length().

Referenced by executeProcessAndGatherOutput(), and safePopen().

int BLOCXX_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 448 of file Exec.cpp.

References BLOCXX_NAMESPACE::Array< T >::size().

int BLOCXX_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 a empty (default) process environment 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 Exec.cpp.

References BLOCXX_NAMESPACE::EnvVars::getenvp().


Variable Documentation

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

Definition at line 291 of file Exec.hpp.

Referenced by BLOCXX_NAMESPACE::Select::selectRWPoll(), and BLOCXX_NAMESPACE::Select::selectRWSelect().


Generated on Fri Jun 16 15:39:12 2006 for blocxx by  doxygen 1.4.6