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 38 of file subprocess.h.

Member Enumeration Documentation

enum sbia::basis::Subprocess::RedirectMode

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 73 of file subprocess.h.

Member Function Documentation

int sbia::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 769 of file subprocess.cxx.

int sbia::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 777 of file subprocess.cxx.

bool sbia::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 632 of file subprocess.cxx.

bool sbia::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 703 of file subprocess.cxx.

bool sbia::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 717 of file subprocess.cxx.

bool sbia::basis::Subprocess::kill ( )

Kill subprocess.

On POSIX, the SIGKILL signal is send.
On Windows, TerminateProcess() is invoked to terminate the subprocess.

Definition at line 568 of file subprocess.cxx.

int sbia::basis::Subprocess::pid ( ) const

Returns:: ID of subprocess.

Definition at line 608 of file subprocess.cxx.

bool sbia::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 474 of file subprocess.cxx.

bool sbia::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 220 of file subprocess.cxx.

bool sbia::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 170 of file subprocess.h.

int sbia::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 749 of file subprocess.cxx.

int sbia::basis::Subprocess::returncode ( ) const

Returns:: Exit code of subprocess. Only valid if terminated() is true.

Definition at line 618 of file subprocess.cxx.

bool sbia::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 532 of file subprocess.cxx.

bool sbia::basis::Subprocess::signaled ( ) const

Returns:: Wether the subprocess has been signaled, i.e., terminated abnormally.

Definition at line 578 of file subprocess.cxx.

Subprocess::CommandLine sbia::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 75 of file subprocess.cxx.

bool sbia::basis::Subprocess::terminate ( )

Terminate subprocess.

On POSIX, the SIGTERM signal is send.
On Windows, TerminateProcess() is invoked to terminate the subprocess.

Definition at line 544 of file subprocess.cxx.

string sbia::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 145 of file subprocess.cxx.

bool sbia::basis::Subprocess::wait ( )

Wait for subprocess to terminate.

This method also sets the exit code as returned by GetExitCode().

Definition at line 507 of file subprocess.cxx.

int sbia::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 736 of file subprocess.cxx.

The documentation for this class was generated from the following files:

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

Member Function Documentation