Execute a program and give access to its io An object of this class encapsulates the execution of an external program. More...

#include <ExternalProgram.h>

Inheritance diagram for zypp::ExternalProgram:

[legend]

Public Types
enum	Stderr_Disposition { Normal_Stderr, Discard_Stderr, Stderr_To_Stdout, Stderr_To_FileDesc }
	Define symbols for different policies on the handling of stderr. More...

typedef std::vector< std::string >	Arguments

typedef std::map< std::string, std::string >	Environment
	For passing additional environment variables to set. More...

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 Pathname &root="")
	Start the external program by using the shell `/bin/sh with the option -c.` More...

	ExternalProgram ()
	Start an external program by giving the arguments as an arry of char *pointers. More...

	ExternalProgram (const Arguments &argv, Stderr_Disposition stderr_disp=Normal_Stderr, bool use_pty=false, int stderr_fd=-1, bool default_locale=false, const 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 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 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 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 ()
	Wait for the progamm to complete. More...

bool	kill ()
	Kill the program. More...

bool	kill (int sig)
	Send a signal to the program. More...

bool	running ()
	Return whether program is running. More...

pid_t	getpid ()
	return pid More...

const std::string &	command () const
	The command we're executing. More...

const std::string &	execError () const
	Some detail telling why the execution failed, if it failed. More...

std::ostream &	operator>> (std::ostream &out_r)
	Redirect all command output to an `ostream`. More...

Public Member Functions inherited from zypp::externalprogram::ExternalDataSource
	ExternalDataSource (FILE inputfile=0, FILE outputfile=0)
	Create a new instance. More...

virtual	~ExternalDataSource ()
	Implicitly close the connection. More...

bool	send (const char *buffer, size_t length)
	Send some data to the output stream. More...

bool	send (std::string s)
	Send some data down the stream. More...

size_t	receive (char *buffer, size_t length)
	Read some data from the input stream. More...

std::string	receiveLine ()
	Read one line from the input stream. More...

std::string	receiveLine (io::timeout_type timeout)
	Read one line from the input stream. More...

std::string	receiveUpto (char c)
	Read characters into a string until delimiter c or EOF is read. More...

std::string	receiveUpto (char c, io::timeout_type timeout)
	Read characters into a string until delimiter c or EOF is read or the timeout is reached. More...

void	setBlocking (bool mode)
	Set the blocking mode of the input stream. More...

FILE *	inputFile () const
	Return the input stream. More...

FILE *	outputFile () const
	Return the output stream. More...

Static Public Member Functions
static void	renumber_fd (int origfd, int newfd)
	origfd will be accessible as newfd and closed (unless they were equal) More...

Protected Member Functions
int	checkStatus (int)

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, bool switch_pgid=false, bool die_with_parent=false)

Private Attributes
bool	use_pty
	Set to true, if a pair of ttys is used for communication instead of a pair of pipes. More...

pid_t	pid

int	_exitStatus

std::string	_command
	Store the command we're executing. More...

std::string	_execError
	Remember execution errors like failed fork/exec. More...

Additional Inherited Members
Protected Attributes inherited from zypp::externalprogram::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();

Definition at line 59 of file ExternalProgram.h.

Member Typedef Documentation

◆ Arguments

typedef std::vector<std::string> zypp::ExternalProgram::Arguments

Definition at line 64 of file ExternalProgram.h.

◆ Environment

typedef std::map<std::string,std::string> zypp::ExternalProgram::Environment

For passing additional environment variables to set.

Definition at line 81 of file ExternalProgram.h.

Member Enumeration Documentation

◆ Stderr_Disposition

enum zypp::ExternalProgram::Stderr_Disposition

Define symbols for different policies on the handling of stderr.

Enumerator
Normal_Stderr
Discard_Stderr
Stderr_To_Stdout
Stderr_To_FileDesc

Definition at line 70 of file ExternalProgram.h.

Constructor & Destructor Documentation

◆ ExternalProgram() [1/8]

zypp::ExternalProgram::ExternalProgram	(	std::string	commandline,
		Stderr_Disposition	stderr_disp = `Normal_Stderr`,
		bool	use_pty = `false`,
		int	stderr_fd = `-1`,
		bool	default_locale = `false`,
		const Pathname &	root = `""`
	)

Start the external program by using the shell /bin/sh with the option -c.

You can use io direction symbols < and >.

Parameters

commandline	a shell commandline that is appended to `/bin/sh -c`.
default_locale	whether to set LC_ALL=C before starting
root	directory to chroot into; or just 'cd' if '/'l; nothing if empty

Definition at line 46 of file ExternalProgram.cc.

◆ ExternalProgram() [2/8]

zypp::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.

Initial args starting with # are discarded but some are treated specially: #/[path] - chdir to /[path] before executing

Stdin redirection: If the 1st argument starts with a '<', the remaining part is treated as file opened for reading on standard input (or /dev/null if empty).

// cat file /tmp/x
const char* argv[] = { "</tmp/x", "cat", NULL };
ExternalProgram prog( argv );

Stdout redirection: If the 1st argument starts with a '>', the remaining part is treated as file opened for writing on standard output (or /dev/null if empty).

Definition at line 40 of file ExternalProgram.cc.

◆ ExternalProgram() [3/8]

