libcamgm
Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Private Member Functions | Private Attributes | List of all members
ca_mgm::ExternalProgram Class Reference

Execute a program and give access to its io An object of this class encapsulates the execution of an external program. It starts the program using fork and some exec.. call, gives you access to the program's stdio and closes the program after use. More...

#include <ExternalProgram.hpp>

Inheritance diagram for ca_mgm::ExternalProgram:
ca_mgm::ExternalDataSource

Public Types

enum  Stderr_Disposition { Normal_Stderr, Discard_Stderr, Stderr_To_Stdout, Stderr_To_FileDesc }
 
typedef std::vector< std::string > Arguments
 
typedef std::map< std::string,
std::string > 
Environment
 

Public Member Functions

 ExternalProgram (std::string commandline, Stderr_Disposition stderr_disp=Normal_Stderr, bool use_pty=false, int stderr_fd=-1, bool default_locale=false, const path::PathName &root="")
 
 ExternalProgram ()
 
 ExternalProgram (const Arguments &argv, Stderr_Disposition stderr_disp=Normal_Stderr, bool use_pty=false, int stderr_fd=-1, bool default_locale=false, const path::PathName &root="")
 
 ExternalProgram (const Arguments &argv, const Environment &environment, Stderr_Disposition stderr_disp=Normal_Stderr, bool use_pty=false, int stderr_fd=-1, bool default_locale=false, const path::PathName &root="")
 
 ExternalProgram (const char *const *argv, Stderr_Disposition stderr_disp=Normal_Stderr, bool use_pty=false, int stderr_fd=-1, bool default_locale=false, const path::PathName &root="")
 
 ExternalProgram (const char *const *argv, const Environment &environment, Stderr_Disposition stderr_disp=Normal_Stderr, bool use_pty=false, int stderr_fd=-1, bool default_locale=false, const path::PathName &root="")
 
 ExternalProgram (const char *binpath, const char *const *argv_1, bool use_pty=false)
 
 ExternalProgram (const char *binpath, const char *const *argv_1, const Environment &environment, bool use_pty=false)
 
 ~ExternalProgram ()
 
int close ()
 
bool kill ()
 
bool running ()
 
pid_t getpid ()
 
const std::string & command () const
 
const std::string & execError () const
 
- Public Member Functions inherited from ca_mgm::ExternalDataSource
 ExternalDataSource (FILE *inputfile=0, FILE *outputfile=0)
 
virtual ~ExternalDataSource ()
 
bool send (const char *buffer, size_t length)
 
bool send (std::string s)
 
size_t receive (char *buffer, size_t length)
 
std::string receiveLine ()
 
std::string receiveUpto (char c)
 
void setBlocking (bool mode)
 
FILE * inputFile () const
 
FILE * outputFile () const
 

Static Public Member Functions

static void renumber_fd (int origfd, int newfd)
 

Protected Member Functions

int checkStatus (int)
 

Private Member Functions

void start_program (const char *const *argv, const Environment &environment, Stderr_Disposition stderr_disp=Normal_Stderr, int stderr_fd=-1, bool default_locale=false, const char *root=NULL)
 

Private Attributes

bool use_pty
 
pid_t pid
 
int _exitStatus
 
std::string _command
 
std::string _execError
 

Additional Inherited Members

- Protected Attributes inherited from ca_mgm::ExternalDataSource
FILE * inputfile
 
FILE * outputfile
 

Detailed Description

Execute a program and give access to its io An object of this class encapsulates the execution of an external program. It starts the program using fork and some exec.. call, gives you access to the program's stdio and closes the program after use.

const char* argv[] =
{
"/usr/bin/foo,
"--option1",
"--option2",
NULL
};
ExternalProgram prog( argv,
ExternalProgram::Discard_Stderr,
false, -1, true);
string line;
for(line = prog.receiveLine();
! line.empty();
line = prog.receiveLine() )
{
stream << line;
}
prog.close();

Member Typedef Documentation

typedef std::vector<std::string> ca_mgm::ExternalProgram::Arguments
typedef std::map<std::string,std::string> ca_mgm::ExternalProgram::Environment

For passing additional environment variables to set

Member Enumeration Documentation

Define symbols for different policies on the handling of stderr

Enumerator
Normal_Stderr 
Discard_Stderr 
Stderr_To_Stdout 
Stderr_To_FileDesc 

