stx::ExecPipe Class Reference

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

#include <stx-execpipe.h>

List of all members.

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.
ExecPipeoperator= (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.
ExecPiperun ()
 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 ExecPipeImplm_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

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  ) 

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

The PATH variable is search for programs not containing a slash / character. 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 1623 of file stx-execpipe.cc.

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

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

The PATH variable is search for programs not containing a slash / character. Note that argv[0] is set to prog.

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

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

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

The PATH variable is search for programs not containing a slash / character. Note that argv[0] is set to prog.

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

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

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

The PATH variable is search for programs not containing a slash / character. Note that argv[0] is set to prog.

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

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

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

The PATH variable is search for programs not containing a slash / character. Note that argv[0] is set to prog.

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

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

void stx::ExecPipe::add_function ( PipeFunction func  ) 

Add a function stage to the pipe.

This function object will be called in the parent process with data passing through the stage. See PipeFunction for more information.

Examples:
functions1.cc.

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

bool stx::ExecPipe::all_return_codes_zero (  )  const

Return true if the return code of all exec() stages were zero.

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

int stx::ExecPipe::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.

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

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

int stx::ExecPipe::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.

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

int stx::ExecPipe::get_return_status ( unsigned int  stageid  )  const

Get the return status of exec() stage's program run after pipe execution as indicated by wait().

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

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

Assignment operator creates a new reference to the right pipe.

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

ExecPipe & stx::ExecPipe::run (  ) 

Run the configured pipe sequence and wait for all children processes to complete.

Returns a reference to *this for chaining.

This function call should be wrapped into a try-catch block as it will throw() if a system call fails.

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

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

void stx::ExecPipe::set_debug_level ( enum DebugLevel  dl  ) 

Change the current debug level. The default is DL_ERROR.

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

void stx::ExecPipe::set_debug_output ( void(*)(const char *line)  output  ) 

Change output function for debug messages.

If set to NULL (the default) the debug lines are printed to stdout.

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

void stx::ExecPipe::set_input_fd ( int  fd  ) 

Assign an already opened file descriptor as input stream for the first exec stage.

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

void stx::ExecPipe::set_input_file ( const char *  path  ) 

Assign a file as input stream source.

This file will be opened read-only and read by the first exec stage.

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

void stx::ExecPipe::set_input_source ( PipeSource source  ) 

Assign a PipeSource as input stream source.

The object will be queried via the read() function for data which is then written to the first exec stage.

Examples:
functions1.cc.

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

void stx::ExecPipe::set_input_string ( const std::string *  input  ) 

Assign a std::string as input stream source.

The contents of the string will be written to the first exec stage. The string object is not copied and must still exist when run() is called.

Examples:
simple2.cc.

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

void stx::ExecPipe::set_output_fd ( int  fd  ) 

Assign an already opened file descriptor as output stream for the last exec stage.

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

void stx::ExecPipe::set_output_file ( const char *  path,
int  mode = 0666 
)

Assign a file as output stream destination.

This file will be created or truncated write-only and written by the last exec stage.

Examples:
functions1.cc.

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

void stx::ExecPipe::set_output_sink ( PipeSink sink  ) 

Assign a PipeSink as output stream destination.

The object will receive data via the process() function and is informed via eof()

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

void stx::ExecPipe::set_output_string ( std::string *  output  ) 

Assign a std::string as output stream destination.

The output of the last exec stage will be stored as the contents of the string. The string object is not copied and must still exist when run() is called.

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

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

unsigned int stx::ExecPipe::size (  )  const

Return the number of pipe stages added.

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


Member Data Documentation

class ExecPipeImpl* stx::ExecPipe::m_impl [protected]

reference-counted pointer implementation

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


The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends
Generated on Sun Jul 18 22:23:45 2010 for STX Execution Pipe by  doxygen 1.6.3