libzypp: zypp::ExternalProgram Class Reference

libzypp 17.38.11

zypp::ExternalProgram Class Reference

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

`#include <zypp-core/ExternalProgram.h>`

Inheritance diagram for zypp::ExternalProgram:

## 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...
using | Arguments = std::vector<std::string>
using | Environment = std::map<std::string, std::string>
| For passing additional environment variables to set.

## Public Member Functions
| ExternalProgram (const 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.
| ExternalProgram ()
| Start an external program by giving the arguments as an arry of char *pointers.
| 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 () override
int | close () override
| Wait for the progamm to complete.
bool | kill ()
| Kill the program.
bool | kill (int sig)
| Send a signal to the program.
bool | running ()
| Return whether program is running.
Pathname | chroot () const
| Return the configured chroot path or empty.
pid_t | getpid ()
| return pid
const std::string & | command () const
| The command we're executing.
const std::string & | execError () const
| Some detail telling why the execution failed, if it failed.
std::ostream & | operator>> (std::ostream &out_r)
| Redirect all command output to an `ostream`.
Public Member Functions inherited from zypp::externalprogram::ExternalDataSource
| ExternalDataSource (FILE *inputfile=0, FILE *outputfile=0)
| Create a new instance.
virtual | ~ExternalDataSource ()
| Implicitly close the connection.
bool | send (const char *buffer, size_t length)
| Send some data to the output stream.
bool | send (std::string s)
| Send some data down the stream.
size_t | receive (char *buffer, size_t length)
| Read some data from the input stream.
std::string | receiveLine ()
| Read one line from the input stream.
std::string | receiveLine (io::timeout_type timeout)
| Read one line from the input stream.
std::string | receiveUpto (char c)
| Read characters into a string until delimiter c or EOF is read.
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.
void | setBlocking (bool mode)
| Set the blocking mode of the input stream.
FILE * | inputFile () const
| Return the input stream.
FILE * | outputFile () const
| Return the output stream.

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

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

## Private Attributes
std::unique_ptr< zyppng::AbstractSpawnEngine > | _backend

## 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 63 of file ExternalProgram.h.

## Member Typedef Documentation

## ◆ Arguments

using zypp::ExternalProgram::Arguments = std::vector<std::string>

Definition at line 68 of file ExternalProgram.h.

## ◆ Environment

using zypp::ExternalProgram::Environment = std::map<std::string, std::string>

For passing additional environment variables to set.

Definition at line 84 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 74 of file ExternalProgram.h.

## Constructor & Destructor Documentation

## ◆ ExternalProgram() [1/8]

zypp::ExternalProgram::ExternalProgram | ( | const 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 48 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 );
zypp::ExternalProgram
Execute a program and give access to its io An object of this class encapsulates the execution of an ...
Definition ExternalProgram.h:64

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 44 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 64 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 83 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 103 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 113 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 125 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 138 of file ExternalProgram.cc.

## ◆ ~ExternalProgram()

zypp::ExternalProgram::~ExternalProgram | ( |  | ) |
| override

Definition at line 152 of file ExternalProgram.cc.

## Member Function Documentation

## ◆ close()

int zypp::ExternalProgram::close | ( |  | ) |
| overridevirtual

Wait for the progamm to complete.

Reimplemented from zypp::externalprogram::ExternalDataSource.

Definition at line 357 of file ExternalProgram.cc.

## ◆ kill() [1/2]

bool zypp::ExternalProgram::kill | ( |  | ) |

Kill the program.

Definition at line 425 of file ExternalProgram.cc.

## ◆ kill() [2/2]

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

Send a signal to the program.

Definition at line 438 of file ExternalProgram.cc.

## ◆ running()

bool zypp::ExternalProgram::running | ( |  | ) |

Return whether program is running.

Definition at line 451 of file ExternalProgram.cc.

## ◆ chroot()

Pathname zypp::ExternalProgram::chroot | ( |  | ) | const

Return the configured chroot path or empty.

Definition at line 457 of file ExternalProgram.cc.

## ◆ getpid()

pid_t zypp::ExternalProgram::getpid | ( |  | ) |

return pid

Definition at line 464 of file ExternalProgram.cc.

## ◆ command()

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

The command we're executing.

Definition at line 471 of file ExternalProgram.cc.

## ◆ execError()

const std::string & zypp::ExternalProgram::execError | ( |  | ) | const

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 480 of file ExternalProgram.cc.

## ◆ 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 490 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;
SEC
#define SEC
Definition Logger.h:106
zypp::ExternalProgram::ExternalProgram
ExternalProgram()
Start an external program by giving the arguments as an arry of char *pointers.
Definition ExternalProgram.cc:44
std::ostringstream s;
ExternalProgram prog("ls -l wrzl");
prog >> s;
if ( prog.close() == 0 )
MIL << s.str() << endl;
else
ERR << prog.execError() << endl;
MIL
#define MIL
Definition Logger.h:103
ERR
#define ERR
Definition Logger.h:105
zypp::ExternalProgram::ExternalProgram
ExternalProgram(const 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.
Definition ExternalProgram.cc:48

Definition at line 495 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,
|  | bool | usePty = false )
| protected

Definition at line 157 of file ExternalProgram.cc.

## Member Data Documentation

## ◆ _backend

std::unique_ptr<zyppng::AbstractSpawnEngine> zypp::ExternalProgram::_backend
| private

Definition at line 235 of file ExternalProgram.h.

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

- zypp-core/ExternalProgram.h
- zypp-core/ExternalProgram.cc