Constructor & Destructor Documentation

ca_mgm::ExternalProgram::ExternalProgram ( std::string  commandline,
Stderr_Disposition  stderr_disp = Normal_Stderr,
bool  use_pty = false,
int  stderr_fd = -1,
bool  default_locale = false,
const path::PathName root = "" 
)

Start the external program by using the shell /bin/sh with the option -c. You can use io direction symbols < and >.

Parameters
commandlinea shell commandline that is appended to /bin/sh -c.
default_localewhether to set LC_ALL=C before starting
rootdirectory to chroot into, / or empty to not chroot

ca_mgm::ExternalProgram::ExternalProgram ( )

Start an external program by giving the arguments as an arry of char *pointers. If environment is provided, varaiables will be added to the childs environment, overwriting existing ones.

Exceptions
ExternalProgramExceptionif fork fails.
ca_mgm::ExternalProgram::ExternalProgram ( const Arguments argv,
Stderr_Disposition  stderr_disp = Normal_Stderr,
bool  use_pty = false,
int  stderr_fd = -1,
bool  default_locale = false,
const path::PathName root = "" 
)
ca_mgm::ExternalProgram::ExternalProgram ( const Arguments argv,
const Environment environment,
Stderr_Disposition  stderr_disp = Normal_Stderr,
bool  use_pty = false,
int  stderr_fd = -1,
bool  default_locale = false,
const path::PathName root = "" 
)
ca_mgm::ExternalProgram::ExternalProgram ( const char *const *  argv,
Stderr_Disposition  stderr_disp = Normal_Stderr,
bool  use_pty = false,
int  stderr_fd = -1,
bool  default_locale = false,
const path::PathName root = "" 
)
ca_mgm::ExternalProgram::ExternalProgram ( const char *const *  argv,
const Environment environment,
Stderr_Disposition  stderr_disp = Normal_Stderr,
bool  use_pty = false,
int  stderr_fd = -1,
bool  default_locale = false,
const path::PathName root = "" 
)
ca_mgm::ExternalProgram::ExternalProgram ( const char *  binpath,
const char *const *  argv_1,
bool  use_pty = false 
)
ca_mgm::ExternalProgram::ExternalProgram ( const char *  binpath,
const char *const *  argv_1,
const Environment environment,
bool  use_pty = false 
)
ca_mgm::ExternalProgram::~ExternalProgram ( )

Member Function Documentation

int ca_mgm::ExternalProgram::checkStatus ( int  )
protected
int ca_mgm::ExternalProgram::close ( )
virtual

Close the input and output streams.

Reimplemented from ca_mgm::ExternalDataSource.

const std::string& ca_mgm::ExternalProgram::command ( ) const
inline

The command we're executing.

References _command.

const std::string& ca_mgm::ExternalProgram::execError ( ) const
inline

Some detail telling why the execution failed, if it failed. Empty if the command is still running or successfully completed.

  • Can't open pty (s).
  • Can't open pipe (s).
  • Can't fork (s).
  • Command exited with status d.
  • Command was killed by signal d (s).

References _execError.

pid_t ca_mgm::ExternalProgram::getpid ( )
inline

return pid

References pid.

bool ca_mgm::ExternalProgram::kill ( )

Kill the program

static void ca_mgm::ExternalProgram::renumber_fd ( int  origfd,
int  newfd 
)
static

origfd will be accessible as newfd and closed (unless they were equal)

bool ca_mgm::ExternalProgram::running ( )

Return whether program is running

void ca_mgm::ExternalProgram::start_program ( const char *const *  argv,
const Environment environment,
Stderr_Disposition  stderr_disp = Normal_Stderr,
int  stderr_fd = -1,
bool  default_locale = false,
const char *  root = NULL 
)
private

Member Data Documentation

std::string ca_mgm::ExternalProgram::_command
private

Store the command we're executing.

Referenced by command().

std::string ca_mgm::ExternalProgram::_execError
private

Remember execution errors like failed fork/exec.

Referenced by execError().

int ca_mgm::ExternalProgram::_exitStatus
private
pid_t ca_mgm::ExternalProgram::pid
private

Referenced by getpid().

bool ca_mgm::ExternalProgram::use_pty
private

Set to true, if a pair of ttys is used for communication instead of a pair of pipes.


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