SC::Process Struct Reference

Execute a child process with standard file descriptors redirection. More...

#include <Process.h>

Classes
struct	Options
struct	StdIn
struct	StdOut
struct	StdStream

Public Types
using	StdErr = StdOut

Public Member Functions
Result	waitForExitSync ()
	Waits (blocking) for process to exit after launch. It can only be called if Process::launch succeeded. More...
Result	launch (Span< const StringView > cmd, const StdOut &stdOut=StdOut::Inherit{}, const StdIn &stdIn=StdIn::Inherit{}, const StdErr &stdErr=StdErr::Inherit{})
	Launch child process with the given arguments. More...
Result	exec (Span< const StringView > cmd, const StdOut &stdOut=StdOut::Inherit{}, const StdIn &stdIn=StdIn::Inherit{}, const StdErr &stdErr=StdErr::Inherit{})
	Executes a child process with the given arguments, waiting (blocking) until it's fully finished. More...
int32_t	getExitStatus () const
	gets the return code from the exited child process (valid only after exec or waitForExitSync) More...
Result	setWorkingDirectory (StringView processWorkingDirectory)
	Sets the starting working directory of the process that will be launched / executed. More...
void	inheritParentEnvironmentVariables (bool inherit)
	Controls if the newly spawned child process will inherit parent process environment variables. More...
Result	setEnvironment (StringView environmentVariable, StringView value)
	Sets the environment variable for the newly spawned child process. More...

Static Public Member Functions
static size_t	getNumberOfProcessors ()
	Returns number of (virtual) processors available. More...
static bool	isWindowsConsoleSubsystem ()
	Returns true only under Windows if executable is compiled with /SUBSYSTEM:Console More...

Public Attributes
ProcessDescriptor	handle
	Handle to the OS process. More...
ProcessID	processID
	ID of the process (can be the same as handle on some OS) More...
Options	options
	Options for the child process (hide console window etc.) More...

Friends
struct	IntrusiveDoubleLinkedList< Process >
struct	ProcessChain

Detailed Description

Execute a child process with standard file descriptors redirection.

Features:

• Redirect standard in/out/err of a child process to a Pipe
• Inherit child process file descriptors from parent process
• Ignore (silence) child process standard file descriptor
• Wait for the child process exit code

Example: execute child process (launch and wait for it to fully execute)

    // Example: execute child process (launch and wait for it to fully execute)
    SC_TRY(Process().exec({"cmd.exe", "-h"}));

Example: execute child process, redirecting stdout to a string

    // Example: execute child process, redirecting stdout to a string
    SmallString<256> output; // could be also just String
    SC_TRY(Process().exec({"where.exe", "winver"}, output));
    // Output now contains "C:\Windows\System32\winver.exe\n"

Example: launch a child process and wait for it to finish execution

    // Example: launch a child process and explicitly wait for it to finish execution
    Process process;
    SC_TRY(process.launch({"ls", "-l"}));
    // ...
    // Here you can do I/O to and from the spawned process
    // ...
    SC_TRY(process.waitForExitSync());
    // This is equivalent to process.exec({"ls", "-l"})

Example: execute child process, filling its stdin with a StringView

    // Example: execute child process, filling its stdin with a StringView
    // This is equivalent of shell command:
    // `echo "child process" | grep process`
    SC_TRY(Process().exec({"grep", "process"}, Process::StdOut::Inherit(), "child proc"));

Example: read process output using a pipe, using launch + waitForExitSync

    // Example: read process output using a pipe, using launch + waitForExitSync
    Process        process;
    PipeDescriptor outputPipe;
    SC_TRY(process.launch({"executable.exe", "--argument1", "--argument2"}, outputPipe));
    String output = StringEncoding::Ascii; // Could also use SmallString<N>
    SC_TRY(outputPipe.readPipe.readUntilEOF(output));
    SC_TRY(process.waitForExitSync());
    // ... Do something with the 'output' string

Example: Add an environment variable

    Process process;
    // This child process will inherit parent environment variables plus NewEnvVar
    SC_TEST_EXPECT(process.setEnvironment("NewEnvVar", "SomeValue"));
    String output;
    // Spawn the child process writing all env variables as KEY=VALUE\n to stdout, redirected to output
    SC_TEST_EXPECT(spawnChildAndPrintEnvironmentVars(process, output));
    // We can check that the NewEnvVar has been set to SomeValue
    SC_TEST_EXPECT(output.view().containsString("NewEnvVar=SomeValue"));
    // PATH env var exists because we are inheriting environment
    SC_TEST_EXPECT(output.view().containsString("PATH="));