zypp::ExternalProgram::ExternalProgram	(	const Arguments &	argv,
		Stderr_Disposition	stderr_disp = `Normal_Stderr`,
		bool	use_pty = `false`,
		int	stderr_fd = `-1`,
		bool	default_locale = `false`,
		const Pathname &	root = `""`
	)

Definition at line 65 of file ExternalProgram.cc.

◆ ExternalProgram() [4/8]

zypp::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 Pathname &	root = `""`
	)

Definition at line 87 of file ExternalProgram.cc.

◆ ExternalProgram() [5/8]

zypp::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 Pathname &	root = `""`
	)

Definition at line 111 of file ExternalProgram.cc.

◆ ExternalProgram() [6/8]

zypp::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 Pathname &	root = `""`
	)

Definition at line 124 of file ExternalProgram.cc.

◆ ExternalProgram() [7/8]

zypp::ExternalProgram::ExternalProgram	(	const char *	binpath,
		const char const	argv_1,
		bool	use_pty = `false`
	)

Definition at line 138 of file ExternalProgram.cc.

◆ ExternalProgram() [8/8]

zypp::ExternalProgram::ExternalProgram	(	const char *	binpath,
		const char const	argv_1,
		const Environment &	environment,
		bool	use_pty = `false`
	)

Definition at line 154 of file ExternalProgram.cc.

◆ ~ExternalProgram()

zypp::ExternalProgram::~ExternalProgram ( )

Definition at line 171 of file ExternalProgram.cc.

Member Function Documentation

◆ close()

int zypp::ExternalProgram::close ( )

virtual

Wait for the progamm to complete.

Reimplemented from zypp::externalprogram::ExternalDataSource.

Definition at line 456 of file ExternalProgram.cc.

◆ kill() [1/2]

bool zypp::ExternalProgram::kill ( )

Kill the program.

Definition at line 574 of file ExternalProgram.cc.

◆ kill() [2/2]

bool zypp::ExternalProgram::kill ( int sig )

Send a signal to the program.

Definition at line 584 of file ExternalProgram.cc.

◆ running()

bool zypp::ExternalProgram::running ( )

Return whether program is running.

Definition at line 594 of file ExternalProgram.cc.

◆ getpid()

pid_t zypp::ExternalProgram::getpid ( )

inline

return pid

Definition at line 171 of file ExternalProgram.h.

◆ command()

const std::string& zypp::ExternalProgram::command ( ) const

inline

The command we're executing.

Definition at line 174 of file ExternalProgram.h.

◆ execError()

const std::string& zypp::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).

Definition at line 186 of file ExternalProgram.h.

◆ renumber_fd()

void zypp::ExternalProgram::renumber_fd	(	int	origfd,
		int	newfd
	)

static

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

Definition at line 618 of file ExternalProgram.cc.

◆ operator>>()

std::ostream & zypp::ExternalProgram::operator>> ( std::ostream & out_r )

Redirect all command output to an ostream.

Returns when the command has completed.

std::ostringstream s;
ExternalProgram("pwd") >> s;
SEC << s.str() << endl;

std::ostringstream s;
ExternalProgram prog("ls -l wrzl");
prog >> s;
if ( prog.close() == 0 )
  MIL << s.str() << endl;
else
  ERR << prog.execError() << endl;

Definition at line 630 of file ExternalProgram.cc.

◆ checkStatus()

int zypp::ExternalProgram::checkStatus ( int status )

protected

Definition at line 534 of file ExternalProgram.cc.

◆ start_program()

void zypp::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`,
		bool	switch_pgid = `false`,
		bool	die_with_parent = `false`
	)

protected

Definition at line 182 of file ExternalProgram.cc.

Member Data Documentation

◆ use_pty

bool zypp::ExternalProgram::use_pty

private

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

Definition at line 225 of file ExternalProgram.h.

◆ pid

pid_t zypp::ExternalProgram::pid

private

Definition at line 227 of file ExternalProgram.h.

◆ _exitStatus

int zypp::ExternalProgram::_exitStatus

private

Definition at line 228 of file ExternalProgram.h.

◆ _command

std::string zypp::ExternalProgram::_command

private

Store the command we're executing.

Definition at line 230 of file ExternalProgram.h.

◆ _execError

std::string zypp::ExternalProgram::_execError

private

Remember execution errors like failed fork/exec.

Definition at line 232 of file ExternalProgram.h.

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

zypp/ExternalProgram.h
zypp/ExternalProgram.cc

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ Arguments

◆ Environment

Member Enumeration Documentation

◆ Stderr_Disposition

Constructor & Destructor Documentation

◆ ExternalProgram() [1/8]

◆ ExternalProgram() [2/8]

◆ ExternalProgram() [3/8]

◆ ExternalProgram() [4/8]

◆ ExternalProgram() [5/8]

◆ ExternalProgram() [6/8]

◆ ExternalProgram() [7/8]

◆ ExternalProgram() [8/8]

◆ ~ExternalProgram()

Member Function Documentation

◆ close()

◆ kill() [1/2]

◆ kill() [2/2]

◆ running()

◆ getpid()

◆ command()

◆ execError()

◆ renumber_fd()

◆ operator>>()

◆ checkStatus()

◆ start_program()

Member Data Documentation

◆ use_pty

◆ pid

◆ _exitStatus

◆ _command

◆ _execError