carb::launcher::LaunchDesc

Defined in carb/launcher/ILauncher.h

struct LaunchDesc

Descriptor of the new process to be launched by ILauncher::openProcess().

This contains all the information needed to launch and communicate with the new child process.

Public Members

const char *const *argv = nullptr

A vector of command line arguments for the new process to launch.

This may not be nullptr. The first argument in the vector must be the path to the executable to run. This may be a relative or absolute path. All following arguments will be passed to the executable as command line arguments. Each string must be UTF-8 encoded. Note that if a relative path is used for the first argument, it must be given relative to the current working directory for the parent (ie: calling) process, not the path given by path. The path value will become the current working directory for the child process, not the path to find the executable image at.

size_t argc = 0

The total number of arguments in the argv vector.

const char *path = nullptr

The optional initial working directory of the new process.

If not specified, this will default to the calling process’s current working directory. Once the child process has been successfully started, its current working directory will be set to this path. This will neither affect the current working directory of the parent process nor will it be used as the path to find the child process’ executable.

OnProcessReadFn onReadStdout = nullptr

Callback to be performed whenever data is successfully read from the child process’s stdout or stderr streams.

These may be nullptr if nothing needs to be read from the child process’s stdout or stderr streams. Note that providing a callback here will spawn a new thread per callback to service read requests on the child process’s stdout or stderr streams. See OnProcessReadFn for more information on how these callbacks should be implemented and what their responsibilities are.

Note

[Linux] If this is non-nullptr and the parent process destroys its process handle for the child process before the child process exits, the child process will be terminated with SIGPIPE if it ever tries to write to the corresponding stream again This is the default Linux kernel behavior for writing to a broken pipe or socket. It is best practice to first wait for the child process to exit before destroying the process handle in the parent process.

OnProcessReadFn onReadStderr = nullptr

Callback to be performed whenever data is successfully read from the child process’s stdout or stderr streams.

These may be nullptr if nothing needs to be read from the child process’s stdout or stderr streams. Note that providing a callback here will spawn a new thread per callback to service read requests on the child process’s stdout or stderr streams. See OnProcessReadFn for more information on how these callbacks should be implemented and what their responsibilities are.

Note

[Linux] If this is non-nullptr and the parent process destroys its process handle for the child process before the child process exits, the child process will be terminated with SIGPIPE if it ever tries to write to the corresponding stream again This is the default Linux kernel behavior for writing to a broken pipe or socket. It is best practice to first wait for the child process to exit before destroying the process handle in the parent process.

void *readStdoutContext = nullptr

The opaque context value to be passed to the read callbacks when they are performed.

This will never be accessed directly by the process object, just passed along to the callbacks. It is the responsibility of the callbacks to know how to appropriately interpret these values. These values are ignored if both onReadStdout and onReadStderr are nullptr.

void *readStderrContext = nullptr

The opaque context value to be passed to the read callbacks when they are performed.

This will never be accessed directly by the process object, just passed along to the callbacks. It is the responsibility of the callbacks to know how to appropriately interpret these values. These values are ignored if both onReadStdout and onReadStderr are nullptr.

LauncherFlags flags = 0

Flags to control the behavior of the new child process.

This is zero or more of the LauncherFlags flags.

size_t bufferSize = kDefaultProcessBufferSize

A hint for the size of the buffer to use when reading from the child process’s stdout and stderr streams.

This represents the maximum amount of data that can be read at once and returned through the onRead*() callbacks. This is ignored if both onReadStdout and onReadStderr are nullptr.

Note that this buffer size is only a hint and may be adjusted internally to meet a reasonable minimum read size for the platform.

const char *const *env = nullptr

A block of environment variables to pass to the child process.

If the flags include the fLaunchFlagNoInheritEnv flag, this environment block will be used explicitly if non-nullptr. If that flag is not used, the calling process’s current environment will be prepended to the block specified here. Any environment variables specified in here will replace any variables in the calling process’s environment block. Each string in this block must be UTF-8 encoded. If this is nullptr, the default behavior is for the child process to inherit the entire environment of the parent process. If an empty non-nullptr environment block is specified here, the child process will be launched without any environment.

size_t envCount = 0

The number of environment variables specified in the environment block env.

This may only be 0 if the environment block is empty or nullptr.

const char *interpreter = nullptr

An optional command interpreter name to use when launching the new process.

This can be used when launching a script file (ie: shell script, python script, etc). This must be nullptr if the command being launched is a binary executable. If this is nullptr and a script file is being executed, an attempt will be made to determine the appropriate command interpreter based on the file extension of the first argument in argv. The ILauncher::launchProcess() call may fail if this is nullptr, an appropriate interpreter could not be found for the named script, and the named script could not be launched directly on the calling platform (ie: a script using a shebang on its first line will internally specify its own command interpreter). This value is ignored if the fLaunchFlagScript flag is not present in flags.

