Platform-independent interface to create and control a subprocess. More...
#include <subprocess.h>
Classes | |
struct | Information |
Information structure required by system to identify subprocess. | |
Public Types | |
typedef std::vector< std::string > | CommandLine |
typedef std::vector< std::string > | Environment |
enum | RedirectMode { RM_NONE, RM_PIPE, RM_STDOUT } |
Modes of redirection for standard input/output buffers. More... | |
Public Member Functions | |
bool | communicate (std::istream &in, std::ostream &out, std::ostream &err) |
Communicate with subprocess. | |
bool | communicate (std::ostream &out, std::ostream &err) |
Communicate with subprocess. | |
bool | communicate (std::ostream &out) |
Communicate with subprocess. | |
bool | kill () |
Kill subprocess. | |
int | pid () const |
bool | poll () const |
Check if subprocess terminated and update return code. | |
bool | popen (const CommandLine &args, const RedirectMode rm_in=RM_NONE, const RedirectMode rm_out=RM_NONE, const RedirectMode rm_err=RM_NONE, const Environment *env=NULL) |
Open new subprocess. | |
bool | popen (const std::string &cmd, const RedirectMode rm_in=RM_NONE, const RedirectMode rm_out=RM_NONE, const RedirectMode rm_err=RM_NONE, const Environment *env=NULL) |
Open new subprocess. | |
int | read (void *buf, size_t nbuf, bool err=false) |
Read data from stdout or stderr of subprocess. | |
int | returncode () const |
bool | send_signal (int signal) |
Send signal to subprocess. | |
bool | signaled () const |
Subprocess () | |
Default constructor. | |
bool | terminate () |
Terminate subprocess. | |
bool | wait () |
Wait for subprocess to terminate. | |
int | write (const void *buf, size_t nbuf) |
Write data to stdin of subprocess. | |
~Subprocess () | |
Terminate running subprocess and close all related handles. | |
Static Public Member Functions | |
static int | call (const CommandLine &cmd) |
Execute command as subprocess. | |
static int | call (const std::string &cmd) |
Execute command as subprocess. | |
static CommandLine | split (const std::string &cmd) |
Split double quoted string into arguments. | |
static std::string | tostring (const CommandLine &args) |
Convert argument vector to double quoted string. |
Detailed Description
Platform-independent interface to create and control a subprocess.
Definition at line 36 of file subprocess.h.
Member Typedef Documentation
typedef std::vector<std::string> basis::Subprocess::CommandLine |
Definition at line 42 of file subprocess.h.
typedef std::vector<std::string> basis::Subprocess::Environment |
Definition at line 43 of file subprocess.h.
Member Enumeration Documentation
Modes of redirection for standard input/output buffers.
- Enumerator:
RM_NONE Do not redirect the input/output.
RM_PIPE Use a pipe to redirect the input/output from/to the parent.
RM_STDOUT Redirect stderr to stdout.
Definition at line 71 of file subprocess.h.
Constructor & Destructor Documentation
basis::Subprocess::Subprocess | ( | ) |
Default constructor.
Definition at line 177 of file subprocess.cxx.
basis::Subprocess::~Subprocess | ( | ) |
Terminate running subprocess and close all related handles.
Definition at line 194 of file subprocess.cxx.
Member Function Documentation
int basis::Subprocess::call | ( | const CommandLine & | cmd | ) | [static] |
Execute command as subprocess.
This function is implemented in the same manner as system() on Unix. It simply creates a Subprocess instance, executes the subprocess and waits for its termination.
Example:
Subprocess::CommandLine cmd; cmd.push_back("ls"); cmd.push_back("some directory"); int status = Subprocess::call(cmd);
- Returns:
- Exit code of subprocess or -1 on error.
Definition at line 767 of file subprocess.cxx.
int basis::Subprocess::call | ( | const std::string & | cmd | ) | [static] |
Execute command as subprocess.
This function is implemented in the same manner as system() on Unix. It simply creates a Subprocess instance, executes the subprocess and waits for its termination.
Example:
int status = Subprocess::call("ls \"some directory\"");
- Parameters:
-
[in] cmd Command-line given as single string. Quote arguments containing whitespace characters using ".
- Returns:
- Exit code of subprocess or -1 on error.
Definition at line 775 of file subprocess.cxx.
bool basis::Subprocess::communicate | ( | std::istream & | in, |
std::ostream & | out, | ||
std::ostream & | err | ||
) |
Communicate with subprocess.
- Note:
- This method closes the pipes to the subprocess after all data has been sent and received and returns after the subprocess terminated. Therefore, the exit code is set upon return.
- Parameters:
-
[in] in Data send to subprocess via pipe to stdin. If no pipe was setup during subprocess creation, this function does nothing and returns false. [in] out Data read from stdout of subprocess. Can be an empty string if no pipe was created for stdout. [in] err Data read from stderr of subprocess. Can be an empty string if no pipe was created for stderr.
- Returns:
- Whether the communication with the subprocess was successful.
Definition at line 630 of file subprocess.cxx.
bool basis::Subprocess::communicate | ( | std::ostream & | out, |
std::ostream & | err | ||
) |
Communicate with subprocess.
- Note:
- This method closes the pipes to the subprocess after all data has been received and returns after the subprocess terminated. Therefore, the exit code is set upon return.
- Parameters:
-
[in] out Data read from stdout of subprocess. Can be an empty string if no pipe was created for stdout. [in] err Data read from stderr of subprocess. Can be an empty string if no pipe was created for stderr.
- Returns:
- Whether the communication with the subprocess was successful.
Definition at line 701 of file subprocess.cxx.
bool basis::Subprocess::communicate | ( | std::ostream & | out | ) |
Communicate with subprocess.
- Note:
- This method closes the pipes to the subprocess after all data has been received and returns after the subprocess terminated. Therefore, the exit code is set upon return.
- Parameters:
-
[in] out Data read from stdout of subprocess. Can be an empty string if no pipe was created for stdout.
- Returns:
- Whether the communication with the subprocess was successful.
Definition at line 715 of file subprocess.cxx.
bool basis::Subprocess::kill | ( | ) |
Kill subprocess.
- On POSIX, the SIGKILL signal is send.
- On Windows, TerminateProcess() is invoked to terminate the subprocess.
Definition at line 566 of file subprocess.cxx.
int basis::Subprocess::pid | ( | ) | const |
- Returns:
- ID of subprocess.
Definition at line 606 of file subprocess.cxx.
bool basis::Subprocess::poll | ( | ) | const |
Check if subprocess terminated and update return code.
This method returns immediately and does not wait for the subprocess to actually being terminated. For that purpuse, use wait() instead.
- Returns:
- Whether the subprocess terminated.
Definition at line 472 of file subprocess.cxx.
bool basis::Subprocess::popen | ( | const CommandLine & | args, |
const RedirectMode | rm_in = RM_NONE , |
||
const RedirectMode | rm_out = RM_NONE , |
||
const RedirectMode | rm_err = RM_NONE , |
||
const Environment * | env = NULL |
||
) |
Open new subprocess.
This method creates the subprocess and returns immediately. In order to wait for the suprocess to finish, the wait() method has to be called explicitly.
- Parameters:
-
[in] args Command-line of subprocess. The first argument has to be the name/path of the command to be executed. [in] rm_in Mode used for redirection of stdin of subprocess. Can be either RM_NONE or RM_PIPE. [in] rm_out Mode used for redirection of stdout of subprocess. Can be either RM_NONE or RM_PIPE. [in] rm_err Mode used for redirection of stderr of subprocess. Can be either RM_NONE, RM_PIPE, or RM_STDOUT. [in] env Environment for the subprocess. If NULL is given, the environment of the parent process is used.
- Returns:
- Whether the subprocess was created successfully.
Definition at line 218 of file subprocess.cxx.
bool basis::Subprocess::popen | ( | const std::string & | cmd, |
const RedirectMode | rm_in = RM_NONE , |
||
const RedirectMode | rm_out = RM_NONE , |
||
const RedirectMode | rm_err = RM_NONE , |
||
const Environment * | env = NULL |
||
) | [inline] |
Open new subprocess.
This method creates the subprocess and returns immediately. In order to wait for the suprocess to finish, the wait() method has to be called explicitly.
- Parameters:
-
[in] cmd Command-line given as double quoted string. Arguments containing whitespaces have to be quoted using double quotes. Use a backslash (\) to escape double quotes inside an argument as well as to escape a backslash itself (required if backslash at end of double quoted argument, e.g., "this argument \\"). [in] rm_in Mode used for redirection of stdin of subprocess. Can be either RM_NONE or RM_PIPE. [in] rm_out Mode used for redirection of stdout of subprocess. Can be either RM_NONE or RM_PIPE. [in] rm_err Mode used for redirection of stderr of subprocess. Can be either RM_NONE, RM_PIPE, or RM_STDOUT. [in] env Environment for the subprocess. If NULL is given, the environment of the parent process is used.
Definition at line 168 of file subprocess.h.
int basis::Subprocess::read | ( | void * | buf, |
size_t | nbuf, | ||
bool | err = false |
||
) |
Read data from stdout or stderr of subprocess.
- Parameters:
-
[out] buf Allocated buffer to store read data to. [in] nbuf Number of bytes to read from subprocess. [in] err If true and the redirection mode of stderr is RM_PIPE, the data is read from stderr of the subprocess. Otherwise, the data is read from stdout.
- Returns:
- Number of bytes read or -1 on error.
Definition at line 747 of file subprocess.cxx.
int basis::Subprocess::returncode | ( | ) | const |
- Returns:
- Exit code of subprocess. Only valid if terminated() is true.
Definition at line 616 of file subprocess.cxx.
bool basis::Subprocess::send_signal | ( | int | signal | ) |
Send signal to subprocess.
On Windows, SIGTERM is an alias for terminate() and SIGKILL an alias for kill() which in turn is nothing else but a termination of the subprocess. All other signals are only sent to POSIX processes.
Definition at line 530 of file subprocess.cxx.
bool basis::Subprocess::signaled | ( | ) | const |
- Returns:
- Wether the subprocess has been signaled, i.e., terminated abnormally.
Definition at line 576 of file subprocess.cxx.
Subprocess::CommandLine basis::Subprocess::split | ( | const std::string & | cmd | ) | [static] |
Split double quoted string into arguments.
- Parameters:
-
[in] cmd Double quoted string. Use '\' to escape double quotes within arguments.
- Returns:
- Argument vector.
Definition at line 71 of file subprocess.cxx.
bool basis::Subprocess::terminate | ( | ) |
Terminate subprocess.
- On POSIX, the SIGTERM signal is send.
- On Windows, TerminateProcess() is invoked to terminate the subprocess.
Definition at line 542 of file subprocess.cxx.
string basis::Subprocess::tostring | ( | const CommandLine & | args | ) | [static] |
Convert argument vector to double quoted string.
- Parameters:
-
[in] args Argument vector.
- Returns:
- Double quoted string.
Definition at line 141 of file subprocess.cxx.
bool basis::Subprocess::wait | ( | ) |
Wait for subprocess to terminate.
This method also sets the exit code as returned by GetExitCode().
Definition at line 505 of file subprocess.cxx.
int basis::Subprocess::write | ( | const void * | buf, |
size_t | nbuf | ||
) |
Write data to stdin of subprocess.
- Parameters:
-
[in] buf Bytes to write. [in] nbuf Number of bytes from buf
to write.
- Returns:
- Number of bytes written or -1 on error.
Definition at line 734 of file subprocess.cxx.
The documentation for this class was generated from the following files: