blocxx
BLOCXX_NAMESPACE::Exec Namespace Reference

Namespaces

namespace  Impl
 

Classes

class  InputCallback
 
class  OutputCallback
 
class  PreExec
 This class is used to specify what spawn() should do between fork and exec. More...
 

Enumerations

enum  EOutputSource { E_STDOUT , E_STDERR }
 

Functions

Process::Status system (const Array< String > &command, const char *const envp[]=0, const Timeout &=Timeout::infinite)
 Execute a command.
 
int safeSystem (const Array< String > &command, const char *const envp[]=0) BLOCXX_DEPRECATED
 This is deprecated.
 
ProcessRef spawnImpl (char const *exec_path, char const *const argv[], char const *const envp[], PreExec &pre_exec)
 
ProcessRef spawn (char const *exec_path, char const *const argv[], char const *const envp[], PreExec &pre_exec)
 Run the executable exec_path in a child process, with argv for the program arguments and envp for the environment.
 
ProcessRef spawn (char const *const argv[], char const *const envp[])
 Variant of spawn that uses StandardPreExec.
 
Process::Status executeProcessAndGatherOutput (char const *const command[], String &output, char const *const envVars[], const Timeout &timeout=Timeout::infinite, int outputlimit=-1, char const *input=0)
 Execute a command and run feedProcessAndGatherOutput() on the process.
 
Process::Status executeProcessAndGatherOutput (char const *const command[], String &output, String &erroutput, char const *const envVars[], const Timeout &timeout=Timeout::infinite, int outputLimit=-1, char const *input=0)
 Execute a command and run feedProcessAndGatherOutput() on the process.
 
BLOCXX_COMMON_API void executeProcessAndGatherOutput (const Array< String > &command, String &output, int &processstatus, int timeoutsecs, int outputlimit, const String &input)
 
Process::Status feedProcessAndGatherOutput (ProcessRef const &proc, String &output, Timeout const &timeout=Timeout::infinite, int outputlimit=-1, String const &input=String())
 Send input to a process, collect the output, and wait for it to exit.
 
Process::Status feedProcessAndGatherOutput (ProcessRef const &proc, String &output, String &erroutput, Timeout const &timeout=Timeout::infinite, int outputLimit=-1, String const &input=String())
 Send input to a process, collect STDOUT and STDERR, and wait for it to exit.
 
void gatherOutput (String &output, const ProcessRef &proc, int timeoutSecs, int outputLimit)
 
void gatherOutput (String &output, const ProcessRef &proc, const Timeout &timeout=Timeout::infinite, int outputlimit=-1)
 Wait for output from a child process.
 
void processInputOutput (OutputCallback &output, Array< ProcessRef > &procs, InputCallback &input, const Timeout &timeout=Timeout::infinite)
 Send input and wait for output from child processes.
 
void processInputOutput (const String &input, String &output, const ProcessRef &process, const Timeout &timeout, int outputLimit)
 
template<typename SA1 , typename SA2 >
Process::Status system (const SA1 &command, const SA2 &envVars, const Timeout &timeout=Timeout::infinite)
 
template<typename S , typename SA1 , typename SA2 >
ProcessRef spawn (S const &exec_path, SA1 const &argv, SA2 const &envp, PreExec &pre_exec)
 Variant of spawn that allows exec_path to have an arbitrary string-like type, and argv and envp to have arbitrary string-array-like types.
 
template<typename SA1 , typename SA2 >
ProcessRef spawn (SA1 const &argv, SA2 const &envp)
 Variant of spawn that uses StandardPreExec and argv and envp to have arbitrary string-array-like types.
 
template<typename SA1 >
ProcessRef spawn (SA1 const &argv)
 
template<typename SA1 , typename S1 , typename S2 >
Process::Status executeProcessAndGatherOutput (SA1 const &command, S1 &output, const Timeout &timeout, int outputlimit, S2 const &input)
 Version of executeProcessAndGatherOutput() that passes the current process's environment to the child process.
 
template<typename SA1 , typename S1 , typename S2 >
Process::Status executeProcessAndGatherOutput (SA1 const &command, S1 &output, S1 &erroutput, const Timeout &timeout, int outputlimit, S2 const &input)
 Version of executeProcessAndGatherOutput() that passes the current process's environment to the child process and separates STDOUT and STDERR.
 
