stx::ExecPipe Class Reference

Main library interface (reference counted pointer). More...

#include <stx-execpipe.h>

Public Types
enum	DebugLevel { DL_ERROR = 0, DL_INFO = 1, DL_DEBUG = 2, DL_TRACE = 3 }
	Enumeration for ascending debug levels. More...
Public Member Functions
	ExecPipe ()
	Construct a new uninitialize execution pipe.
	~ExecPipe ()
	Release reference to execution pipe.
	ExecPipe (const ExecPipe &ep)
	Copy-constructor creates a new reference to the _same_ pipe.
ExecPipe &	operator= (const ExecPipe &ep)
	Assignment operator creates a new reference to the right pipe.
void	set_debug_level (enum DebugLevel dl)
	Change the current debug level. The default is DL_ERROR.
void	set_debug_output (void(output)(const char line))
	Change output function for debug messages.
ExecPipe &	run ()
	Run the configured pipe sequence and wait for all children processes to complete.
Input Selectors

void	set_input_fd (int fd)
	Assign an already opened file descriptor as input stream for the first exec stage.
void	set_input_file (const char *path)
	Assign a file as input stream source.
void	set_input_string (const std::string *input)
	Assign a std::string as input stream source.
void	set_input_source (PipeSource *source)
	Assign a PipeSource as input stream source.
Output Selectors

void	set_output_fd (int fd)
	Assign an already opened file descriptor as output stream for the last exec stage.
void	set_output_file (const char *path, int mode=0666)
	Assign a file as output stream destination.
void	set_output_string (std::string *output)
	Assign a std::string as output stream destination.
void	set_output_sink (PipeSink *sink)
	Assign a PipeSink as output stream destination.
Add Pipe Stages

unsigned int	size () const
	Return the number of pipe stages added.
void	add_exec (const char *prog)
	Add an exec() stage to the pipe with given arguments.
void	add_exec (const char prog, const char arg1)
	Add an exec() stage to the pipe with given arguments.
void	add_exec (const char prog, const char arg1, const char *arg2)
	Add an exec() stage to the pipe with given arguments.
void	add_exec (const char prog, const char arg1, const char arg2, const char arg3)
	Add an exec() stage to the pipe with given arguments.
void	add_exec (const std::vector< std::string > *args)
	Add an exec() stage to the pipe with given arguments.
void	add_execp (const char *prog)
	Add an execp() stage to the pipe with given arguments.
void	add_execp (const char prog, const char arg1)
	Add an execp() stage to the pipe with given arguments.
void	add_execp (const char prog, const char arg1, const char *arg2)
	Add an execp() stage to the pipe with given arguments.
void	add_execp (const char prog, const char arg1, const char arg2, const char arg3)
	Add an execp() stage to the pipe with given arguments.
void	add_execp (const std::vector< std::string > *args)
	Add an execp() stage to the pipe with given arguments.
void	add_exece (const char path, const std::vector< std::string > args, const std::vector< std::string > *env)
	Add an exece() stage to the pipe with the given arguments and environments.
void	add_function (PipeFunction *func)
	Add a function stage to the pipe.
Inspect Return Codes

int	get_return_status (unsigned int stageid) const
	Get the return status of exec() stage's program run after pipe execution as indicated by wait().
int	get_return_code (unsigned int stageid) const
	Get the return code of exec() stage's program run after pipe execution, or -1 if the program terminated abnormally.
int	get_return_signal (unsigned int stageid) const
	Get the signal of the abnormally terminated exec() stage's program run after pipe execution, or -1 if the program terminated normally.
bool	all_return_codes_zero () const
	Return true if the return code of all exec() stages were zero.
Protected Attributes
class ExecPipeImpl *	m_impl
	reference-counted pointer implementation

Detailed Description

Main library interface (reference counted pointer).

The ExecPipe class is the main interface to the library. It is a reference counted pointer implementation, so you can easily copy and pass around without duplicating the inside object. See the main page for detailed information and examples.

Examples:: functions1.cc, simple1.cc, simple2.cc, and simple3.cc.

Definition at line 128 of file stx-execpipe.h.

Member Enumeration Documentation

enum stx::ExecPipe::DebugLevel

Enumeration for ascending debug levels.

Enumerator:

DL_ERROR	error reporting is always active. shows failed syscalls.
DL_INFO	info reports at important points during pipe run.
DL_DEBUG	debug shows information about select() calls.
DL_TRACE	trace lists lots of info about read() and write() calls.

Definition at line 150 of file stx-execpipe.h.

Constructor & Destructor Documentation

stx::ExecPipe::ExecPipe ( )

Construct a new uninitialize execution pipe.

Definition at line 1492 of file stx-execpipe.cc.

stx::ExecPipe::~ExecPipe ( )

Release reference to execution pipe.

Definition at line 1498 of file stx-execpipe.cc.

stx::ExecPipe::ExecPipe ( const ExecPipe & ep )

Copy-constructor creates a new reference to the _same_ pipe.

Definition at line 1504 of file stx-execpipe.cc.

Member Function Documentation

void stx::ExecPipe::add_exec ( const std::vector< std::string > * args )

Add an exec() stage to the pipe with given arguments.

The vector of arguments is not copied, so it must still exist when run() is called. Note that the program called is args[0].

Definition at line 1598 of file stx-execpipe.cc.

void stx::ExecPipe::add_exec	(	const char *	prog,
		const char *	arg1,
		const char *	arg2,
		const char *	arg3
	)

Add an exec() stage to the pipe with given arguments.

Note that argv[0] is set to prog.

Definition at line 1593 of file stx-execpipe.cc.

void stx::ExecPipe::add_exec	(	const char *	prog,
		const char *	arg1,
		const char *	arg2
	)

Add an exec() stage to the pipe with given arguments.

Note that argv[0] is set to prog.

Definition at line 1588 of file stx-execpipe.cc.

void stx::ExecPipe::add_exec	(	const char *	prog,
		const char *	arg1
	)

Add an exec() stage to the pipe with given arguments.

Note that argv[0] is set to prog.

Definition at line 1583 of file stx-execpipe.cc.

void stx::ExecPipe::add_exec ( const char * prog )

Add an exec() stage to the pipe with given arguments.

Note that argv[0] is set to prog.

Examples:: simple1.cc.

Definition at line 1578 of file stx-execpipe.cc.

void stx::ExecPipe::add_exece	(	const char *	path,
		const std::vector< std::string > *	args,
		const std::vector< std::string > *	env
	)

Add an exece() stage to the pipe with the given arguments and environments.

This is the most flexible exec() call. The vector of arguments and environment variables is not copied, so it must still exist when run() is called. The args[0] is _not_ override with path, so you can fake program name calls.

Definition at line 1628 of file stx-execpipe.cc.

void stx::ExecPipe::add_execp ( const std::vector< std::string > * args )