Special-case /dev/null in open in the portability header
[folly.git] / folly / Subprocess.h
1 /*
2  * Copyright 2016 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 [1] 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 [1] version of popen() (type="r", to read from the child):
36  *    Subprocess proc(cmd, Subprocess::pipeStdout());
37  *    // read from proc.stdout()
38  *    proc.wait();
39  *
40  * A thread-safe [1] version of popen() (type="w", to write to the child):
41  *    Subprocess proc(cmd, Subprocess::pipeStdin());
42  *    // write to proc.stdin()
43  *    proc.wait();
44  *
45  * If you want to redirect both stdin and stdout to pipes, you can, but note
46  * that you're subject to a variety of deadlocks.  You'll want to use
47  * nonblocking I/O, like the callback version of communicate().
48  *
49  * The string or IOBuf-based variants of communicate() are the simplest way
50  * to communicate with a child via its standard input, standard output, and
51  * standard error.  They buffer everything in memory, so they are not great
52  * for large amounts of data (or long-running processes), but they are much
53  * simpler than the callback version.
54  *
55  * == A note on thread-safety ==
56  *
57  * [1] "thread-safe" refers ONLY to the fact that Subprocess is very careful
58  * to fork in a way that does not cause grief in multithreaded programs.
59  *
60  * Caveat: If your system does not have the atomic pipe2 system call, it is
61  * not safe to concurrently call Subprocess from different threads.
62  * Therefore, it is best to have a single thread be responsible for spawning
63  * subprocesses.
64  *
65  * A particular instances of Subprocess is emphatically **not** thread-safe.
66  * If you need to simultaneously communicate via the pipes, and interact
67  * with the Subprocess state, your best bet is to:
68  *  - takeOwnershipOfPipes() to separate the pipe I/O from the subprocess.
69  *  - Only interact with the Subprocess from one thread at a time.
70  *
71  * The current implementation of communicate() cannot be safely interrupted.
72  * To do so correctly, one would need to use EventFD, or open a dedicated
73  * pipe to be messaged from a different thread -- in particular, kill() will
74  * not do, since a descendant may keep the pipes open indefinitely.
75  *
76  * So, once you call communicate(), you must wait for it to return, and not
77  * touch the pipes from other threads.  closeParentFd() is emphatically
78  * unsafe to call concurrently, and even sendSignal() is not a good idea.
79  * You can perhaps give the Subprocess's PID to a different thread before
80  * starting communicate(), and use that PID to send a signal without
81  * accessing the Subprocess object.  In that case, you will need a mutex
82  * that ensures you don't wait() before you sent said signal.  In a
83  * nutshell, don't do this.
84  *
85  * In fact, signals are inherently concurrency-unsafe on Unix: if you signal
86  * a PID, while another thread is in waitpid(), the signal may fire either
87  * before or after the process is reaped.  This means that your signal can,
88  * in pathological circumstances, be delivered to the wrong process (ouch!).
89  * To avoid this, you should only use non-blocking waits (i.e. poll()), and
90  * make sure to serialize your signals (i.e. kill()) with the waits --
91  * either wait & signal from the same thread, or use a mutex.
92  */
93
94 #pragma once
95
96 #include <sys/types.h>
97 #include <signal.h>
98 #if __APPLE__
99 #include <sys/wait.h>
100 #else
101 #include <wait.h>
102 #endif
103
104 #include <exception>
105 #include <vector>
106 #include <string>
107
108 #include <boost/container/flat_map.hpp>
109 #include <boost/operators.hpp>
110
111 #include <folly/Exception.h>
112 #include <folly/File.h>
113 #include <folly/FileUtil.h>
114 #include <folly/Function.h>
115 #include <folly/gen/String.h>
116 #include <folly/io/IOBufQueue.h>
117 #include <folly/MapUtil.h>
118 #include <folly/Portability.h>
119 #include <folly/Range.h>
120
121 namespace folly {
122
123 /**
124  * Class to wrap a process return code.
125  */
126 class Subprocess;
127 class ProcessReturnCode {
128   friend class Subprocess;
129  public:
130   enum State {
131     // Subprocess starts in the constructor, so this state designates only
132     // default-initialized or moved-out ProcessReturnCodes.
133     NOT_STARTED,
134     RUNNING,
135     EXITED,
136     KILLED
137   };
138
139   // Default-initialized for convenience. Subprocess::returnCode() will
140   // never produce this value.
141   ProcessReturnCode() : ProcessReturnCode(RV_NOT_STARTED) {}
142
143   // Trivially copyable
144   ProcessReturnCode(const ProcessReturnCode& p) = default;
145   ProcessReturnCode& operator=(const ProcessReturnCode& p) = default;
146   // Non-default move: In order for Subprocess to be movable, the "moved
147   // out" state must not be "running", or ~Subprocess() will abort.
148   ProcessReturnCode(ProcessReturnCode&& p) noexcept;
149   ProcessReturnCode& operator=(ProcessReturnCode&& p) noexcept;
150
151   /**
152    * Process state.  One of:
153    * NOT_STARTED: process hasn't been started successfully
154    * RUNNING: process is currently running
155    * EXITED: process exited (successfully or not)
156    * KILLED: process was killed by a signal.
157    */
158   State state() const;
159
160   /**
161    * Helper wrappers around state().
162    */
163   bool notStarted() const { return state() == NOT_STARTED; }
164   bool running() const { return state() == RUNNING; }
165   bool exited() const { return state() == EXITED; }
166   bool killed() const { return state() == KILLED; }
167
168   /**
169    * Exit status.  Only valid if state() == EXITED; throws otherwise.
170    */
171   int exitStatus() const;
172
173   /**
174    * Signal that caused the process's termination.  Only valid if
175    * state() == KILLED; throws otherwise.
176    */
177   int killSignal() const;
178
179   /**
180    * Was a core file generated?  Only valid if state() == KILLED; throws
181    * otherwise.
182    */
183   bool coreDumped() const;
184
185   /**
186    * String representation; one of
187    * "not started"
188    * "running"
189    * "exited with status <status>"
190    * "killed by signal <signal>"
191    * "killed by signal <signal> (core dumped)"
192    */
193   std::string str() const;
194
195   /**
196    * Helper function to enforce a precondition based on this.
197    * Throws std::logic_error if in an unexpected state.
198    */
199   void enforce(State state) const;
200  private:
201   explicit ProcessReturnCode(int rv) : rawStatus_(rv) { }
202   static constexpr int RV_NOT_STARTED = -2;
203   static constexpr int RV_RUNNING = -1;
204
205   int rawStatus_;
206 };
207
208 /**
209  * Base exception thrown by the Subprocess methods.
210  */
211 class SubprocessError : public std::exception {};
212
213 /**
214  * Exception thrown by *Checked methods of Subprocess.
215  */
216 class CalledProcessError : public SubprocessError {
217  public:
218   explicit CalledProcessError(ProcessReturnCode rc);
219   ~CalledProcessError() throw() = default;
220   const char* what() const throw() override { return what_.c_str(); }
221   ProcessReturnCode returnCode() const { return returnCode_; }
222  private:
223   ProcessReturnCode returnCode_;
224   std::string what_;
225 };
226
227 /**
228  * Exception thrown if the subprocess cannot be started.
229  */
230 class SubprocessSpawnError : public SubprocessError {
231  public:
232   SubprocessSpawnError(const char* executable, int errCode, int errnoValue);
233   ~SubprocessSpawnError() throw() = default;
234   const char* what() const throw() override { return what_.c_str(); }
235   int errnoValue() const { return errnoValue_; }
236
237  private:
238   int errnoValue_;
239   std::string what_;
240 };
241
242 /**
243  * Subprocess.
244  */
245 class Subprocess {
246  public:
247   static const int CLOSE = -1;
248   static const int PIPE = -2;
249   static const int PIPE_IN = -3;
250   static const int PIPE_OUT = -4;
251
252   /**
253    * See Subprocess::Options::dangerousPostForkPreExecCallback() for usage.
254    * Every derived class should include the following warning:
255    *
256    * DANGER: This class runs after fork in a child processes. Be fast, the
257    * parent thread is waiting, but remember that other parent threads are
258    * running and may mutate your state.  Avoid mutating any data belonging to
259    * the parent.  Avoid interacting with non-POD data that originated in the
260    * parent.  Avoid any libraries that may internally reference non-POD data.
261    * Especially beware parent mutexes -- for example, glog's LOG() uses one.
262    */
263   struct DangerousPostForkPreExecCallback {
264     virtual ~DangerousPostForkPreExecCallback() {}
265     // This must return 0 on success, or an `errno` error code.
266     virtual int operator()() = 0;
267   };
268
269   /**
270    * Class representing various options: file descriptor behavior, and
271    * whether to use $PATH for searching for the executable,
272    *
273    * By default, we don't use $PATH, file descriptors are closed if
274    * the close-on-exec flag is set (fcntl FD_CLOEXEC) and inherited
275    * otherwise.
276    */
277   class Options : private boost::orable<Options> {
278     friend class Subprocess;
279    public:
280     Options() {}  // E.g. https://gcc.gnu.org/bugzilla/show_bug.cgi?id=58328
281
282     /**
283      * Change action for file descriptor fd.
284      *
285      * "action" may be another file descriptor number (dup2()ed before the
286      * child execs), or one of CLOSE, PIPE_IN, and PIPE_OUT.
287      *
288      * CLOSE: close the file descriptor in the child
289      * PIPE_IN: open a pipe *from* the child
290      * PIPE_OUT: open a pipe *to* the child
291      *
292      * PIPE is a shortcut; same as PIPE_IN for stdin (fd 0), same as
293      * PIPE_OUT for stdout (fd 1) or stderr (fd 2), and an error for
294      * other file descriptors.
295      */
296     Options& fd(int fd, int action);
297
298     /**
299      * Shortcut to change the action for standard input.
300      */
301     Options& stdin(int action) { return fd(STDIN_FILENO, action); }
302
303     /**
304      * Shortcut to change the action for standard output.
305      */
306     Options& stdout(int action) { return fd(STDOUT_FILENO, action); }
307
308     /**
309      * Shortcut to change the action for standard error.
310      * Note that stderr(1) will redirect the standard error to the same
311      * file descriptor as standard output; the equivalent of bash's "2>&1"
312      */
313     Options& stderr(int action) { return fd(STDERR_FILENO, action); }
314
315     Options& pipeStdin() { return fd(STDIN_FILENO, PIPE_IN); }
316     Options& pipeStdout() { return fd(STDOUT_FILENO, PIPE_OUT); }
317     Options& pipeStderr() { return fd(STDERR_FILENO, PIPE_OUT); }
318
319     /**
320      * Close all other fds (other than standard input, output, error,
321      * and file descriptors explicitly specified with fd()).
322      *
323      * This is potentially slow; it's generally a better idea to
324      * set the close-on-exec flag on all file descriptors that shouldn't
325      * be inherited by the child.
326      *
327      * Even with this option set, standard input, output, and error are
328      * not closed; use stdin(CLOSE), stdout(CLOSE), stderr(CLOSE) if you
329      * desire this.
330      */
331     Options& closeOtherFds() { closeOtherFds_ = true; return *this; }
332
333     /**
334      * Use the search path ($PATH) when searching for the executable.
335      */
336     Options& usePath() { usePath_ = true; return *this; }
337
338     /**
339      * Change the child's working directory, after the vfork.
340      */
341     Options& chdir(const std::string& dir) { childDir_ = dir; return *this; }
342
343 #if __linux__
344     /**
345      * Child will receive a signal when the parent exits.
346      */
347     Options& parentDeathSignal(int sig) {
348       parentDeathSignal_ = sig;
349       return *this;
350     }
351 #endif
352
353     /**
354      * Child will be made a process group leader when it starts. Upside: one
355      * can reliably all its kill non-daemonizing descendants.  Downside: the
356      * child will not receive Ctrl-C etc during interactive use.
357      */
358     Options& processGroupLeader() {
359       processGroupLeader_ = true;
360       return *this;
361     }
362
363     /**
364      * *** READ THIS WHOLE DOCBLOCK BEFORE USING ***
365      *
366      * Run this callback in the child after the fork, just before the
367      * exec(), and after the child's state has been completely set up:
368      *  - signal handlers have been reset to default handling and unblocked
369      *  - the working directory was set
370      *  - closed any file descriptors specified via Options()
371      *  - set child process flags (see code)
372      *
373      * This is EXTREMELY DANGEROUS. For example, this innocuous-looking code
374      * can cause a fraction of your Subprocess launches to hang forever:
375      *
376      *   LOG(INFO) << "Hello from the child";
377      *
378      * The reason is that glog has an internal mutex. If your fork() happens
379      * when the parent has the mutex locked, the child will wait forever.
380      *
381      * == GUIDELINES ==
382      *
383      * - Be quick -- the parent thread is blocked until you exit.
384      * - Remember that other parent threads are running, and may mutate your
385      *   state.
386      * - Avoid mutating any data belonging to the parent.
387      * - Avoid interacting with non-POD data that came from the parent.
388      * - Avoid any libraries that may internally reference non-POD state.
389      * - Especially beware parent mutexes, e.g. LOG() uses a global mutex.
390      * - Avoid invoking the parent's destructors (you can accidentally
391      *   delete files, terminate network connections, etc).
392      * - Read http://ewontfix.com/7/
393      */
394     Options& dangerousPostForkPreExecCallback(
395         DangerousPostForkPreExecCallback* cob) {
396       dangerousPostForkPreExecCallback_ = cob;
397       return *this;
398     }
399
400     /**
401      * Helpful way to combine Options.
402      */
403     Options& operator|=(const Options& other);
404
405    private:
406     typedef boost::container::flat_map<int, int> FdMap;
407     FdMap fdActions_;
408     bool closeOtherFds_{false};
409     bool usePath_{false};
410     std::string childDir_;  // "" keeps the parent's working directory
411 #if __linux__
412     int parentDeathSignal_{0};
413 #endif
414     bool processGroupLeader_{false};
415     DangerousPostForkPreExecCallback*
416       dangerousPostForkPreExecCallback_{nullptr};
417   };
418
419   static Options pipeStdin() { return Options().stdin(PIPE); }
420   static Options pipeStdout() { return Options().stdout(PIPE); }
421   static Options pipeStderr() { return Options().stderr(PIPE); }
422
423   // Non-copiable, but movable
424   Subprocess(const Subprocess&) = delete;
425   Subprocess& operator=(const Subprocess&) = delete;
426   Subprocess(Subprocess&&) = default;
427   Subprocess& operator=(Subprocess&&) = default;
428
429   /**
430    * Create an uninitialized subprocess.
431    *
432    * In this state it can only be destroyed, or assigned to using the move
433    * assignment operator.
434    */
435   Subprocess();
436
437   /**
438    * Create a subprocess from the given arguments.  argv[0] must be listed.
439    * If not-null, executable must be the actual executable
440    * being used (otherwise it's the same as argv[0]).
441    *
442    * If env is not-null, it must contain name=value strings to be used
443    * as the child's environment; otherwise, we inherit the environment
444    * from the parent.  env must be null if options.usePath is set.
445    */
446   explicit Subprocess(
447       const std::vector<std::string>& argv,
448       const Options& options = Options(),
449       const char* executable = nullptr,
450       const std::vector<std::string>* env = nullptr);
451   ~Subprocess();
452
453   /**
454    * Create a subprocess run as a shell command (as shell -c 'command')
455    *
456    * The shell to use is taken from the environment variable $SHELL,
457    * or /bin/sh if $SHELL is unset.
458    */
459   explicit Subprocess(
460       const std::string& cmd,
461       const Options& options = Options(),
462       const std::vector<std::string>* env = nullptr);
463
464   ////
465   //// The methods below only manipulate the process state, and do not
466   //// affect its communication pipes.
467   ////
468
469   /**
470    * Return the child's pid, or -1 if the child wasn't successfully spawned
471    * or has already been wait()ed upon.
472    */
473   pid_t pid() const;
474
475   /**
476    * Return the child's status (as per wait()) if the process has already
477    * been waited on, -1 if the process is still running, or -2 if the
478    * process hasn't been successfully started.  NOTE that this does not call
479    * waitpid() or Subprocess::poll(), but simply returns the status stored
480    * in the Subprocess object.
481    */
482   ProcessReturnCode returnCode() const { return returnCode_; }
483
484   /**
485    * Poll the child's status and return it. Return the exit status if the
486    * subprocess had quit, or RUNNING otherwise.  Throws an std::logic_error
487    * if called on a Subprocess whose status is no longer RUNNING.  No other
488    * exceptions are possible.  Aborts on egregious violations of contract,
489    * e.g. if you wait for the underlying process without going through this
490    * Subprocess instance.
491    */
492   ProcessReturnCode poll();
493
494   /**
495    * Poll the child's status.  If the process is still running, return false.
496    * Otherwise, return true if the process exited with status 0 (success),
497    * or throw CalledProcessError if the process exited with a non-zero status.
498    */
499   bool pollChecked();
500
501   /**
502    * Wait for the process to terminate and return its status.  Like poll(),
503    * the only exception this can throw is std::logic_error if you call this
504    * on a Subprocess whose status is RUNNING.  Aborts on egregious
505    * violations of contract, like an out-of-band waitpid(p.pid(), 0, 0).
506    */
507   ProcessReturnCode wait();
508
509   /**
510    * Wait for the process to terminate, throw if unsuccessful.
511    */
512   void waitChecked();
513
514   /**
515    * Send a signal to the child.  Shortcuts for the commonly used Unix
516    * signals are below.
517    */
518   void sendSignal(int signal);
519   void terminate() { sendSignal(SIGTERM); }
520   void kill() { sendSignal(SIGKILL); }
521
522   ////
523   //// The methods below only affect the process's communication pipes, but
524   //// not its return code or state (they do not poll() or wait()).
525   ////
526
527   /**
528    * Communicate with the child until all pipes to/from the child are closed.
529    *
530    * The input buffer is written to the process' stdin pipe, and data is read
531    * from the stdout and stderr pipes.  Non-blocking I/O is performed on all
532    * pipes simultaneously to avoid deadlocks.
533    *
534    * The stdin pipe will be closed after the full input buffer has been written.
535    * An error will be thrown if a non-empty input buffer is supplied but stdin
536    * was not configured as a pipe.
537    *
538    * Returns a pair of buffers containing the data read from stdout and stderr.
539    * If stdout or stderr is not a pipe, an empty IOBuf queue will be returned
540    * for the respective buffer.
541    *
542    * Note that communicate() and communicateIOBuf() both return when all
543    * pipes to/from the child are closed; the child might stay alive after
544    * that, so you must still wait().
545    *
546    * communicateIOBuf() uses IOBufQueue for buffering (which has the
547    * advantage that it won't try to allocate all data at once), but it does
548    * store the subprocess's entire output in memory before returning.
549    *
550    * communicate() uses strings for simplicity.
551    */
552   std::pair<IOBufQueue, IOBufQueue> communicateIOBuf(
553       IOBufQueue input = IOBufQueue());
554
555   std::pair<std::string, std::string> communicate(
556       StringPiece input = StringPiece());
557
558   /**
559    * Communicate with the child until all pipes to/from the child are closed.
560    *
561    * == Semantics ==
562    *
563    * readCallback(pfd, cfd) will be called whenever there's data available
564    * on any pipe *from* the child (PIPE_OUT).  pfd is the file descriptor
565    * in the parent (that you use to read from); cfd is the file descriptor
566    * in the child (used for identifying the stream; 1 = child's standard
567    * output, 2 = child's standard error, etc)
568    *
569    * writeCallback(pfd, cfd) will be called whenever a pipe *to* the child is
570    * writable (PIPE_IN).  pfd is the file descriptor in the parent (that you
571    * use to write to); cfd is the file descriptor in the child (used for
572    * identifying the stream; 0 = child's standard input, etc)
573    *
574    * The read and write callbacks must read from / write to pfd and return
575    * false during normal operation.  Return true to tell communicate() to
576    * close the pipe.  For readCallback, this might send SIGPIPE to the
577    * child, or make its writes fail with EPIPE, so you should generally
578    * avoid returning true unless you've reached end-of-file.
579    *
580    * communicate() returns when all pipes to/from the child are closed; the
581    * child might stay alive after that, so you must still wait().
582    * Conversely, the child may quit long before its pipes are closed, since
583    * its descendants can keep them alive forever.
584    *
585    * Most users won't need to use this callback version; the simpler version
586    * of communicate (which buffers data in memory) will probably work fine.
587    *
588    * == Things you must get correct ==
589    *
590    * 1) You MUST consume all data passed to readCallback (or return true to
591    * close the pipe).  Similarly, you MUST write to a writable pipe (or
592    * return true to close the pipe).  To do otherwise is an error that can
593    * result in a deadlock.  You must do this even for pipes you are not
594    * interested in.
595    *
596    * 2) pfd is nonblocking, so be prepared for read() / write() to return -1
597    * and set errno to EAGAIN (in which case you should return false).  Use
598    * readNoInt() from FileUtil.h to handle interrupted reads for you.
599    *
600    * 3) Your callbacks MUST NOT call any of the Subprocess methods that
601    * manipulate the pipe FDs.  Check the docblocks, but, for example,
602    * neither closeParentFd (return true instead) nor takeOwnershipOfPipes
603    * are safe.  Stick to reading/writing from pfd, as appropriate.
604    *
605    * == Good to know ==
606    *
607    * 1) See ReadLinesCallback for an easy way to consume the child's output
608    * streams line-by-line (or tokenized by another delimiter).
609    *
610    * 2) "Wait until the descendants close the pipes" is usually the behavior
611    * you want, since the descendants may have something to say even if the
612    * immediate child is dead.  If you need to be able to force-close all
613    * parent FDs, communicate() will NOT work for you.  Do it your own way by
614    * using takeOwnershipOfPipes().
615    *
616    * Why not? You can return "true" from your callbacks to sever active
617    * pipes, but inactive ones can remain open indefinitely.  It is
618    * impossible to safely close inactive pipes while another thread is
619    * blocked in communicate().  This is BY DESIGN.  Racing communicate()'s
620    * read/write callbacks can result in wrong I/O and data corruption.  This
621    * class would need internal synchronization and timeouts, a poor and
622    * expensive implementation choice, in order to make closeParentFd()
623    * thread-safe.
624    */
625   using FdCallback = folly::Function<bool(int, int)>;
626   void communicate(FdCallback readCallback, FdCallback writeCallback);
627
628   /**
629    * A readCallback for Subprocess::communicate() that helps you consume
630    * lines (or other delimited pieces) from your subprocess's file
631    * descriptors.  Use the readLinesCallback() helper to get template
632    * deduction.  For example:
633    *
634    *   subprocess.communicate(
635    *     Subprocess::readLinesCallback(
636    *       [](int fd, folly::StringPiece s) {
637    *         std::cout << fd << " said: " << s;
638    *         return false;  // Keep reading from the child
639    *       }
640    *     ),
641    *     [](int pdf, int cfd){ return true; }  // Don't write to the child
642    *   );
643    *
644    * If a file line exceeds maxLineLength, your callback will get some
645    * initial chunks of maxLineLength with no trailing delimiters.  The final
646    * chunk of a line is delimiter-terminated iff the delimiter was present
647    * in the input.  In particular, the last line in a file always lacks a
648    * delimiter -- so if a file ends on a delimiter, the final line is empty.
649    *
650    * Like a regular communicate() callback, your fdLineCb() normally returns
651    * false.  It may return true to tell Subprocess to close the underlying
652    * file descriptor.  The child process may then receive SIGPIPE or get
653    * EPIPE errors on writes.
654    */
655   template <class Callback>
656   class ReadLinesCallback {
657    private:
658     // Binds an FD to the client-provided FD+line callback
659     struct StreamSplitterCallback {
660       StreamSplitterCallback(Callback& cb, int fd) : cb_(cb), fd_(fd) { }
661       // The return value semantics are inverted vs StreamSplitter
662       bool operator()(StringPiece s) { return !cb_(fd_, s); }
663       Callback& cb_;
664       int fd_;
665     };
666     typedef gen::StreamSplitter<StreamSplitterCallback> LineSplitter;
667    public:
668     explicit ReadLinesCallback(
669       Callback&& fdLineCb,
670       uint64_t maxLineLength = 0,  // No line length limit by default
671       char delimiter = '\n',
672       uint64_t bufSize = 1024
673     ) : fdLineCb_(std::forward<Callback>(fdLineCb)),
674         maxLineLength_(maxLineLength),
675         delimiter_(delimiter),
676         bufSize_(bufSize) {}
677
678     bool operator()(int pfd, int cfd) {
679       // Make a splitter for this cfd if it doesn't already exist
680       auto it = fdToSplitter_.find(cfd);
681       auto& splitter = (it != fdToSplitter_.end()) ? it->second
682         : fdToSplitter_.emplace(cfd, LineSplitter(
683             delimiter_, StreamSplitterCallback(fdLineCb_, cfd), maxLineLength_
684           )).first->second;
685       // Read as much as we can from this FD
686       char buf[bufSize_];
687       while (true) {
688         ssize_t ret = readNoInt(pfd, buf, bufSize_);
689         if (ret == -1 && errno == EAGAIN) {  // No more data for now
690           return false;
691         }
692         checkUnixError(ret, "read");
693         if (ret == 0) {  // Reached end-of-file
694           splitter.flush();  // Ignore return since the file is over anyway
695           return true;
696         }
697         if (!splitter(StringPiece(buf, ret))) {
698           return true;  // The callback told us to stop
699         }
700       }
701     }
702
703    private:
704     Callback fdLineCb_;
705     const uint64_t maxLineLength_;
706     const char delimiter_;
707     const uint64_t bufSize_;
708     // We lazily make splitters for all cfds that get used.
709     std::unordered_map<int, LineSplitter> fdToSplitter_;
710   };
711
712   // Helper to enable template deduction
713   template <class Callback>
714   static auto readLinesCallback(
715       Callback&& fdLineCb,
716       uint64_t maxLineLength = 0, // No line length limit by default
717       char delimiter = '\n',
718       uint64_t bufSize = 1024)
719       -> ReadLinesCallback<typename std::decay<Callback>::type> {
720     return ReadLinesCallback<typename std::decay<Callback>::type>(
721         std::forward<Callback>(fdLineCb), maxLineLength, delimiter, bufSize);
722   }
723
724   /**
725    * communicate() callbacks can use this to temporarily enable/disable
726    * notifications (callbacks) for a pipe to/from the child.  By default,
727    * all are enabled.  Useful for "chatty" communication -- you want to
728    * disable write callbacks until you receive the expected message.
729    *
730    * Disabling a pipe does not free you from the requirement to consume all
731    * incoming data.  Failing to do so will easily create deadlock bugs.
732    *
733    * Throws if the childFd is not known.
734    */
735   void enableNotifications(int childFd, bool enabled);
736
737   /**
738    * Are notifications for one pipe to/from child enabled?  Throws if the
739    * childFd is not known.
740    */
741   bool notificationsEnabled(int childFd) const;
742
743   ////
744   //// The following methods are meant for the cases when communicate() is
745   //// not suitable.  You should not need them when you call communicate(),
746   //// and, in fact, it is INHERENTLY UNSAFE to use closeParentFd() or
747   //// takeOwnershipOfPipes() from a communicate() callback.
748   ////
749
750   /**
751    * Close the parent file descriptor given a file descriptor in the child.
752    * DO NOT USE from communicate() callbacks; make them return true instead.
753    */
754   void closeParentFd(int childFd);
755
756   /**
757    * Set all pipes from / to child to be non-blocking.  communicate() does
758    * this for you.
759    */
760   void setAllNonBlocking();
761
762   /**
763    * Get parent file descriptor corresponding to the given file descriptor
764    * in the child.  Throws if childFd isn't a pipe (PIPE_IN / PIPE_OUT).
765    * Do not close() the returned file descriptor; use closeParentFd, above.
766    */
767   int parentFd(int childFd) const {
768     return pipes_[findByChildFd(childFd)].pipe.fd();
769   }
770   int stdin() const { return parentFd(0); }
771   int stdout() const { return parentFd(1); }
772   int stderr() const { return parentFd(2); }
773
774   /**
775    * The child's pipes are logically separate from the process metadata
776    * (they may even be kept alive by the child's descendants).  This call
777    * lets you manage the pipes' lifetime separetely from the lifetime of the
778    * child process.
779    *
780    * After this call, the Subprocess instance will have no knowledge of
781    * these pipes, and the caller assumes responsibility for managing their
782    * lifetimes.  Pro-tip: prefer to explicitly close() the pipes, since
783    * folly::File would otherwise silently suppress I/O errors.
784    *
785    * No, you may NOT call this from a communicate() callback.
786    */
787   struct ChildPipe {
788     ChildPipe(int fd, folly::File&& ppe) : childFd(fd), pipe(std::move(ppe)) {}
789     int childFd;
790     folly::File pipe;  // Owns the parent FD
791   };
792   std::vector<ChildPipe> takeOwnershipOfPipes();
793
794  private:
795   static const int RV_RUNNING = ProcessReturnCode::RV_RUNNING;
796   static const int RV_NOT_STARTED = ProcessReturnCode::RV_NOT_STARTED;
797
798   // spawn() sets up a pipe to read errors from the child,
799   // then calls spawnInternal() to do the bulk of the work.  Once
800   // spawnInternal() returns it reads the error pipe to see if the child
801   // encountered any errors.
802   void spawn(
803       std::unique_ptr<const char*[]> argv,
804       const char* executable,
805       const Options& options,
806       const std::vector<std::string>* env);
807   void spawnInternal(
808       std::unique_ptr<const char*[]> argv,
809       const char* executable,
810       Options& options,
811       const std::vector<std::string>* env,
812       int errFd);
813
814   // Actions to run in child.
815   // Note that this runs after vfork(), so tread lightly.
816   // Returns 0 on success, or an errno value on failure.
817   int prepareChild(const Options& options,
818                    const sigset_t* sigmask,
819                    const char* childDir) const;
820   int runChild(const char* executable, char** argv, char** env,
821                const Options& options) const;
822
823   /**
824    * Read from the error pipe, and throw SubprocessSpawnError if the child
825    * failed before calling exec().
826    */
827   void readChildErrorPipe(int pfd, const char* executable);
828
829   // Returns an index into pipes_. Throws std::invalid_argument if not found.
830   size_t findByChildFd(const int childFd) const;
831
832   pid_t pid_{-1};
833   ProcessReturnCode returnCode_{RV_NOT_STARTED};
834
835   /**
836    * Represents a pipe between this process, and the child process (or its
837    * descendant).  To interact with these pipes, you can use communicate(),
838    * or use parentFd() and related methods, or separate them from the
839    * Subprocess instance entirely via takeOwnershipOfPipes().
840    */
841   struct Pipe : private boost::totally_ordered<Pipe> {
842     folly::File pipe; // Our end of the pipe, wrapped in a File to auto-close.
843     int childFd = -1; // Identifies the pipe: what FD is this in the child?
844     int direction = PIPE_IN; // one of PIPE_IN / PIPE_OUT
845     bool enabled = true; // Are notifications enabled in communicate()?
846
847     bool operator<(const Pipe& other) const {
848       return childFd < other.childFd;
849     }
850     bool operator==(const Pipe& other) const {
851       return childFd == other.childFd;
852     }
853   };
854
855   // Populated at process start according to fdActions, empty after
856   // takeOwnershipOfPipes().  Sorted by childFd.  Can only have elements
857   // erased, but not inserted, after being populated.
858   //
859   // The number of pipes between parent and child is assumed to be small,
860   // so we're happy with a vector here, even if it means linear erase.
861   std::vector<Pipe> pipes_;
862 };
863
864 inline Subprocess::Options& Subprocess::Options::operator|=(
865     const Subprocess::Options& other) {
866   if (this == &other) return *this;
867   // Replace
868   for (auto& p : other.fdActions_) {
869     fdActions_[p.first] = p.second;
870   }
871   closeOtherFds_ |= other.closeOtherFds_;
872   usePath_ |= other.usePath_;
873   processGroupLeader_ |= other.processGroupLeader_;
874   return *this;
875 }
876
877 }  // namespace folly