template<typename SA1 , typename S1 >
Process::Status executeProcessAndGatherOutput (SA1 const &command, S1 &output, const Timeout &timeout=Timeout::infinite, int outputlimit=-1)
 Version of executeProcessAndGatherOutput() that passes the current process's environment to the child process.
 
template<typename SA1 , typename S1 >
Process::Status executeProcessAndGatherOutput (SA1 const &command, S1 &output, S1 &erroutput, const Timeout &timeout=Timeout::infinite, int outputlimit=-1)
 Version of executeProcessAndGatherOutput() that passes the current process's environment to the child process and collects STDOUT and STDERR separately.
 
template<typename SA1 , typename S1 , typename SA2 , typename S2 >
Process::Status executeProcessAndGatherOutput (SA1 const &command, S1 &output, SA2 const &envp, const Timeout &timeout, int outputlimit, S2 const &input)
 Variant of executeProcessAndGatherOutput that allows command and envp to have arbitrary string-array-like types and output to have an arbitrary string-like type.
 
template<typename SA1 , typename S1 , typename SA2 , typename S2 >
Process::Status executeProcessAndGatherOutput (SA1 const &command, S1 &output, S1 &erroutput, SA2 const &envp, const Timeout &timeout, int outputlimit, S2 const &input)
 Variant of executeProcessAndGatherOutput that allows command and envp to have arbitrary string-array-like types and output to have an arbitrary string-like type.
 
template<typename SA1 , typename S1 , typename SA2 >
Process::Status executeProcessAndGatherOutput (SA1 const &command, S1 &output, S1 &erroutput, SA2 const &envp, const Timeout &timeout=Timeout::infinite, int outputlimit=-1)
 Version of executeProcessAndGatherOutput() that passes no input to the process.
 
template<typename S , typename SA1 , typename SA2 >
ProcessRef spawnImpl (S const &exec_path, SA1 const &argv, SA2 const &envp, PreExec &pre_exec)
 Variant of spawnImpl that allows exec_path to have an arbitrary string-like type, and argv and envp to have arbitrary string-array-like types.
 
ProcessRef spawnImpl (char const *const argv[], char const *const envp[])
 Variant of spawnImpl that uses StandardPreExec.
 
template<typename SA1 , typename SA2 >
ProcessRef spawnImpl (SA1 const &argv, SA2 const &envp)
 Variant of spawnImpl that uses StandardPreExec and argv and envp to have arbitrary string-array-like types.
 
template<typename SA1 >
ProcessRef spawnImpl (SA1 const &argv)
 

Variables

::BLOCXX_NAMESPACE::GlobalPtr< ExecMockObject, Impl::NullFactoryg_execMockObject = { 0, {0, PTHREAD_MUTEX_INITIALIZER} }
 
static char const *const *const currentEnvironment = 0
 Intended to be used as a parameter to spawn() to indicate that the current environment will be used for the child process.
 

Enumeration Type Documentation

◆ EOutputSource

Enumerator
E_STDOUT 
E_STDERR 

Definition at line 318 of file Exec.hpp.

Function Documentation

◆ executeProcessAndGatherOutput() [1/10]

BLOCXX_COMMON_API Process::Status BLOCXX_NAMESPACE::Exec::executeProcessAndGatherOutput ( char const *const command[],
String & output,
char const *const envVars[],
const Timeout & timeout = Timeout::infinite,
int outputlimit = -1,
char const * input = 0 )

Execute a command and run feedProcessAndGatherOutput() on the 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. Exercise caution when doing this, as you may be creating a security hole.

Parameters
commandcommand[0] is the binary to be executed. command[1] .. command[n] are the command line parameters to the command.
output
See also
feedProcessAndGatherOutput().
Parameters
envVarsAn EnvVars object that contains the environment variables to 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.
timeout
See also
feedProcessAndGatherOutput().
Parameters
outputlimit
See also
feedProcessAndGatherOutput().
Parameters
input
See also
feedProcessAndGatherOutput().
Exceptions
ExecErrorExceptionon error.
ExecTimeoutExceptionif the process hasn't finished within timeoutsecs.
ExecBufferFullExceptionif the process output exceeds outputlimit bytes.

Definition at line 257 of file Exec.cpp.

References feedProcessAndGatherOutput(), g_execMockObject, and spawn().