This can be one of the kInterpreter* names to use a standard command interpreter that is [presumably] installed on the system. If a specific command interpreter is to be used instead, it is the caller’s responsibility to set this appropriately.

Note

This interpreter process will be launched with a search on the system’s ‘PATH’ variable. On Windows this is always the behavior for launching any process. However, on Linux a process must always be identified by its path (relative or absolute) except in the case of launching a command interpreter.

const char *stdoutLog = nullptr

Optional names of log files to redirect stdout and stderr output from the child process to in lieu of a callback.

The output from these streams won’t be visible to the parent process (unless it is also reading from the log file). If either of these are non-nullptr and not an empty string, and the callbacks (onReadStdout or onReadStderr) are also nullptr, the corresponding stream from the child process will be redirected to these files(s) on disk. It is the caller’s responsibility to ensure the requested filename is valid and writable. If the log fails to open, launching the child process will be silently ignored or fail depending on whether the fLaunchFlagAllowBadLog flag is used or not. These logs will be ignored if any of the fLaunchFlagNoStdStreams flags are used. The log file corresponding to the flag(s) used will be disabled.

When a log is requested, it will be opened in a sharing mode. The log will be opened with shared read and write permissions. If the named log file already exists, it will always be truncated when opened. It is the caller’s responsibility to ensure the previous file is moved or renamed if its contents need to be preserved. The log will also be opened in ‘append’ mode (ie: as if “a+” had been passed to fopen()) so that all new messages are written at the end of the file. It is the child process’s responsibility to ensure that all messages written to the log files are synchronized so that messages do not get incorrectly interleaved. If both log files are given the same name, it is also the child process’s responsibility to ensure writes to stdout and stderr are appropriately serialized.

Setting log file names here will behave roughly like shell redirection to a file. The two streams can be independently specified (as in “> out.txt & err.txt”), or they can both be redirected to the same file (as in “&> log.txt” or > log.txt & log.txt”). The files will behave as expected in the child process - writing to stdout will be buffered while writing to stderr will be unbuffered. If the named log file already exists, it will always be overwritten and truncated.

This filename can be either an absolute or relative path. Relative paths will be opened relative to the current working directory at the time. The caller is responsible for ensuring all path components leading up to the log filename exist before calling. Note that the log file(s) will be created before the child process is launched. If the child process fails to launch, it will be the caller’s responsibility to clean up the log file if necessary.

Note

if a non-nullptr callback is given for either stdout or stderr, that will override the log file named here. Each log file will only be created if its corresponding callback is not specified.

const char *stderrLog = nullptr

Optional names of log files to redirect stdout and stderr output from the child process to in lieu of a callback.

The output from these streams won’t be visible to the parent process (unless it is also reading from the log file). If either of these are non-nullptr and not an empty string, and the callbacks (onReadStdout or onReadStderr) are also nullptr, the corresponding stream from the child process will be redirected to these files(s) on disk. It is the caller’s responsibility to ensure the requested filename is valid and writable. If the log fails to open, launching the child process will be silently ignored or fail depending on whether the fLaunchFlagAllowBadLog flag is used or not. These logs will be ignored if any of the fLaunchFlagNoStdStreams flags are used. The log file corresponding to the flag(s) used will be disabled.

When a log is requested, it will be opened in a sharing mode. The log will be opened with shared read and write permissions. If the named log file already exists, it will always be truncated when opened. It is the caller’s responsibility to ensure the previous file is moved or renamed if its contents need to be preserved. The log will also be opened in ‘append’ mode (ie: as if “a+” had been passed to fopen()) so that all new messages are written at the end of the file. It is the child process’s responsibility to ensure that all messages written to the log files are synchronized so that messages do not get incorrectly interleaved. If both log files are given the same name, it is also the child process’s responsibility to ensure writes to stdout and stderr are appropriately serialized.

Setting log file names here will behave roughly like shell redirection to a file. The two streams can be independently specified (as in “> out.txt & err.txt”), or they can both be redirected to the same file (as in “&> log.txt” or > log.txt & log.txt”). The files will behave as expected in the child process - writing to stdout will be buffered while writing to stderr will be unbuffered. If the named log file already exists, it will always be overwritten and truncated.

This filename can be either an absolute or relative path. Relative paths will be opened relative to the current working directory at the time. The caller is responsible for ensuring all path components leading up to the log filename exist before calling. Note that the log file(s) will be created before the child process is launched. If the child process fails to launch, it will be the caller’s responsibility to clean up the log file if necessary.

Note

if a non-nullptr callback is given for either stdout or stderr, that will override the log file named here. Each log file will only be created if its corresponding callback is not specified.

void *ext = nullptr

Reserved for future expansion.

This must be nullptr.