folly::Subprocess::Options Class Reference

#include <Subprocess.h>

Public Member Functions
	Options ()
Options &	fd (int fd, int action)
Options &	stdinFd (int action)
Options &	stdoutFd (int action)
Options &	stderrFd (int action)
Options &	pipeStdin ()
Options &	pipeStdout ()
Options &	pipeStderr ()
Options &	closeOtherFds ()
Options &	usePath ()
Options &	chdir (const std::string &dir)
Options &	processGroupLeader ()
Options &	detach ()
Options &	dangerousPostForkPreExecCallback (DangerousPostForkPreExecCallback *cob)

Private Types
typedef boost::container::flat_map< int, int >	FdMap

Private Attributes
FdMap	fdActions_
bool	closeOtherFds_ {false}
bool	usePath_ {false}
bool	processGroupLeader_ {false}
bool	detach_ {false}
std::string	childDir_
DangerousPostForkPreExecCallback *	dangerousPostForkPreExecCallback_

Friends
class	Subprocess

Detailed Description

Class representing various options: file descriptor behavior, and whether to use $PATH for searching for the executable,

By default, we don't use $PATH, file descriptors are closed if the close-on-exec flag is set (fcntl FD_CLOEXEC) and inherited otherwise.

Definition at line 301 of file Subprocess.h.

Member Typedef Documentation

typedef boost::container::flat_map<int, int> folly::Subprocess::Options::FdMap

private

Definition at line 487 of file Subprocess.h.

Constructor & Destructor Documentation

folly::Subprocess::Options::Options ( )

inline

Definition at line 305 of file Subprocess.h.

References upload::action.

{} // E.g. https://gcc.gnu.org/bugzilla/show_bug.cgi?id=58328

Member Function Documentation

Options& folly::Subprocess::Options::chdir ( const std::string &  dir )

inline

Change the child's working directory, after the vfork.

Definition at line 384 of file Subprocess.h.

References folly::sig.

Referenced by TEST().

                                         {
      childDir_ = dir;
      return *this;
    }

Options& folly::Subprocess::Options::closeOtherFds ( )

inline

Close all other fds (other than standard input, output, error, and file descriptors explicitly specified with fd()).

This is potentially slow; it's generally a better idea to set the close-on-exec flag on all file descriptors that shouldn't be inherited by the child.

Even with this option set, standard input, output, and error are not closed; use stdin(CLOSE), stdout(CLOSE), stderr(CLOSE) if you desire this.

Definition at line 368 of file Subprocess.h.

Referenced by TEST().

                             {
      closeOtherFds_ = true;
      return *this;
    }

Options& folly::Subprocess::Options::dangerousPostForkPreExecCallback ( DangerousPostForkPreExecCallback *  cob )

inline

*** READ THIS WHOLE DOCBLOCK BEFORE USING ***

Run this callback in the child after the fork, just before the exec(), and after the child's state has been completely set up:

• signal handlers have been reset to default handling and unblocked
• the working directory was set
• closed any file descriptors specified via Options()
• set child process flags (see code)

This is EXTREMELY DANGEROUS. For example, this innocuous-looking code can cause a fraction of your Subprocess launches to hang forever:

LOG(INFO) << "Hello from the child";

The reason is that glog has an internal mutex. If your fork() happens when the parent has the mutex locked, the child will wait forever.

== GUIDELINES ==

• Be quick – the parent thread is blocked until you exit.
• Remember that other parent threads are running, and may mutate your state.
• Avoid mutating any data belonging to the parent.
• Avoid interacting with non-POD data that came from the parent.
• Avoid any libraries that may internally reference non-POD state.
• Especially beware parent mutexes, e.g. LOG() uses a global mutex.
• Avoid invoking the parent's destructors (you can accidentally delete files, terminate network connections, etc).
• Read http://ewontfix.com/7/

Definition at line 457 of file Subprocess.h.

References folly::pushmi::__adl::noexcept(), and uint64_t.

Referenced by TEST().

                                               {
      dangerousPostForkPreExecCallback_ = cob;
      return *this;
    }

Options& folly::Subprocess::Options::detach ( )

inline

Detach the spawned process, to allow destroying the Subprocess object without waiting for the child process to finish.

This causes the code to fork twice before executing the command. The intermediate child process will exit immediately, causing the process running the executable to be reparented to init (pid 1).

Subprocess objects created with detach() enabled will already be in an "EXITED" state when the constructor returns. The caller should not call wait() or poll() on the Subprocess, and pid() will return -1.

Definition at line 421 of file Subprocess.h.

Referenced by TEST().

                      {
      detach_ = true;
      return *this;
    }

Subprocess::Options & folly::Subprocess::Options::fd	(	int	fd,
		int	action
	)

Change action for file descriptor fd.

