Retry wait() on EINTR; clean up signal handling
[folly.git] / folly / Subprocess.h
1 /*
2  * Copyright 2012 Facebook, Inc.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *   http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16
17 /**
18  * Subprocess library, modeled after Python's subprocess module
19  * (http://docs.python.org/2/library/subprocess.html)
20  *
21  * This library defines one class (Subprocess) which represents a child
22  * process.  Subprocess has two constructors: one that takes a vector<string>
23  * and executes the given executable without using the shell, and one
24  * that takes a string and executes the given command using the shell.
25  * Subprocess allows you to redirect the child's standard input, standard
26  * output, and standard error to/from child descriptors in the parent,
27  * or to create communication pipes between the child and the parent.
28  *
29  * The simplest example is a thread-safe version of the system() library
30  * function:
31  *    Subprocess(cmd).wait();
32  * which executes the command using the default shell and waits for it
33  * to complete, returning the exit status.
34  *
35  * A thread-safe version of popen() (type="r", to read from the child):
36  *    Subprocess proc(cmd, Subprocess::Options().stdout(Subprocess::PIPE));
37  *    // read from proc.stdout()
38  *    proc.wait();
39  *
40  * A thread-safe version of popen() (type="w", to write from the child):
41  *    Subprocess proc(cmd, Subprocess::Options().stdin(Subprocess::PIPE));
42  *    // write to proc.stdin()
43  *    proc.wait();
44  *
45  * If you want to redirect both stdin and stdout to pipes, you can, but
46  * note that you're subject to a variety of deadlocks.  You'll want to use
47  * nonblocking I/O; look at the implementation of communicate() for an example.
48  *
49  * communicate() is a way to communicate to a child via its standard input,
50  * standard output, and standard error.  It buffers everything in memory,
51  * so it's not great for large amounts of data (or long-running processes),
52  * but it insulates you from the deadlocks mentioned above.
53  */
54 #ifndef FOLLY_SUBPROCESS_H_
55 #define FOLLY_SUBPROCESS_H_
56
57 #include <sys/types.h>
58 #include <signal.h>
59 #include <wait.h>
60
61 #include <exception>
62 #include <vector>
63 #include <string>
64
65 #include <boost/container/flat_map.hpp>
66 #include <boost/operators.hpp>
67 #include <boost/noncopyable.hpp>
68
69 #include "folly/experimental/io/IOBufQueue.h"
70 #include "folly/MapUtil.h"
71 #include "folly/Portability.h"
72 #include "folly/Range.h"
73
74 namespace folly {
75
76 /**
77  * Class to wrap a process return code.
78  */
79 class Subprocess;
80 class ProcessReturnCode {
81   friend class Subprocess;
82  public:
83   enum State {
84     NOT_STARTED,
85     RUNNING,
86     EXITED,
87     KILLED
88   };
89
90   /**
91    * Process state.  One of:
92    * NOT_STARTED: process hasn't been started successfully
93    * RUNNING: process is currently running
94    * EXITED: process exited (successfully or not)
95    * KILLED: process was killed by a signal.
96    */
97   State state() const;
98
99   /**
100    * Helper wrappers around state().
101    */
102   bool notStarted() const { return state() == NOT_STARTED; }
103   bool running() const { return state() == RUNNING; }
104   bool exited() const { return state() == EXITED; }
105   bool killed() const { return state() == KILLED; }
106
107   /**
108    * Exit status.  Only valid if state() == EXITED; throws otherwise.
109    */
110   int exitStatus() const;
111
112   /**
113    * Signal that caused the process's termination.  Only valid if
114    * state() == KILLED; throws otherwise.
115    */
116   int killSignal() const;
117
118   /**
119    * Was a core file generated?  Only valid if state() == KILLED; throws
120    * otherwise.
121    */
122   bool coreDumped() const;
123
124   /**
125    * String representation; one of
126    * "not started"
127    * "running"
128    * "exited with status <status>"
129    * "killed by signal <signal>"
130    * "killed by signal <signal> (core dumped)"
131    */
132   std::string str() const;
133
134   /**
135    * Helper function to enforce a precondition based on this.
136    * Throws std::logic_error if in an unexpected state.
137    */
138   void enforce(State state) const;
139  private:
140   explicit ProcessReturnCode(int rv) : rawStatus_(rv) { }
141   static constexpr int RV_NOT_STARTED = -2;
142   static constexpr int RV_RUNNING = -1;
143
144   int rawStatus_;
145 };
146
147 /**
148  * Exception thrown by *Checked methods of Subprocess.
149  */
150 class CalledProcessError : public std::exception {
151  public:
152   explicit CalledProcessError(ProcessReturnCode rc);
153   ~CalledProcessError() throw() { }
154   const char* what() const throw() FOLLY_OVERRIDE { return what_.c_str(); }
155   ProcessReturnCode returnCode() const { return returnCode_; }
156  private:
157   ProcessReturnCode returnCode_;
158   std::string what_;
159 };
160
161 /**
162  * Subprocess.
163  */
164 class Subprocess : private boost::noncopyable {
165  public:
166   static const int CLOSE = -1;
167   static const int PIPE = -2;
168   static const int PIPE_IN = -3;
169   static const int PIPE_OUT = -4;
170
171   /**
172    * Class representing various options: file descriptor behavior, and
173    * whether to use $PATH for searching for the executable,
174    *
175    * By default, we don't use $PATH, file descriptors are closed if
176    * the close-on-exec flag is set (fcntl FD_CLOEXEC) and inherited
177    * otherwise.
178    */
179   class Options {
180     friend class Subprocess;
181    public:
182     Options() : closeOtherFds_(false), usePath_(false) { }
183
184     /**
185      * Change action for file descriptor fd.
186      *
187      * "action" may be another file descriptor number (dup2()ed before the
188      * child execs), or one of CLOSE, PIPE_IN, and PIPE_OUT.
189      *
190      * CLOSE: close the file descriptor in the child
191      * PIPE_IN: open a pipe *from* the child
192      * PIPE_OUT: open a pipe *to* the child
193      *
194      * PIPE is a shortcut; same as PIPE_IN for stdin (fd 0), same as
195      * PIPE_OUT for stdout (fd 1) or stderr (fd 2), and an error for
196      * other file descriptors.
197      */
198     Options& fd(int fd, int action);
199
200     /**
201      * Shortcut to change the action for standard input.
202      */
203     Options& stdin(int action) { return fd(0, action); }
204
205     /**
206      * Shortcut to change the action for standard output.
207      */
208     Options& stdout(int action) { return fd(1, action); }
209
210     /**
211      * Shortcut to change the action for standard error.
212      * Note that stderr(1) will redirect the standard error to the same
213      * file descriptor as standard output; the equivalent of bash's "2>&1"
214      */
215     Options& stderr(int action) { return fd(2, action); }
216
217     /**
218      * Close all other fds (other than standard input, output, error,
219      * and file descriptors explicitly specified with fd()).
220      *
221      * This is potentially slow; it's generally a better idea to
222      * set the close-on-exec flag on all file descriptors that shouldn't
223      * be inherited by the child.
224      *
225      * Even with this option set, standard input, output, and error are
226      * not closed; use stdin(CLOSE), stdout(CLOSE), stderr(CLOSE) if you
227      * desire this.
228      */
229     Options& closeOtherFds() { closeOtherFds_ = true; return *this; }
230
231     /**
232      * Use the search path ($PATH) when searching for the executable.
233      */
234     Options& usePath() { usePath_ = true; return *this; }
235    private:
236     typedef boost::container::flat_map<int, int> FdMap;
237     FdMap fdActions_;
238     bool closeOtherFds_;
239     bool usePath_;
240   };
241
242   /**
243    * Create a subprocess from the given arguments.  argv[0] must be listed.
244    * If not-null, executable must be the actual executable
245    * being used (otherwise it's the same as argv[0]).
246    *
247    * If env is not-null, it must contain name=value strings to be used
248    * as the child's environment; otherwise, we inherit the environment
249    * from the parent.  env must be null if options.usePath is set.
250    */
251   explicit Subprocess(
252       const std::vector<std::string>& argv,
253       const Options& options = Options(),
254       const char* executable = nullptr,
255       const std::vector<std::string>* env = nullptr);
256   ~Subprocess();
257
258   /**
259    * Create a subprocess run as a shell command (as shell -c 'command')
260    *
261    * The shell to use is taken from the environment variable $SHELL,
262    * or /bin/sh if $SHELL is unset.
263    */
264   explicit Subprocess(
265       const std::string& cmd,
266       const Options& options = Options(),
267       const std::vector<std::string>* env = nullptr);
268
269   /**
270    * Append all data, close the stdin (to-child) fd, and read all data,
271    * except that this is done in a safe manner to prevent deadlocking.
272    *
273    * If WRITE_STDIN is given in flags, the process must have been opened with
274    * stdinFd=PIPE.
275    *
276    * If READ_STDOUT is given in flags, the first returned value will be the
277    * value read from the child's stdout; the child must have been opened with
278    * stdoutFd=PIPE.
279    *
280    * If READ_STDERR is given in flags, the second returned value will be the
281    * value read from the child's stderr; the child must have been opened with
282    * stderrFd=PIPE.
283    *
284    * Note that communicate() returns when all pipes to/from the child are
285    * closed; the child might stay alive after that, so you must still wait().
286    *
287    * communicateIOBuf uses IOBufQueue for buffering (which has the advantage
288    * that it won't try to allocate all data at once).  communicate
289    * uses strings for simplicity.
290    */
291   enum {
292     WRITE_STDIN = 1 << 0,
293     READ_STDOUT = 1 << 1,
294     READ_STDERR = 1 << 2,
295   };
296   std::pair<IOBufQueue, IOBufQueue> communicateIOBuf(
297       int flags = READ_STDOUT,
298       IOBufQueue data = IOBufQueue());
299
300   std::pair<std::string, std::string> communicate(
301       int flags = READ_STDOUT,
302       StringPiece data = StringPiece());
303
304   /**
305    * Communicate with the child until all pipes to/from the child are closed.
306    *
307    * readCallback(pfd, cfd) will be called whenever there's data available
308    * on any pipe *from* the child (PIPE_OUT).  pfd is the file descriptor
309    * in the parent (that you use to read from); cfd is the file descriptor
310    * in the child (used for identifying the stream; 1 = child's standard
311    * output, 2 = child's standard error, etc)
312    *
313    * writeCallback(pfd, cfd) will be called whenever a pipe *to* the child is
314    * writable (PIPE_IN).  pfd is the file descriptor in the parent (that you
315    * use to write to); cfd is the file descriptor in the child (used for
316    * identifying the stream; 0 = child's standard input, etc)
317    *
318    * The read and write callbacks must read from / write to pfd and return
319    * false during normal operation or true at end-of-file;
320    * communicate() will then close the pipe.  Note that pfd is
321    * nonblocking, so be prepared for read() / write() to return -1 and
322    * set errno to EAGAIN (in which case you should return false).
323    *
324    * NOTE that you MUST consume all data passed to readCallback (or return
325    * true, which will close the pipe, possibly sending SIGPIPE to the child or
326    * making its writes fail with EPIPE), and you MUST write to a writable pipe
327    * (or return true, which will close the pipe).  To do otherwise is an
328    * error.  You must do this even for pipes you are not interested in.
329    *
330    * Note that communicate() returns when all pipes to/from the child are
331    * closed; the child might stay alive after that, so you must still wait().
332    *
333    * Most users won't need to use this; the simpler version of communicate
334    * (which buffers data in memory) will probably work fine.
335    */
336   typedef std::function<bool(int, int)> FdCallback;
337   void communicate(FdCallback readCallback, FdCallback writeCallback);
338
339   /**
340    * Return the child's pid, or -1 if the child wasn't successfully spawned
341    * or has already been wait()ed upon.
342    */
343   pid_t pid() const;
344
345   /**
346    * Return the child's status (as per wait()) if the process has already
347    * been waited on, -1 if the process is still running, or -2 if the process
348    * hasn't been successfully started.  NOTE that this does not poll, but
349    * returns the status stored in the Subprocess object.
350    */
351   ProcessReturnCode returnCode() const { return returnCode_; }
352
353   /**
354    * Poll the child's status and return it, return -1 if the process
355    * is still running.  NOTE that it is illegal to call poll again after
356    * poll indicated that the process has terminated, or to call poll on a
357    * process that hasn't been successfully started (the constructor threw an
358    * exception).
359    */
360   ProcessReturnCode poll();
361
362   /**
363    * Poll the child's status.  If the process is still running, return false.
364    * Otherwise, return true if the process exited with status 0 (success),
365    * or throw CalledProcessError if the process exited with a non-zero status.
366    */
367   bool pollChecked();
368
369   /**
370    * Wait for the process to terminate and return its status.
371    * Similarly to poll, it is illegal to call wait after the process
372    * has already been reaped or if the process has not successfully started.
373    */
374   ProcessReturnCode wait();
375
376   /**
377    * Wait for the process to terminate, throw if unsuccessful.
378    */
379   void waitChecked();
380
381   /**
382    * Set all pipes from / to child non-blocking.  communicate() does
383    * this for you.
384    */
385   void setAllNonBlocking();
386
387   /**
388    * Get parent file descriptor corresponding to the given file descriptor
389    * in the child.  Throws if childFd isn't a pipe (PIPE_IN / PIPE_OUT).
390    * Do not close() the return file descriptor; use closeParentFd, below.
391    */
392   int parentFd(int childFd) const {
393     return pipes_[findByChildFd(childFd)].parentFd;
394   }
395   int stdin() const { return parentFd(0); }
396   int stdout() const { return parentFd(1); }
397   int stderr() const { return parentFd(2); }
398
399   /**
400    * Close the parent file descriptor given a file descriptor in the child.
401    */
402   void closeParentFd(int childFd);
403
404   /**
405    * Send a signal to the child.  Shortcuts for the commonly used Unix
406    * signals are below.
407    */
408   void sendSignal(int signal);
409   void terminate() { sendSignal(SIGTERM); }
410   void kill() { sendSignal(SIGKILL); }
411
412  private:
413   static const int RV_RUNNING = ProcessReturnCode::RV_RUNNING;
414   static const int RV_NOT_STARTED = ProcessReturnCode::RV_NOT_STARTED;
415
416   void spawn(
417       std::unique_ptr<const char*[]> argv,
418       const char* executable,
419       const Options& options,
420       const std::vector<std::string>* env);
421
422   // Action to run in child.
423   // Note that this runs after vfork(), so tread lightly.
424   void runChild(const char* executable, char** argv, char** env,
425                 const Options& options) const;
426
427   /**
428    * Close all file descriptors.
429    */
430   void closeAll();
431
432   // return index in pipes_
433   int findByChildFd(int childFd) const;
434
435   pid_t pid_;
436   ProcessReturnCode returnCode_;
437
438   // The number of pipes between parent and child is assumed to be small,
439   // so we're happy with a vector here, even if it means linear erase.
440   // sorted by childFd
441   struct PipeInfo : private boost::totally_ordered<PipeInfo> {
442     int parentFd;
443     int childFd;
444     int direction;  // one of PIPE_IN / PIPE_OUT
445     bool operator<(const PipeInfo& other) const {
446       return childFd < other.childFd;
447     }
448     bool operator==(const PipeInfo& other) const {
449       return childFd == other.childFd;
450     }
451   };
452   std::vector<PipeInfo> pipes_;
453 };
454
455 }  // namespace folly
456
457 #endif /* FOLLY_SUBPROCESS_H_ */
458