blocxx: BLOCXX_NAMESPACE::Exec Namespace Reference

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.

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().

Referenced by executeProcessAndGatherOutput().

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.

References BLOCXX_NAMESPACE::EnvVars::E_CURRENT_ENVIRONMENT, and executeProcessAndGatherOutput().

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.

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_ASSERT, BLOCXX_THROW, BLOCXX_THROW_ERRNO_MSG, BLOCXX_NAMESPACE::IntrusiveReference< T >::cast_to(), BLOCXX_NAMESPACE::FileSystem::close(), BLOCXX_NAMESPACE::UnnamedPipe::createUnnamedPipe(), BLOCXX_NAMESPACE::PopenStreams::err(), ETIMEDOUT, i, BLOCXX_NAMESPACE::PopenStreams::in(), NSIG, BLOCXX_NAMESPACE::PopenStreams::out(), BLOCXX_NAMESPACE::PopenStreams::pid(), BLOCXX_NAMESPACE::Array< T >::size(), and BLOCXX_NAMESPACE::FileSystem::write().

Referenced by executeProcessAndGatherOutput(), and safePopen().

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(), BLOCXX_NAMESPACE::String::length(), 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 i, NSIG, BLOCXX_NAMESPACE::PopenStreams::pid(), BLOCXX_NAMESPACE::Array< T >::size(), and BLOCXX_NAMESPACE::ThreadImpl::testCancel().

Referenced by BLOCXX_NAMESPACE::StackTrace::printStackTrace(), and safeSystem().

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(), and safeSystem().

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

Definition at line 291 of file Exec.hpp.

BLOCXX_NAMESPACE::Exec Namespace Reference

Classes

Enumerations

Functions

Variables

Enumeration Type Documentation

Function Documentation

Variable Documentation


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