zypp/ExternalProgram.h

   1 /*---------------------------------------------------------------------\
   2 |                          ____ _   __ __ ___                          |
   3 |                         |__  / \ / / . \ . \                         |
   4 |                           / / \ V /|  _/  _/                         |
   5 |                          / /__ | | | | | |                           |
   6 |                         /_____||_| |_| |_|                           |
   7 |                                                                      |
   8 \---------------------------------------------------------------------*/
   9 /** \file zypp/ExternalProgram.h
  10 */
  11
  12
  13 #ifndef ZYPP_EXTERNALPROGRAM_H
  14 #define ZYPP_EXTERNALPROGRAM_H
  15
  16 #include <map>
  17 #include <string>
  18
  19 #include "zypp/base/ExternalDataSource.h"
  20 #include "zypp/Pathname.h"
  21
  22 namespace zypp {
  23
  24     /**
  25      * @short Execute a program and give access to its io
  26      * An object of this class encapsulates the execution of
  27      * an external program. It starts the program using fork
  28      * and some exec.. call, gives you access to the program's
  29      * stdio and closes the program after use.
  30      */
  31     class ExternalProgram : public zypp::externalprogram::ExternalDataSource
  32     {
  33
  34     public:
  35       /**
  36        * Define symbols for different policies on the handling
  37        * of stderr
  38        */
  39       enum Stderr_Disposition {
  40         Normal_Stderr,
  41         Discard_Stderr,
  42         Stderr_To_Stdout,
  43         Stderr_To_FileDesc
  44       };
  45
  46
  47       /**
  48        * For passing additional environment variables to set
  49        */
  50       typedef std::map<std::string,std::string> Environment;
  51
  52       /**
  53        * Start the external program by using the shell <tt>/bin/sh<tt>
  54        * with the option <tt>-c</tt>. You can use io direction symbols < and >.
  55        * @param commandline a shell commandline that is appended to
  56        * <tt>/bin/sh -c</tt>.
  57        * @param default_locale whether to set LC_ALL=C before starting
  58        * @param root directory to chroot into, / or empty to not chroot
  59        */
  60       ExternalProgram (std::string commandline,
  61                      Stderr_Disposition stderr_disp = Normal_Stderr,
  62                      bool use_pty = false, int stderr_fd = -1, bool default_locale = false,
  63                      const Pathname& root = "");
  64
  65       /**
  66        * Start an external program by giving the arguments as an arry of char *pointers.
  67        * If environment is provided, varaiables will be added to the childs environment,
  68        * overwriting existing ones.
  69        * \throws ExternalProgramException if fork fails.
  70        */
  71
  72       ExternalProgram();
  73
  74       ExternalProgram (const char *const *argv,
  75                      Stderr_Disposition stderr_disp = Normal_Stderr,
  76                      bool use_pty = false, int stderr_fd = -1, bool default_locale = false,
  77                      const Pathname& root = "");
  78
  79       ExternalProgram (const char *const *argv, const Environment & environment,
  80                      Stderr_Disposition stderr_disp = Normal_Stderr,
  81                      bool use_pty = false, int stderr_fd = -1, bool default_locale = false,
  82                      const Pathname& root = "");
  83
  84       ExternalProgram (const char *binpath, const char *const *argv_1,
  85                      bool use_pty = false);
  86
  87
  88       ExternalProgram (const char *binpath, const char *const *argv_1, const Environment & environment,
  89                      bool use_pty = false);
  90
  91
  92       ~ExternalProgram();
  93
  94       int close();
  95
  96       /**
  97        * Kill the program
  98        */
  99       bool kill();
 100
 101       /**
 102        * Return whether program is running
 103        */
 104       bool running();
 105
 106       /**
 107        * return pid
 108        * */
 109       pid_t getpid() { return pid; }
 110
 111       /** The command we're executing. */
 112       const std::string & command() const
 113       { return _command; }
 114
 115       /** Some detail telling why the execution failed, if it failed.
 116        * Empty if the command is still running or successfully completed.
 117        *
 118        * \li <tt>Can't open pty (%s).</tt>
 119        * \li <tt>Can't open pipe (%s).</tt>
 120        * \li <tt>Can't fork (%s).</tt>
 121        * \li <tt>Command exited with status %d.</tt>
 122        * \li <tt>Command was killed by signal %d (%s).</tt>
 123       */
 124       const std::string & execError() const
 125       { return _execError; }
 126
 127       /**
 128        * origfd will be accessible as newfd and closed (unless they were equal)
 129        */
 130       static void renumber_fd (int origfd, int newfd);
 131
 132     protected:
 133       int checkStatus( int );
 134
 135     private:
 136
 137       /**
 138        * Set to true, if a pair of ttys is used for communication
 139        * instead of a pair of pipes.
 140        */
 141       bool use_pty;
 142
 143       pid_t pid;
 144       int _exitStatus;
 145       /** Store the command we're executing. */
 146       std::string _command;
 147       /** Remember execution errors like failed fork/exec. */
 148       std::string _execError;
 149
 150       void start_program (const char *const *argv, const Environment & environment,
 151                         Stderr_Disposition stderr_disp = Normal_Stderr,
 152                         int stderr_fd = -1, bool default_locale = false,
 153                         const char* root = NULL);
 154
 155     };
 156
 157 } // namespace zypp
 158
 159 #endif // ZYPP_EXTERNALPROGRAM_H