Referenced by executeProcessAndGatherOutput(), executeProcessAndGatherOutput(), executeProcessAndGatherOutput(), executeProcessAndGatherOutput(), executeProcessAndGatherOutput(), executeProcessAndGatherOutput(), executeProcessAndGatherOutput(), and executeProcessAndGatherOutput().

◆ executeProcessAndGatherOutput() [2/10]

BLOCXX_COMMON_API Process::Status BLOCXX_NAMESPACE::Exec::executeProcessAndGatherOutput ( char const *const command[],
String & output,
String & erroutput,
char const *const envVars[],
const Timeout & timeout = Timeout::infinite,
int outputLimit = -1,
char const * input = 0 )

Execute a command and run feedProcessAndGatherOutput() on the 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. Exercise caution when doing this, as you may be creating a security hole.

Parameters
commandcommand[0] is the binary to be executed. command[1] .. command[n] are the command line parameters to the command.
output
See also
feedProcessAndGatherOutput().
Parameters
erroutput
See also
feedProcessAndGatherOutput().
Parameters
envVarsAn EnvVars object that contains the environment variables to 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.
timeout
See also
feedProcessAndGatherOutput().
Parameters
outputlimit
See also
feedProcessAndGatherOutput().
Parameters
input
See also
feedProcessAndGatherOutput().
Exceptions
ExecErrorExceptionon error.
ExecTimeoutExceptionif the process hasn't finished within timeoutsecs.
ExecBufferFullExceptionif the process output exceeds outputlimit bytes.

Definition at line 274 of file Exec.cpp.

References feedProcessAndGatherOutput(), g_execMockObject, and spawn().

◆ executeProcessAndGatherOutput() [3/10]

BLOCXX_COMMON_API void BLOCXX_NAMESPACE::Exec::executeProcessAndGatherOutput ( const Array< String > & command,
String & output,
int & processstatus,
int timeoutsecs,
int outputlimit,
const String & input )

◆ executeProcessAndGatherOutput() [4/10]

template<typename SA1 , typename S1 , typename S2 >
Process::Status BLOCXX_NAMESPACE::Exec::executeProcessAndGatherOutput ( SA1 const & command,
S1 & output,
const Timeout & timeout,
int outputlimit,
S2 const & input )

Version of executeProcessAndGatherOutput() that passes the current process's environment to the child process.

Definition at line 576 of file Exec.hpp.

References BLOCXX_NAMESPACE::String::c_str(), currentEnvironment, executeProcessAndGatherOutput(), BLOCXX_NAMESPACE::Cstr::CstrArr< SA >::sarr, and BLOCXX_NAMESPACE::Cstr::to_char_ptr().

◆ executeProcessAndGatherOutput() [5/10]

template<typename SA1 , typename S1 >
Process::Status BLOCXX_NAMESPACE::Exec::executeProcessAndGatherOutput ( SA1 const & command,
S1 & output,
const Timeout & timeout = Timeout::infinite,
int outputlimit = -1 )

Version of executeProcessAndGatherOutput() that passes the current process's environment to the child process.

Definition at line 633 of file Exec.hpp.

References BLOCXX_NAMESPACE::String::c_str(), currentEnvironment, executeProcessAndGatherOutput(), and BLOCXX_NAMESPACE::Cstr::CstrArr< SA >::sarr.

◆ executeProcessAndGatherOutput() [6/10]

template<typename SA1 , typename S1 , typename S2 >
Process::Status BLOCXX_NAMESPACE::Exec::executeProcessAndGatherOutput ( SA1 const & command,
S1 & output,
S1 & erroutput,
const Timeout & timeout,
int outputlimit,
S2 const & input )

Version of executeProcessAndGatherOutput() that passes the current process's environment to the child process and separates STDOUT and STDERR.

Definition at line 604 of file Exec.hpp.

References BLOCXX_NAMESPACE::String::c_str(), currentEnvironment, executeProcessAndGatherOutput(), BLOCXX_NAMESPACE::Cstr::CstrArr< SA >::sarr, and BLOCXX_NAMESPACE::Cstr::to_char_ptr().

◆ executeProcessAndGatherOutput() [7/10]

template<typename SA1 , typename S1 >
Process::Status BLOCXX_NAMESPACE::Exec::executeProcessAndGatherOutput ( SA1 const & command,
S1 & output,
S1 & erroutput,
const Timeout & timeout = Timeout::infinite,
int outputlimit = -1 )