Example: Redefine an environment variable

    Process process;
    // This child process will inherit parent environment variables but we re-define PATH
    SC_TEST_EXPECT(process.setEnvironment("PATH", "/usr/sane_cpp_binaries"));
    String output;
    // Spawn the child process writing all env variables as KEY=VALUE\n to stdout, redirected to output
    SC_TEST_EXPECT(spawnChildAndPrintEnvironmentVars(process, output));
    // PATH env var has been re-defined
    SC_TEST_EXPECT(output.view().containsString("PATH=/usr/sane_cpp_binaries"));

Example: Disable environment variable inheritance

    Process process;
    process.inheritParentEnvironmentVariables(false);
    String output;
    // Spawn the child process writing all env variables as KEY=VALUE\n to stdout, redirected to output
    SC_TEST_EXPECT(spawnChildAndPrintEnvironmentVars(process, output));
    // PATH env var doesn't exist because of Process::inheritParentEnvironmentVariables(false)
    SC_TEST_EXPECT(not output.view().containsString("PATH="));

Member Function Documentation

exec()

Result SC::Process::exec ( Span< const StringView >  cmd, const StdOut &  stdOut = StdOut::Inherit{}, const StdIn &  stdIn = StdIn::Inherit{}, const StdErr &  stdErr = StdErr::Inherit{}  )

inline

Executes a child process with the given arguments, waiting (blocking) until it's fully finished.

Parameters

cmd	Process executable path and its arguments (if any)
stdOut	Process::StdOut::Ignore{}, Process::StdOut::Inherit{} or redirect stdout to String/Vector/Span
stdIn	Process::StdIn::Ignore{}, Process::StdIn::Inherit{} or feed stdin from StringView/String/Vector/Span
stdErr	Process::StdErr::Ignore{}, Process::StdErr::Inherit{} or redirect stderr to String/Vector/Span

Returns

Error if the requested executable doesn't exist / is not accessible / it cannot be executed

getExitStatus()

int32_t SC::Process::getExitStatus ( ) const

inline

gets the return code from the exited child process (valid only after exec or waitForExitSync)

getNumberOfProcessors()

static size_t SC::Process::getNumberOfProcessors ( )

static

Returns number of (virtual) processors available.

inheritParentEnvironmentVariables()

void SC::Process::inheritParentEnvironmentVariables ( bool  inherit )

inline

Controls if the newly spawned child process will inherit parent process environment variables.

isWindowsConsoleSubsystem()

static bool SC::Process::isWindowsConsoleSubsystem ( )

static

Returns true only under Windows if executable is compiled with /SUBSYSTEM:Console

launch()

Result SC::Process::launch ( Span< const StringView >  cmd, const StdOut &  stdOut = StdOut::Inherit{}, const StdIn &  stdIn = StdIn::Inherit{}, const StdErr &  stdErr = StdErr::Inherit{}  )

inline

Launch child process with the given arguments.

Parameters

cmd	Process executable path and its arguments (if any)
stdOut	Process::StdOut::Ignore{}, Process::StdOut::Inherit{} or redirect stdout to String/Vector/Span
stdIn	Process::StdIn::Ignore{}, Process::StdIn::Inherit{} or feed stdin from StringView/String/Vector/Span
stdErr	Process::StdErr::Ignore{}, Process::StdErr::Inherit{} or redirect stderr to String/Vector/Span

Returns

Error if the requested executable doesn't exist / is not accessible / it cannot be executed

setEnvironment()

Result SC::Process::setEnvironment	(	StringView	environmentVariable,
		StringView	value
	)

Sets the environment variable for the newly spawned child process.

setWorkingDirectory()

Result SC::Process::setWorkingDirectory

(

StringView

processWorkingDirectory

)

Sets the starting working directory of the process that will be launched / executed.

waitForExitSync()

Result SC::Process::waitForExitSync

(

)

Waits (blocking) for process to exit after launch. It can only be called if Process::launch succeeded.

Member Data Documentation

handle

ProcessDescriptor SC::Process::handle

Handle to the OS process.

options

Options SC::Process::options

Options for the child process (hide console window etc.)

processID

ProcessID SC::Process::processID

ID of the process (can be the same as handle on some OS)

---

The documentation for this struct was generated from the following file:

• Process.h