Platform-independent interface to create and control a subprocess. More...

#include <subprocess.h>

Collaboration diagram for basis::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. More...

bool	communicate (std::ostream &out, std::ostream &err)
	Communicate with subprocess. More...

bool	communicate (std::ostream &out)
	Communicate with subprocess. More...

bool	kill ()
	Kill subprocess. More...

int	pid () const

bool	poll () const
	Check if subprocess terminated and update return code. More...

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. More...

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. More...

int	read (void *buf, size_t nbuf, bool err=false)
	Read data from stdout or stderr of subprocess. More...

int	returncode () const

bool	send_signal (int signal)
	Send signal to subprocess. More...

bool	signaled () const

	Subprocess ()
	Default constructor. More...

bool	terminate ()
	Terminate subprocess. More...

bool	wait ()
	Wait for subprocess to terminate. More...

int	write (const void *buf, size_t nbuf)
	Write data to stdin of subprocess. More...

	~Subprocess ()
	Terminate running subprocess and close all related handles. More...

Static Public Member Functions
static int	call (const CommandLine &cmd)
	Execute command as subprocess. More...

static int	call (const std::string &cmd)
	Execute command as subprocess. More...

static CommandLine	split (const std::string &cmd)
	Split double quoted string into arguments. More...

static std::string	tostring (const CommandLine &args)
	Convert argument vector to double quoted string. More...

Detailed Description

Platform-independent interface to create and control a subprocess.

Definition at line 40 of file subprocess.h.

Member Typedef Documentation

§ CommandLine

typedef std::vector<std::string> basis::Subprocess::CommandLine

Definition at line 46 of file subprocess.h.

§ Environment

typedef std::vector<std::string> basis::Subprocess::Environment

Definition at line 47 of file subprocess.h.

Member Enumeration Documentation

§ RedirectMode

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

Constructor & Destructor Documentation

§ Subprocess()

basis::Subprocess::Subprocess ( )

Default constructor.

Definition at line 177 of file subprocess.cxx.

§ ~Subprocess()

basis::Subprocess::~Subprocess ( )

Terminate running subprocess and close all related handles.

Definition at line 194 of file subprocess.cxx.

Member Function Documentation

§ call() [1/2]

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 771 of file subprocess.cxx.

§ call() [2/2]

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 779 of file subprocess.cxx.

§ communicate() [1/3]

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 634 of file subprocess.cxx.

§ communicate() [2/3]

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 705 of file subprocess.cxx.

§ communicate() [3/3]

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 719 of file subprocess.cxx.

§ kill()

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 565 of file subprocess.cxx.

§ pid()

int basis::Subprocess::pid ( ) const

Returns: ID of subprocess.

Definition at line 610 of file subprocess.cxx.

§ poll()

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 466 of file subprocess.cxx.

§ popen() [1/2]

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.

§ popen() [2/2]

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

§ read()

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 751 of file subprocess.cxx.

§ returncode()

int basis::Subprocess::returncode ( ) const

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

Definition at line 620 of file subprocess.cxx.

§ send_signal()

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 529 of file subprocess.cxx.

§ signaled()

bool basis::Subprocess::signaled ( ) const

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

Definition at line 575 of file subprocess.cxx.

§ split()

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.

§ terminate()

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 541 of file subprocess.cxx.

§ tostring()

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.

§ wait()

bool basis::Subprocess::wait ( )

Wait for subprocess to terminate.

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

Definition at line 504 of file subprocess.cxx.

§ write()

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 738 of file subprocess.cxx.

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

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

§ CommandLine

§ Environment

Member Enumeration Documentation

§ RedirectMode

Constructor & Destructor Documentation

§ Subprocess()

§ ~Subprocess()

Member Function Documentation

§ call() [1/2]

§ call() [2/2]

§ communicate() [1/3]

§ communicate() [2/3]

§ communicate() [3/3]

§ kill()

§ pid()

§ poll()

§ popen() [1/2]

§ popen() [2/2]

§ read()

§ returncode()

§ send_signal()

§ signaled()

§ split()

§ terminate()

§ tostring()

§ wait()

§ write()