"action" may be another file descriptor number (dup2()ed before the child execs), or one of CLOSE, PIPE_IN, and PIPE_OUT.

CLOSE: close the file descriptor in the child PIPE_IN: open a pipe from the child PIPE_OUT: open a pipe to the child

PIPE is a shortcut; same as PIPE_IN for stdin (fd 0), same as PIPE_OUT for stdout (fd 1) or stderr (fd 2), and an error for other file descriptors.

Definition at line 173 of file Subprocess.cpp.

References upload::action, folly::Subprocess::PIPE, folly::Subprocess::PIPE_IN, and folly::Subprocess::PIPE_OUT.

                                                           {
  if (action == Subprocess::PIPE) {
    if (fd == 0) {
      action = Subprocess::PIPE_IN;
    } else if (fd == 1 || fd == 2) {
      action = Subprocess::PIPE_OUT;
    } else {
      throw std::invalid_argument(
          to<std::string>("Only fds 0, 1, 2 are valid for action=PIPE: ", fd));
    }
  }
  fdActions_[fd] = action;
  return *this;
}

Options& folly::Subprocess::Options::pipeStderr ( )

inline

Definition at line 352 of file Subprocess.h.

Referenced by TEST().

                          {
      return fd(STDERR_FILENO, PIPE_OUT);
    }

Options& folly::Subprocess::Options::pipeStdin ( )

inline

Definition at line 346 of file Subprocess.h.

Referenced by TEST().

                         {
      return fd(STDIN_FILENO, PIPE_IN);
    }

Options& folly::Subprocess::Options::pipeStdout ( )

inline

Definition at line 349 of file Subprocess.h.

Referenced by getNoteRawContent(), and TEST().

                          {
      return fd(STDOUT_FILENO, PIPE_OUT);
    }

Options& folly::Subprocess::Options::processGroupLeader ( )

inline

Child will be made a process group leader when it starts. Upside: one can reliably kill all its non-daemonizing descendants. Downside: the child will not receive Ctrl-C etc during interactive use.

Definition at line 404 of file Subprocess.h.

                                  {
      processGroupLeader_ = true;
      return *this;
    }

Options& folly::Subprocess::Options::stderrFd ( int  action )

inline

Shortcut to change the action for standard error. Note that stderr(1) will redirect the standard error to the same file descriptor as standard output; the equivalent of bash's "2>&1"

Definition at line 342 of file Subprocess.h.

                                  {
      return fd(STDERR_FILENO, action);
    }

Options& folly::Subprocess::Options::stdinFd ( int  action )

inline

Shortcut to change the action for standard input.

Definition at line 326 of file Subprocess.h.

Referenced by TEST().

                                 {
      return fd(STDIN_FILENO, action);
    }

Options& folly::Subprocess::Options::stdoutFd ( int  action )

inline

Shortcut to change the action for standard output.

Definition at line 333 of file Subprocess.h.

Referenced by TEST().

                                  {
      return fd(STDOUT_FILENO, action);
    }

Options& folly::Subprocess::Options::usePath ( )

inline

Use the search path ($PATH) when searching for the executable.

Definition at line 376 of file Subprocess.h.

Referenced by getNoteRawContent(), and TEST().

                       {
      usePath_ = true;
      return *this;
    }

Friends And Related Function Documentation

friend class Subprocess

friend

Definition at line 302 of file Subprocess.h.

Member Data Documentation

std::string folly::Subprocess::Options::childDir_

private

Definition at line 493 of file Subprocess.h.

bool folly::Subprocess::Options::closeOtherFds_ {false}

private

Definition at line 489 of file Subprocess.h.

Referenced by folly::Subprocess::prepareChild().

DangerousPostForkPreExecCallback* folly::Subprocess::Options::dangerousPostForkPreExecCallback_

private

Initial value:

{
        nullptr}

Definition at line 497 of file Subprocess.h.

Referenced by folly::Subprocess::prepareChild().

bool folly::Subprocess::Options::detach_ {false}

private

Definition at line 492 of file Subprocess.h.

Referenced by folly::Subprocess::spawn().

FdMap folly::Subprocess::Options::fdActions_

private

Definition at line 488 of file Subprocess.h.

Referenced by folly::Subprocess::prepareChild().

bool folly::Subprocess::Options::processGroupLeader_ {false}

private

Definition at line 491 of file Subprocess.h.

Referenced by folly::Subprocess::prepareChild().

bool folly::Subprocess::Options::usePath_ {false}

private

Definition at line 490 of file Subprocess.h.

Referenced by folly::Subprocess::runChild(), folly::Subprocess::spawn(), and folly::Subprocess::Subprocess().

---

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

• proxygen/folly/folly/Subprocess.h
• proxygen/folly/folly/Subprocess.cpp