E-MailRelay
Classes | Public Member Functions | Static Public Member Functions | List of all members
G::NewProcess Class Reference

A class for creating new processes. More...

#include <gnewprocess.h>

Classes

struct  Fd
 Wraps up a file descriptor for passing to G::NewProcess. More...
 

Public Member Functions

 NewProcess (const Path &exe, const StringArray &args, const Environment &env=Environment::minimal(), Fd fd_stdin=Fd::devnull(), Fd fd_stdout=Fd::pipe(), Fd fd_stderr=Fd::devnull(), const G::Path &cd=G::Path(), bool strict_path=true, Identity run_as_id=Identity::invalid(), bool strict_id=true, int exec_error_exit=127, const std::string &exec_error_format=std::string(), std::string(*exec_error_format_fn)(std::string, int)=nullptr)
 Constructor. More...
 
 NewProcess (const NewProcessConfig &)
 Constructor overload with parameters packaged into a structure. More...
 
 ~NewProcess ()
 Destructor. More...
 
int id () const noexcept
 Returns the process id. More...
 
NewProcessWaitablewaitable () noexcept
 Returns a reference to the Waitable sub-object so that the caller can wait for the child process to exit. More...
 
void kill (bool yield=false) noexcept
 Tries to kill the spawned process and optionally yield to a thread that might be waiting on it. More...
 
 NewProcess (const NewProcess &)=delete
 
 NewProcess (NewProcess &&)=delete
 
void operator= (const NewProcess &)=delete
 
void operator= (NewProcess &&)=delete
 

Static Public Member Functions

static std::pair< bool, pid_t > fork ()
 A utility function that forks the calling process and returns twice; once in the parent and once in the child. More...
 

Detailed Description

A class for creating new processes.

Eg:

{
NewProcess task( "foo" , args ) ;
auto& waitable = task.waitable() ;
int rc = waitable.get() ;
std::string s = waitable.output() ;
...
}
int get() const
Returns the result of the wait() as either the process exit code or as a thrown exception.
std::string output() const
Returns the first bit of child-process output.
NewProcessWaitable & wait()
Waits for the process identified by the constructor parameter to exit.
NewProcess(const Path &exe, const StringArray &args, const Environment &env=Environment::minimal(), Fd fd_stdin=Fd::devnull(), Fd fd_stdout=Fd::pipe(), Fd fd_stderr=Fd::devnull(), const G::Path &cd=G::Path(), bool strict_path=true, Identity run_as_id=Identity::invalid(), bool strict_id=true, int exec_error_exit=127, const std::string &exec_error_format=std::string(), std::string(*exec_error_format_fn)(std::string, int)=nullptr)
Constructor.
NewProcessWaitable & waitable() noexcept
Returns a reference to the Waitable sub-object so that the caller can wait for the child process to e...
See also
G::Daemon, G::NewProcessWaitable

Definition at line 63 of file gnewprocess.h.

Constructor & Destructor Documentation

◆ NewProcess() [1/2]

G::NewProcess::NewProcess ( const Path exe,
const StringArray args,
const Environment env = Environment::minimal(),
Fd  fd_stdin = Fd::devnull(),
Fd  fd_stdout = Fd::pipe(),
Fd  fd_stderr = Fd::devnull(),
const G::Path cd = G::Path(),
bool  strict_path = true,
Identity  run_as_id = Identity::invalid(),
bool  strict_id = true,
int  exec_error_exit = 127,
const std::string &  exec_error_format = std::string(),
std::string(*)(std::string, int)  exec_error_format_fn = nullptr 
)

Constructor.

Spawns the given program to run independently in a child process.

The child process's stdin, stdout and stderr are connected as directed, but exactly one of stdout and stderr must be the internal pipe since it is used to detect process termination. To inherit the existing file descriptors use Fd(STDIN_FILENO) etc. Using Fd::fd(-1) is equivalent to Fd::devnull().

The child process is given the new environment, unless the environment given is empty() in which case the environment is inherited from the calling process (see G::Environment::inherit()).

If 'strict_path' then the program must be given as an absolute path. Otherwise it can be relative and the calling process's PATH is used to find it.

If a valid identity is supplied then the child process runs as that identity. If 'strict_id' is also true then the id is not allowed to be root. See G::Process::beOrdinaryForExec().

If the exec() fails then the 'exec_error_exit' argument is used as the child process exit code.

The internal pipe can be used for error messages in the situation where the exec() in the forked child process fails. This requires that one of the 'exec_error_format' parameters is given; by default nothing is sent over the pipe when the exec() fails.

The exec error message is assembled by the given callback function, with the 'exec_error_format' argument passed as its first parameter. The second parameter is the exec() errno. The default callback function does text substitution for "__errno__" and "__strerror__" substrings that appear within the error format string.

Definition at line 111 of file gnewprocess_unix.cpp.

◆ NewProcess() [2/2]

G::NewProcess::NewProcess ( const NewProcessConfig config)
inlineexplicit

Constructor overload with parameters packaged into a structure.

Definition at line 373 of file gnewprocess.h.

◆ ~NewProcess()

G::NewProcess::~NewProcess ( )
default

Destructor.

Kills the spawned process if the Waitable has not been resolved.

Member Function Documentation

◆ fork()

std::pair< bool, pid_t > G::NewProcess::fork ( )
static

A utility function that forks the calling process and returns twice; once in the parent and once in the child.

Returns an "is-in-child/child-pid" pair.

See also
G::Daemon

Definition at line 129 of file gnewprocess_unix.cpp.

◆ id()

int G::NewProcess::id ( ) const
noexcept

Returns the process id.

Definition at line 134 of file gnewprocess_unix.cpp.

◆ kill()

void G::NewProcess::kill ( bool  yield = false)
noexcept

Tries to kill the spawned process and optionally yield to a thread that might be waiting on it.

Definition at line 139 of file gnewprocess_unix.cpp.

◆ waitable()

G::NewProcessWaitable & G::NewProcess::waitable ( )
noexcept

Returns a reference to the Waitable sub-object so that the caller can wait for the child process to exit.

Definition at line 124 of file gnewprocess_unix.cpp.


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