Version of executeProcessAndGatherOutput() that passes the current process's environment to the child process and collects STDOUT and STDERR separately.

Definition at line 660 of file Exec.hpp.

References BLOCXX_NAMESPACE::String::c_str(), currentEnvironment, executeProcessAndGatherOutput(), and BLOCXX_NAMESPACE::Cstr::CstrArr< SA >::sarr.

◆ executeProcessAndGatherOutput() [8/10]

template<typename SA1 , typename S1 , typename SA2 , typename S2 >
Process::Status BLOCXX_NAMESPACE::Exec::executeProcessAndGatherOutput ( SA1 const & command,
S1 & output,
S1 & erroutput,
SA2 const & envp,
const Timeout & timeout,
int outputlimit,
S2 const & input )

Variant of executeProcessAndGatherOutput that allows command and envp to have arbitrary string-array-like types and output to have an arbitrary string-like type.

It also collects STDOUT and STDERR separately. If command or envp are of type StringArray a terminating null is not necessary.

Precondition
S1 supports assignment from a const char*.
S2 is a type for which Cstr::to_char_ptr is defined.
Specializations of the Cstr::CstrArr class template are defined for both types SA1 and SA2.

Definition at line 736 of file Exec.hpp.

References BLOCXX_NAMESPACE::String::c_str(), executeProcessAndGatherOutput(), BLOCXX_NAMESPACE::Cstr::CstrArr< SA >::sarr, and BLOCXX_NAMESPACE::Cstr::to_char_ptr().

◆ executeProcessAndGatherOutput() [9/10]

template<typename SA1 , typename S1 , typename SA2 >
Process::Status BLOCXX_NAMESPACE::Exec::executeProcessAndGatherOutput ( SA1 const & command,
S1 & output,
S1 & erroutput,
SA2 const & envp,
const Timeout & timeout = Timeout::infinite,
int outputlimit = -1 )

Version of executeProcessAndGatherOutput() that passes no input to the process.

STDOUT and STDERR are collected separately.

Definition at line 766 of file Exec.hpp.

References executeProcessAndGatherOutput().

◆ executeProcessAndGatherOutput() [10/10]

template<typename SA1 , typename S1 , typename SA2 , typename S2 >
Process::Status BLOCXX_NAMESPACE::Exec::executeProcessAndGatherOutput ( SA1 const & command,
S1 & output,
SA2 const & envp,
const Timeout & timeout,
int outputlimit,
S2 const & input )

Variant of executeProcessAndGatherOutput that allows command and envp to have arbitrary string-array-like types and output to have an arbitrary string-like type.

If command or envp are of type StringArray a terminating null is not necessary.

Precondition
S1 supports assignment from a const char*.
S2 is a type for which Cstr::to_char_ptr is defined.
Specializations of the Cstr::CstrArr class template are defined for both types SA1 and SA2.

Definition at line 698 of file Exec.hpp.

References BLOCXX_NAMESPACE::String::c_str(), executeProcessAndGatherOutput(), BLOCXX_NAMESPACE::Cstr::CstrArr< SA >::sarr, and BLOCXX_NAMESPACE::Cstr::to_char_ptr().

◆ feedProcessAndGatherOutput() [1/2]

BLOCXX_COMMON_API Process::Status BLOCXX_NAMESPACE::Exec::feedProcessAndGatherOutput ( ProcessRef const & proc,
String & output,
String & erroutput,
Timeout const & timeout = Timeout::infinite,
int outputLimit = -1,
String const & input = String() )

Send input to a process, collect STDOUT and STDERR, 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 on STDOUT or STDERR, an ExecBufferFullException is thrown.

If the process does not terminate by itself, or if an exception is thrown because a limit has been reached (time or output), then Process::waitCloseTerm() is called with default arguments to force termination.

Parameters
procThe object managing the process.
outputProcess STDOUT is appended to this string.
erroututProcess STDERR is appended to this string.
timeoutThe interval to wait for the process to exit. If the process hasn't exited after the timeout, an ExecTimeoutException will be thrown, and the process will be killed. Output from a process can reset a relative with reset timeout.
outputlimitThe 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.
inputData to write to the child's stdin. After the data has been written, stdin is closed.
Exceptions
ExecErrorExceptionon error.
ExecTimeoutExceptionif the process hasn't finished within timeoutsecs.
ExecBufferFullExceptionif the process output exceeds outputlimit bytes.

