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 | Config
| Configuration structure for G::NewProcess. More...
struct | Fd
| Wraps up a file descriptor for passing to G::NewProcess. More...

## Public Member Functions
| NewProcess (const Path &exe, const G::StringArray &args, const Config &)
| Constructor. More...
| ~NewProcess ()
| Destructor. More...
int | id () const noexcept
| Returns the process id. More...
NewProcessWaitable & | waitable () 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
NewProcess & | operator= (const NewProcess &)=delete
NewProcess & | 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( "exe" , args , {} ) ;
auto& waitable = task.waitable() ;
waitable.wait() ;
int rc = waitable.get() ;
std::string s = waitable.output() ;
...
}
G::NewProcessWaitable::get
int get() const
Returns the result of the wait() as either the process exit code or as a thrown exception.
Definition: gnewprocess_unix.cpp:486
G::NewProcessWaitable::output
std::string output() const
Returns the first bit of child-process output.
Definition: gnewprocess_unix.cpp:535
G::NewProcessWaitable::wait
NewProcessWaitable & wait()
Waits for the process identified by the constructor parameter to exit.
Definition: gnewprocess_unix.cpp:430
G::NewProcess::waitable
NewProcessWaitable & waitable() noexcept
Returns a reference to the Waitable sub-object so that the caller can wait for the child process to e...
Definition: gnewprocess_unix.cpp:116
G::NewProcess::NewProcess
NewProcess(const Path &exe, const G::StringArray &args, const Config &)
Constructor.
Definition: gnewprocess_unix.cpp:108

See also
  G::Daemon, G::NewProcessWaitable

Definition at line 61 of file gnewprocess.h.

## Constructor & Destructor Documentation

## ◆ NewProcess()

G::NewProcess::NewProcess | ( | const Path & | exe,
|  | const G::StringArray & | args,
|  | const Config & | config
| ) |  |

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_exe' then the program must be given as an absolute path. Otherwise it can be a relative path and the calling process's PATH variable or the 'exec_search_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 on Unix it is reported asynchronously with the 'exec_error_exit' argument used as the child process exit value; on Windows a CreateProcess() failure throws an exception.

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

If 'exec_error_format_fn' is given then the error message is assembled by passing it 'exec_error_format' as its first parameter and the errno as the second parameter. If the 'exec_error_format' string is given without 'exec_error_format_fn' then it is used as the error message after substitution of any "__errno__" and "__strerror__" sub-strings.

Definition at line 108 of file gnewprocess_unix.cpp.

## ◆ ~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.

Not implemented on windows. Returns an "is-in-child/child-pid" pair.

See also
  G::Daemon

Definition at line 121 of file gnewprocess_unix.cpp.

## ◆ id()

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

Returns the process id.

Definition at line 126 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 131 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 116 of file gnewprocess_unix.cpp.

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

- /tmp/slackdce/slackrepo.HKsbdz/build_emailrelay/emailrelay-2.6/src/glib/gnewprocess.h
- /tmp/slackdce/slackrepo.HKsbdz/build_emailrelay/emailrelay-2.6/src/glib/gnewprocess_unix.cpp
- /tmp/slackdce/slackrepo.HKsbdz/build_emailrelay/emailrelay-2.6/src/glib/gnewprocess_win32.cpp