1 /*---------------------------------------------------------------------\
3 | |__ / \ / / . \ . \ |
8 \---------------------------------------------------------------------*/
9 /** \file zypp/ExternalProgram.h
13 #ifndef ZYPP_EXTERNALPROGRAM_H
14 #define ZYPP_EXTERNALPROGRAM_H
20 #include "zypp/base/ExternalDataSource.h"
21 #include "zypp/Pathname.h"
26 * @short Execute a program and give access to its io
27 * An object of this class encapsulates the execution of
28 * an external program. It starts the program using fork
29 * and some exec.. call, gives you access to the program's
30 * stdio and closes the program after use.
34 * const char* argv[] =
42 * ExternalProgram prog( argv,
43 * ExternalProgram::Discard_Stderr,
46 * for(line = prog.receiveLine();
48 * line = prog.receiveLine() )
56 class ExternalProgram : public zypp::externalprogram::ExternalDataSource
61 typedef std::vector<std::string> Arguments;
64 * Define symbols for different policies on the handling
67 enum Stderr_Disposition {
76 * For passing additional environment variables to set
78 typedef std::map<std::string,std::string> Environment;
81 * Start the external program by using the shell <tt>/bin/sh<tt>
82 * with the option <tt>-c</tt>. You can use io direction symbols < and >.
83 * @param commandline a shell commandline that is appended to
84 * <tt>/bin/sh -c</tt>.
85 * @param default_locale whether to set LC_ALL=C before starting
86 * @param root directory to chroot into, / or empty to not chroot
88 ExternalProgram (std::string commandline,
89 Stderr_Disposition stderr_disp = Normal_Stderr,
90 bool use_pty = false, int stderr_fd = -1, bool default_locale = false,
91 const Pathname& root = "");
94 * Start an external program by giving the arguments as an arry of char *pointers.
95 * If environment is provided, varaiables will be added to the childs environment,
96 * overwriting existing ones.
97 * \throws ExternalProgramException if fork fails.
102 ExternalProgram (const Arguments &argv,
103 Stderr_Disposition stderr_disp = Normal_Stderr,
104 bool use_pty = false, int stderr_fd = -1, bool default_locale = false,
105 const Pathname& root = "");
107 ExternalProgram (const Arguments &argv, const Environment & environment,
108 Stderr_Disposition stderr_disp = Normal_Stderr,
109 bool use_pty = false, int stderr_fd = -1, bool default_locale = false,
110 const Pathname& root = "");
112 ExternalProgram (const char *const *argv,
113 Stderr_Disposition stderr_disp = Normal_Stderr,
114 bool use_pty = false, int stderr_fd = -1, bool default_locale = false,
115 const Pathname& root = "");
117 ExternalProgram (const char *const *argv, const Environment & environment,
118 Stderr_Disposition stderr_disp = Normal_Stderr,
119 bool use_pty = false, int stderr_fd = -1, bool default_locale = false,
120 const Pathname& root = "");
122 ExternalProgram (const char *binpath, const char *const *argv_1,
123 bool use_pty = false);
126 ExternalProgram (const char *binpath, const char *const *argv_1, const Environment & environment,
127 bool use_pty = false);
132 /** Wait for the progamm to complete. */
141 * Return whether program is running
148 pid_t getpid() { return pid; }
150 /** The command we're executing. */
151 const std::string & command() const
154 /** Some detail telling why the execution failed, if it failed.
155 * Empty if the command is still running or successfully completed.
157 * \li <tt>Can't open pty (%s).</tt>
158 * \li <tt>Can't open pipe (%s).</tt>
159 * \li <tt>Can't fork (%s).</tt>
160 * \li <tt>Command exited with status %d.</tt>
161 * \li <tt>Command was killed by signal %d (%s).</tt>
163 const std::string & execError() const
164 { return _execError; }
167 * origfd will be accessible as newfd and closed (unless they were equal)
169 static void renumber_fd (int origfd, int newfd);
174 * Redirect all command output to an \c ostream.
175 * Returns when the command has completed.
177 * std::ostringstream s;
178 * ExternalProgram("pwd") >> s;
179 * SEC << s.str() << endl;
182 * std::ostringstream s;
183 * ExternalProgram prog("ls -l wrzl");
185 * if ( prog.close() == 0 )
186 * MIL << s.str() << endl;
188 * ERR << prog.execError() << endl;
191 std::ostream & operator>>( std::ostream & out_r );
194 int checkStatus( int );
199 * Set to true, if a pair of ttys is used for communication
200 * instead of a pair of pipes.
206 /** Store the command we're executing. */
207 std::string _command;
208 /** Remember execution errors like failed fork/exec. */
209 std::string _execError;
211 void start_program (const char *const *argv, const Environment & environment,
212 Stderr_Disposition stderr_disp = Normal_Stderr,
213 int stderr_fd = -1, bool default_locale = false,
214 const char* root = NULL);
220 #endif // ZYPP_EXTERNALPROGRAM_H