Definition at line 331 of file Exec.cpp.

References processInputOutput().

◆ feedProcessAndGatherOutput() [2/2]

BLOCXX_COMMON_API Process::Status BLOCXX_NAMESPACE::Exec::feedProcessAndGatherOutput ( ProcessRef const & proc,
String & output,
Timeout const & timeout = Timeout::infinite,
int outputlimit = -1,
String const & input = String() )

Send input to 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.

If the process does not terminate by itself, or if an exception is thrown because a limit has been reached (time or output), then Process::waitCloseTerm() is called with default arguments to force termination.

Parameters
procThe object managing the process.
outputProcess output is appended to this string.
timeoutThe interval to wait for the process to exit. If the process hasn't exited after the timeout, an ExecTimeoutException will be thrown, and the process will be killed. Output from a process can reset a relative with reset timeout.
outputlimitThe 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.
inputData to write to the child's stdin. After the data has been written, stdin is closed.
Exceptions
ExecErrorExceptionon error.
ExecTimeoutExceptionif the process hasn't finished within timeoutsecs.
ExecBufferFullExceptionif the process output exceeds outputlimit bytes.

Definition at line 314 of file Exec.cpp.

References processInputOutput().

Referenced by executeProcessAndGatherOutput(), and executeProcessAndGatherOutput().

◆ gatherOutput() [1/2]

BLOCXX_COMMON_API void BLOCXX_NAMESPACE::Exec::gatherOutput ( String & output,
const ProcessRef & proc,
const Timeout & timeout = Timeout::infinite,
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
outputAn out parameter, the process output will be appended to this string.
procThe connection to the child process.
timeoutSpecifies the interval to wait for the process to exit. If the process hasn't exited after the timeout, an ExecTimeoutException will be thrown.
Output from a process can reset a relative with reset timeout.
outputlimitSpecifies 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
ProcessErroron error.
ProcessTimeoutif the process hasn't finished within timeoutsecs.
ProcessBufferFullif the process output exceeds outputlimit bytes.

Definition at line 356 of file Exec.cpp.

References processInputOutput().

◆ gatherOutput() [2/2]

void BLOCXX_NAMESPACE::Exec::gatherOutput ( String & output,
const ProcessRef & proc,
int timeoutSecs,
int outputLimit )

Definition at line 350 of file Exec.cpp.

References gatherOutput(), and BLOCXX_NAMESPACE::Timeout::relativeWithReset().

Referenced by gatherOutput().

◆ processInputOutput() [1/2]

BLOCXX_COMMON_API void BLOCXX_NAMESPACE::Exec::processInputOutput ( const String & input,
String & output,
const ProcessRef & process,
const Timeout & timeout,
int outputLimit )

Definition at line 608 of file Exec.cpp.

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

◆ processInputOutput() [2/2]

BLOCXX_COMMON_API void BLOCXX_NAMESPACE::Exec::processInputOutput ( OutputCallback & output,
Array< ProcessRef > & procs,
InputCallback & input,
const Timeout & timeout = Timeout::infinite )

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
outputA callback, whenever data is received from a process, it will be passed to output.handleData().
procsThe connections to the child processes.
timeoutSpecifies the interval to wait for all the processes to exit. If the timeout expires, an ExecTimeoutException will be thrown. Output from a process can reset a relative with reset timeout.
inputCallback 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
ExecErrorExceptionon error.
ExecTimeoutExceptionif the process hasn't finished within timeoutSecs.

Definition at line 412 of file Exec.cpp.

References BLOCXX_NAMESPACE::TimeoutTimer::asRelativeTimeout(), availableDataLen, BLOCXX_THROW, BLOCXX_THROW_ERRNO_MSG, E_STDERR, E_STDOUT, BLOCXX_NAMESPACE::Array< T >::erase(), errIsOpen, BLOCXX_NAMESPACE::TimeoutTimer::expired(), BLOCXX_NAMESPACE::Exec::InputCallback::getData(), BLOCXX_NAMESPACE::Exec::OutputCallback::handleData(), i, inIsOpen, BLOCXX_NAMESPACE::TimeoutTimer::loop(), outIsOpen, BLOCXX_NAMESPACE::Array< T >::push_back(), BLOCXX_NAMESPACE::IOIFC::read(), BLOCXX_NAMESPACE::TimeoutTimer::resetOnLoop(), BLOCXX_NAMESPACE::Select::SELECT_ERROR, BLOCXX_NAMESPACE::Select::SELECT_TIMEOUT, BLOCXX_NAMESPACE::Select::selectRW(), BLOCXX_NAMESPACE::Array< T >::size(), BLOCXX_NAMESPACE::TimeoutTimer::start(), BLOCXX_NAMESPACE::Select::SelectObject::waitForRead, BLOCXX_NAMESPACE::Select::SelectObject::waitForWrite, and BLOCXX_NAMESPACE::IOIFC::write().

Referenced by feedProcessAndGatherOutput(), feedProcessAndGatherOutput(), gatherOutput(), and processInputOutput().

◆ safeSystem()

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

This is deprecated.

Use system() instead

Definition at line 112 of file Exec.cpp.

References BLOCXX_NAMESPACE::Process::Status::getPOSIXwaitpidStatus(), and system().

◆ spawn() [1/5]

BLOCXX_COMMON_API ProcessRef BLOCXX_NAMESPACE::Exec::spawn ( char const *const argv[],
char const *const envp[] )

Variant of spawn that uses StandardPreExec.

Definition at line 147 of file Exec.cpp.

References spawn().

◆ spawn() [2/5]

BLOCXX_COMMON_API ProcessRef BLOCXX_NAMESPACE::Exec::spawn ( char const * exec_path,
char const *const argv[],
char const *const envp[],
PreExec & pre_exec )

Run the executable exec_path in a child process, with argv for the program arguments and envp for the environment.

Precondition
The standard descriptors (0, 1, and 2) are all open.
Parameters
exec_pathAbsolute path of the executable to run in the child process.
argvNull-terminated argument list for the child process. If argv is null or the empty sequence (argv[0] is null), then it is replaced with a sequence containing only exec_path.
envpThe null-terminated environment for the child process. If null then the caller's environment is used. It is recommended that envp be constructed by starting with Secure::minimal_environment() and adding only those additional environment variables known to be needed.
pre_execSpecifies what action to take in the child process between fork and exec.

Definition at line 133 of file Exec.cpp.

References BLOCXX_NAMESPACE::WaitpidThreadFix::shouldUseWaitpidThreadFix(), spawnImpl(), and BLOCXX_NAMESPACE::WaitpidThreadFix::spawnProcess().

Referenced by executeProcessAndGatherOutput(), executeProcessAndGatherOutput(), spawn(), spawn(), spawn(), spawn(), and system().

◆ spawn() [3/5]

template<typename S , typename SA1 , typename SA2 >
ProcessRef BLOCXX_NAMESPACE::Exec::spawn ( S const & exec_path,
SA1 const & argv,
SA2 const & envp,
PreExec & pre_exec )

Variant of spawn that allows exec_path to have an arbitrary string-like type, and argv and envp to have arbitrary string-array-like types.

If argv or envp are of type StringArray a terminating null is not necessary.

Precondition
S is a type for which Cstr::to_char_ptr is defined.
Specializations of the Cstr::CstrArr class template are defined for both types SA1 and SA2.

Definition at line 247 of file Exec.hpp.

References BLOCXX_NAMESPACE::Cstr::CstrArr< SA >::sarr, spawn(), and BLOCXX_NAMESPACE::Cstr::to_char_ptr().

◆ spawn() [4/5]

template<typename SA1 >
ProcessRef BLOCXX_NAMESPACE::Exec::spawn ( SA1 const & argv)

Definition at line 282 of file Exec.hpp.

References currentEnvironment, and spawn().

◆ spawn() [5/5]

template<typename SA1 , typename SA2 >
ProcessRef BLOCXX_NAMESPACE::Exec::spawn ( SA1 const & argv,
SA2 const & envp )

Variant of spawn that uses StandardPreExec and argv and envp to have arbitrary string-array-like types.

Precondition
Specializations of the Cstr::CstrArr class template are defined for both types SA1 and SA2.

Definition at line 272 of file Exec.hpp.

References BLOCXX_NAMESPACE::Cstr::CstrArr< SA >::sarr, and spawn().

◆ spawnImpl() [1/5]

ProcessRef BLOCXX_NAMESPACE::Exec::spawnImpl ( char const *const argv[],
char const *const envp[] )

Variant of spawnImpl that uses StandardPreExec.

◆ spawnImpl() [2/5]

ProcessRef BLOCXX_NAMESPACE::Exec::spawnImpl ( char const * exec_path,
char const *const argv[],
char const *const envp[],
PreExec & pre_exec )

◆ spawnImpl() [3/5]

template<typename S , typename SA1 , typename SA2 >
ProcessRef BLOCXX_NAMESPACE::Exec::spawnImpl ( S const & exec_path,
SA1 const & argv,
SA2 const & envp,
PreExec & pre_exec )

Variant of spawnImpl that allows exec_path to have an arbitrary string-like type, and argv and envp to have arbitrary string-array-like types.

If argv or envp are of type StringArray a terminating null is not necessary.

Precondition
S is a type for which Cstr::to_char_ptr is defined.
Specializations of the Cstr::CstrArr class template are defined for both types SA1 and SA2.

Definition at line 70 of file WaitpidThreadFixFwd.hpp.

References BLOCXX_NAMESPACE::Cstr::CstrArr< SA >::sarr, spawnImpl(), and BLOCXX_NAMESPACE::Cstr::to_char_ptr().

◆ spawnImpl() [4/5]

template<typename SA1 >
ProcessRef BLOCXX_NAMESPACE::Exec::spawnImpl ( SA1 const & argv)

Definition at line 105 of file WaitpidThreadFixFwd.hpp.

References currentEnvironment, and spawnImpl().

◆ spawnImpl() [5/5]

template<typename SA1 , typename SA2 >
ProcessRef BLOCXX_NAMESPACE::Exec::spawnImpl ( SA1 const & argv,
SA2 const & envp )

Variant of spawnImpl that uses StandardPreExec and argv and envp to have arbitrary string-array-like types.

Precondition
Specializations of the Cstr::CstrArr class template are defined for both types SA1 and SA2.

Definition at line 95 of file WaitpidThreadFixFwd.hpp.

References BLOCXX_NAMESPACE::Cstr::CstrArr< SA >::sarr, and spawnImpl().

◆ system() [1/2]

BLOCXX_COMMON_API Process::Status BLOCXX_NAMESPACE::Exec::system ( const Array< String > & command,
const char *const envp[] = 0,
const Timeout & = Timeout::infinite )

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. Use a timeout or be careful that the command you run doesn't hang.

Parameters
commandcommand[0] is the binary to be executed. command[1] .. command[n] are the command line parameters to the command.
envpan 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.
timeoutHow long to wait for the process to exit.
Returns
The process's status
Exceptions
ExecErrorExceptionon error

Definition at line 94 of file Exec.cpp.

References BLOCXX_NAMESPACE::Timeout::relative(), and spawn().

Referenced by BLOCXX_NAMESPACE::StackTrace::getStackTrace(), safeSystem(), and system().

◆ system() [2/2]

template<typename SA1 , typename SA2 >
Process::Status BLOCXX_NAMESPACE::Exec::system ( const SA1 & command,
const SA2 & envVars,
const Timeout & timeout = Timeout::infinite )

Definition at line 88 of file Exec.hpp.

References BLOCXX_NAMESPACE::Cstr::CstrArr< SA >::sarr, and system().

Variable Documentation

◆ currentEnvironment

char const* const* const BLOCXX_NAMESPACE::Exec::currentEnvironment = 0
static

Intended to be used as a parameter to spawn() to indicate that the current environment will be used for the child process.

Definition at line 205 of file Exec.hpp.

Referenced by executeProcessAndGatherOutput(), executeProcessAndGatherOutput(), executeProcessAndGatherOutput(), executeProcessAndGatherOutput(), spawn(), and spawnImpl().

◆ g_execMockObject

::BLOCXX_NAMESPACE::GlobalPtr<ExecMockObject, Impl::NullFactory> BLOCXX_NAMESPACE::Exec::g_execMockObject = { 0, {0, PTHREAD_MUTEX_INITIALIZER} }

Definition at line 90 of file Exec.cpp.

Referenced by executeProcessAndGatherOutput(), and executeProcessAndGatherOutput().