Process control support. More...

Namespaces
namespace	SDL::prop
	Constants for Properties keys.
namespace	SDL::prop::Process
	Properties for processes.
namespace	SDL::prop::Process::Create
	Properties for process creation.

Classes
struct	SDL::Process
	An opaque handle representing a system process. More...

Typedefs
using	SDL::ProcessRaw = SDL_Process*
	Alias to raw representation for Process.
using	SDL::ProcessRef = ResourceRef<Process>
	Reference for Process.
using	SDL::ProcessIO = SDL_ProcessIO
	Description of where standard I/O should be directed when creating a process.

Functions
Process	SDL::CreateProcess (const char const args, bool pipe_stdio)
	Create a new process.
Process	SDL::CreateProcessWithProperties (PropertiesRef props)
	Create a new process with the specified properties.
PropertiesRef	SDL::GetProcessProperties (ProcessRef process)
	Get the properties associated with a process.
StringResult	SDL::ReadProcess (ProcessRef process, int *exitcode=nullptr)
	Read all the output from a process.
IOStreamRef	SDL::GetProcessInput (ProcessRef process)
	Get the IOStream associated with process standard input.
IOStreamRef	SDL::GetProcessOutput (ProcessRef process)
	Get the IOStream associated with process standard output.
void	SDL::KillProcess (ProcessRef process, bool force)
	Stop a process.
bool	SDL::WaitProcess (ProcessRef process, bool block, int *exitcode)
	Wait for a process to finish.
void	SDL::DestroyProcess (ProcessRaw process)
	Destroy a previously created process object.
	SDL::Process::Process (const char const args, bool pipe_stdio)
	Create a new process.
	SDL::Process::Process (PropertiesRef props)
	Create a new process with the specified properties.
PropertiesRef	SDL::Process::GetProperties () const
	Get the properties associated with a process.
StringResult	SDL::Process::Read (int *exitcode=nullptr)
	Read all the output from a process.
IOStreamRef	SDL::Process::GetInput ()
	Get the IOStream associated with process standard input.
IOStreamRef	SDL::Process::GetOutput ()
	Get the IOStream associated with process standard output.
void	SDL::Process::Kill (bool force)
	Stop a process.
bool	SDL::Process::Wait (bool block, int *exitcode)
	Wait for a process to finish.
void	SDL::Process::Destroy ()
	Destroy a previously created process object.

Variables
constexpr ProcessIO	SDL::PROCESS_STDIO_INHERITED
	The I/O stream is inherited from the application.
constexpr ProcessIO	SDL::PROCESS_STDIO_NULL
	The I/O stream is ignored.
constexpr ProcessIO	SDL::PROCESS_STDIO_APP = SDL_PROCESS_STDIO_APP
	The I/O stream is connected to a new IOStream that the application can read or write.
constexpr ProcessIO	SDL::PROCESS_STDIO_REDIRECT = SDL_PROCESS_STDIO_REDIRECT
	The I/O stream is redirected to an existing IOStream.

Detailed Description

Process control support.

These functions provide a cross-platform way to spawn and manage OS-level processes.

You can create a new subprocess with CreateProcess() and optionally read and write to it using Process.Read() or Process.GetInput() and Process.GetOutput(). If more advanced functionality like chaining input between processes is necessary, you can use CreateProcessWithProperties().

You can get the status of a created process with Process.Wait(), or terminate the process with Process.Kill().

Don't forget to call Process.Destroy() to clean up, whether the process process was killed, terminated on its own, or is still running!

Typedef Documentation

◆ ProcessIO

using SDL::ProcessIO = SDL_ProcessIO

Description of where standard I/O should be directed when creating a process.

If a standard I/O stream is set to PROCESS_STDIO_INHERITED, it will go to the same place as the application's I/O stream. This is the default for standard output and standard error.

If a standard I/O stream is set to SDL_PROCESS_STDIO_nullptr, it is connected to NUL: on Windows and /dev/null on POSIX systems. This is the default for standard input.

If a standard I/O stream is set to PROCESS_STDIO_APP, it is connected to a new IOStream that is available to the application. Standard input will be available as prop.Process.STDIN_POINTER and allows Process.GetInput(), standard output will be available as prop.Process.STDOUT_POINTER and allows Process.Read() and Process.GetOutput(), and standard error will be available as prop.Process.STDERR_POINTER in the properties for the created process.

If a standard I/O stream is set to PROCESS_STDIO_REDIRECT, it is connected to an existing IOStream provided by the application. Standard input is provided using prop.Process.Create.STDIN_POINTER, standard output is provided using prop.Process.Create.STDOUT_POINTER, and standard error is provided using prop.Process.Create.STDERR_POINTER in the creation properties. These existing streams should be closed by the application once the new process is created.

In order to use an IOStream with PROCESS_STDIO_REDIRECT, it must have prop.IOStream.WINDOWS_HANDLE_POINTER or prop.IOStream.FILE_DESCRIPTOR_NUMBER set. This is true for streams representing files and process I/O.

Since: This enum is available since SDL 3.2.0.

See also: CreateProcessWithProperties; Process.GetProperties; Process.Read; Process.GetInput; Process.GetOutput

◆ ProcessRef

using SDL::ProcessRef = ResourceRef<Process>

Reference for Process.

This does not take ownership!

Function Documentation

◆ CreateProcess()

Process SDL::CreateProcess	(	const char const	args,
		bool	pipe_stdio )

inline

Create a new process.

The path to the executable is supplied in args[0]. args[1..N] are additional arguments passed on the command line of the new process, and the argument list should be terminated with a nullptr, e.g.:

const char *args[] = { "myprogram", "argument", nullptr };

Setting pipe_stdio to true is equivalent to setting prop.Process.Create.STDIN_NUMBER and prop.Process.Create.STDOUT_NUMBER to PROCESS_STDIO_APP, and will allow the use of Process.Read() or Process.GetInput() and Process.GetOutput().

See CreateProcessWithProperties() for more details.

Parameters

args	the path and arguments for the new process.
pipe_stdio	true to create pipes to the process's standard input and from the process's standard output, false for the process to have no input and inherit the application's standard output.

Returns: the newly created and running process, or nullptr if the process couldn't be created.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: CreateProcessWithProperties; Process.GetProperties; Process.Read; Process.GetInput; Process.GetOutput; Process.Kill; Process.Wait; Process.Destroy

◆ CreateProcessWithProperties()

Process SDL::CreateProcessWithProperties ( PropertiesRef props )

inline

Create a new process with the specified properties.

These are the supported properties:

prop.Process.Create.ARGS_POINTER: an array of strings containing the program to run, any arguments, and a nullptr pointer, e.g. const char *args[] = { "myprogram", "argument", nullptr }. This is a required property.
prop.Process.Create.ENVIRONMENT_POINTER: an Environment pointer. If this property is set, it will be the entire environment for the process, otherwise the current environment is used.
prop.Process.Create.WORKING_DIRECTORY_STRING: a UTF-8 encoded string representing the working directory for the process, defaults to the current working directory.
prop.Process.Create.STDIN_NUMBER: an ProcessIO value describing where standard input for the process comes from, defaults to SDL_PROCESS_STDIO_nullptr.
prop.Process.Create.STDIN_POINTER: an IOStream pointer used for standard input when prop.Process.Create.STDIN_NUMBER is set to PROCESS_STDIO_REDIRECT.
prop.Process.Create.STDOUT_NUMBER: an ProcessIO value describing where standard output for the process goes to, defaults to PROCESS_STDIO_INHERITED.
prop.Process.Create.STDOUT_POINTER: an IOStream pointer used for standard output when prop.Process.Create.STDOUT_NUMBER is set to PROCESS_STDIO_REDIRECT.
prop.Process.Create.STDERR_NUMBER: an ProcessIO value describing where standard error for the process goes to, defaults to PROCESS_STDIO_INHERITED.
prop.Process.Create.STDERR_POINTER: an IOStream pointer used for standard error when prop.Process.Create.STDERR_NUMBER is set to PROCESS_STDIO_REDIRECT.
prop.Process.Create.STDERR_TO_STDOUT_BOOLEAN: true if the error output of the process should be redirected into the standard output of the process. This property has no effect if prop.Process.Create.STDERR_NUMBER is set.
prop.Process.Create.BACKGROUND_BOOLEAN: true if the process should run in the background. In this case the default input and output is SDL_PROCESS_STDIO_nullptr and the exitcode of the process is not available, and will always be 0.
prop.Process.Create.CMDLINE_STRING: a string containing the program to run and any parameters. This string is passed directly to CreateProcess on Windows, and does nothing on other platforms. This property is only important if you want to start programs that does non-standard command-line processing, and in most cases using prop.Process.Create.ARGS_POINTER is sufficient.

On POSIX platforms, wait() and waitpid(-1, ...) should not be called, and SIGCHLD should not be ignored or handled because those would prevent SDL from properly tracking the lifetime of the underlying process. You should use Process.Wait() instead.

Parameters

props the properties to use.

Returns: the newly created and running process, or nullptr if the process couldn't be created.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: CreateProcess; Process.GetProperties; Process.Read; Process.GetInput; Process.GetOutput; Process.Kill; Process.Wait; Process.Destroy

◆ Destroy()

void SDL::Process::Destroy ( )

inline

Destroy a previously created process object.

Note that this does not stop the process, just destroys the SDL object used to track it. If you want to stop the process you should use Process.Kill().

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: CreateProcess; CreateProcessWithProperties; Process.Kill

◆ DestroyProcess()

void SDL::DestroyProcess ( ProcessRaw process )

inline

Destroy a previously created process object.

Note that this does not stop the process, just destroys the SDL object used to track it. If you want to stop the process you should use Process.Kill().

Parameters

process The process object to destroy.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: CreateProcess; CreateProcessWithProperties; Process.Kill

◆ GetInput()

IOStreamRef SDL::Process::GetInput ( )

inline

Get the IOStream associated with process standard input.

The process must have been created with CreateProcess() and pipe_stdio set to true, or with CreateProcessWithProperties() and prop.Process.Create.STDIN_NUMBER set to PROCESS_STDIO_APP.

Writing to this stream can return less data than expected if the process hasn't read its input. It may be blocked waiting for its output to be read, if so you may need to call Process.GetOutput() and read the output in parallel with writing input.

Returns: the input stream or nullptr on failure; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: CreateProcess; CreateProcessWithProperties; Process.GetOutput

◆ GetOutput()

IOStreamRef SDL::Process::GetOutput ( )

inline

Get the IOStream associated with process standard output.

The process must have been created with CreateProcess() and pipe_stdio set to true, or with CreateProcessWithProperties() and prop.Process.Create.STDOUT_NUMBER set to PROCESS_STDIO_APP.

Reading from this stream can return 0 with IOStream.GetStatus() returning IO_STATUS_NOT_READY if no output is available yet.

Returns: the output stream or nullptr on failure; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: CreateProcess; CreateProcessWithProperties; Process.GetInput

◆ GetProcessInput()

IOStreamRef SDL::GetProcessInput ( ProcessRef process )

inline

Get the IOStream associated with process standard input.

The process must have been created with CreateProcess() and pipe_stdio set to true, or with CreateProcessWithProperties() and prop.Process.Create.STDIN_NUMBER set to PROCESS_STDIO_APP.

Writing to this stream can return less data than expected if the process hasn't read its input. It may be blocked waiting for its output to be read, if so you may need to call Process.GetOutput() and read the output in parallel with writing input.

Parameters

process The process to get the input stream for.

Returns: the input stream or nullptr on failure; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: CreateProcess; CreateProcessWithProperties; Process.GetOutput

◆ GetProcessOutput()

IOStreamRef SDL::GetProcessOutput ( ProcessRef process )

inline

Get the IOStream associated with process standard output.

The process must have been created with CreateProcess() and pipe_stdio set to true, or with CreateProcessWithProperties() and prop.Process.Create.STDOUT_NUMBER set to PROCESS_STDIO_APP.

Reading from this stream can return 0 with IOStream.GetStatus() returning IO_STATUS_NOT_READY if no output is available yet.

Parameters

process The process to get the output stream for.

Returns: the output stream or nullptr on failure; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: CreateProcess; CreateProcessWithProperties; Process.GetInput

◆ GetProcessProperties()

PropertiesRef SDL::GetProcessProperties ( ProcessRef process )

inline

Get the properties associated with a process.

The following read-only properties are provided by SDL:

prop.Process.PID_NUMBER: the process ID of the process.
prop.Process.STDIN_POINTER: an IOStream that can be used to write input to the process, if it was created with prop.Process.Create.STDIN_NUMBER set to PROCESS_STDIO_APP.
prop.Process.STDOUT_POINTER: a non-blocking IOStream that can be used to read output from the process, if it was created with prop.Process.Create.STDOUT_NUMBER set to PROCESS_STDIO_APP.
prop.Process.STDERR_POINTER: a non-blocking IOStream that can be used to read error output from the process, if it was created with prop.Process.Create.STDERR_NUMBER set to PROCESS_STDIO_APP.
prop.Process.BACKGROUND_BOOLEAN: true if the process is running in the background.

Parameters

process the process to query.

Returns: a valid property ID on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: CreateProcess; CreateProcessWithProperties

◆ GetProperties()

PropertiesRef SDL::Process::GetProperties ( ) const

inline

Get the properties associated with a process.

The following read-only properties are provided by SDL:

prop.Process.PID_NUMBER: the process ID of the process.
prop.Process.STDIN_POINTER: an IOStream that can be used to write input to the process, if it was created with prop.Process.Create.STDIN_NUMBER set to PROCESS_STDIO_APP.
prop.Process.STDOUT_POINTER: a non-blocking IOStream that can be used to read output from the process, if it was created with prop.Process.Create.STDOUT_NUMBER set to PROCESS_STDIO_APP.
prop.Process.STDERR_POINTER: a non-blocking IOStream that can be used to read error output from the process, if it was created with prop.Process.Create.STDERR_NUMBER set to PROCESS_STDIO_APP.
prop.Process.BACKGROUND_BOOLEAN: true if the process is running in the background.

Returns: a valid property ID on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: CreateProcess; CreateProcessWithProperties

◆ Kill()

void SDL::Process::Kill ( bool force )

inline

Stop a process.

Parameters

force true to terminate the process immediately, false to try to stop the process gracefully. In general you should try to stop the process gracefully first as terminating a process may leave it with half-written data or in some other unstable state.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: CreateProcess; CreateProcessWithProperties; Process.Wait; Process.Destroy

◆ KillProcess()

void SDL::KillProcess	(	ProcessRef	process,
		bool	force )

inline

Stop a process.

Parameters

process	The process to stop.
force	true to terminate the process immediately, false to try to stop the process gracefully. In general you should try to stop the process gracefully first as terminating a process may leave it with half-written data or in some other unstable state.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: CreateProcess; CreateProcessWithProperties; Process.Wait; Process.Destroy

◆ Process() [1/2]

SDL::Process::Process	(	const char const	args,
		bool	pipe_stdio )

inline

Create a new process.

The path to the executable is supplied in args[0]. args[1..N] are additional arguments passed on the command line of the new process, and the argument list should be terminated with a nullptr, e.g.:

const char *args[] = { "myprogram", "argument", nullptr };

Setting pipe_stdio to true is equivalent to setting prop.Process.Create.STDIN_NUMBER and prop.Process.Create.STDOUT_NUMBER to PROCESS_STDIO_APP, and will allow the use of Process.Read() or Process.GetInput() and Process.GetOutput().

See CreateProcessWithProperties() for more details.

Parameters

args	the path and arguments for the new process.
pipe_stdio	true to create pipes to the process's standard input and from the process's standard output, false for the process to have no input and inherit the application's standard output.

Postcondition: the newly created and running process, or nullptr if the process couldn't be created.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: CreateProcessWithProperties; Process.GetProperties; Process.Read; Process.GetInput; Process.GetOutput; Process.Kill; Process.Wait; Process.Destroy

◆ Process() [2/2]

SDL::Process::Process ( PropertiesRef props )

inline

Create a new process with the specified properties.

These are the supported properties:

prop.Process.Create.ARGS_POINTER: an array of strings containing the program to run, any arguments, and a nullptr pointer, e.g. const char *args[] = { "myprogram", "argument", nullptr }. This is a required property.
prop.Process.Create.ENVIRONMENT_POINTER: an Environment pointer. If this property is set, it will be the entire environment for the process, otherwise the current environment is used.
prop.Process.Create.WORKING_DIRECTORY_STRING: a UTF-8 encoded string representing the working directory for the process, defaults to the current working directory.
prop.Process.Create.STDIN_NUMBER: an ProcessIO value describing where standard input for the process comes from, defaults to SDL_PROCESS_STDIO_nullptr.
prop.Process.Create.STDIN_POINTER: an IOStream pointer used for standard input when prop.Process.Create.STDIN_NUMBER is set to PROCESS_STDIO_REDIRECT.
prop.Process.Create.STDOUT_NUMBER: an ProcessIO value describing where standard output for the process goes to, defaults to PROCESS_STDIO_INHERITED.
prop.Process.Create.STDOUT_POINTER: an IOStream pointer used for standard output when prop.Process.Create.STDOUT_NUMBER is set to PROCESS_STDIO_REDIRECT.
prop.Process.Create.STDERR_NUMBER: an ProcessIO value describing where standard error for the process goes to, defaults to PROCESS_STDIO_INHERITED.
prop.Process.Create.STDERR_POINTER: an IOStream pointer used for standard error when prop.Process.Create.STDERR_NUMBER is set to PROCESS_STDIO_REDIRECT.
prop.Process.Create.STDERR_TO_STDOUT_BOOLEAN: true if the error output of the process should be redirected into the standard output of the process. This property has no effect if prop.Process.Create.STDERR_NUMBER is set.
prop.Process.Create.BACKGROUND_BOOLEAN: true if the process should run in the background. In this case the default input and output is SDL_PROCESS_STDIO_nullptr and the exitcode of the process is not available, and will always be 0.
prop.Process.Create.CMDLINE_STRING: a string containing the program to run and any parameters. This string is passed directly to CreateProcess on Windows, and does nothing on other platforms. This property is only important if you want to start programs that does non-standard command-line processing, and in most cases using prop.Process.Create.ARGS_POINTER is sufficient.

On POSIX platforms, wait() and waitpid(-1, ...) should not be called, and SIGCHLD should not be ignored or handled because those would prevent SDL from properly tracking the lifetime of the underlying process. You should use Process.Wait() instead.

Parameters

props the properties to use.

Postcondition: the newly created and running process, or nullptr if the process couldn't be created.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: CreateProcess; Process.GetProperties; Process.Read; Process.GetInput; Process.GetOutput; Process.Kill; Process.Wait; Process.Destroy

◆ Read()

StringResult SDL::Process::Read ( int * exitcode = nullptr )

inline

Read all the output from a process.

If a process was created with I/O enabled, you can use this function to read the output. This function blocks until the process is complete, capturing all output, and providing the process exit code.

The data is allocated with a zero byte at the end (null terminated) for convenience. This extra byte is not included in the value reported via datasize.

The data should be freed with free().

Parameters

exitcode a pointer filled in with the process exit code if the process has exited, may be nullptr.

Returns: the data or nullptr on failure; call GetError() for more information.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: CreateProcess; CreateProcessWithProperties; Process.Destroy

◆ ReadProcess()

StringResult SDL::ReadProcess	(	ProcessRef	process,
		int *	exitcode = nullptr )

inline

Read all the output from a process.

If a process was created with I/O enabled, you can use this function to read the output. This function blocks until the process is complete, capturing all output, and providing the process exit code.

The data is allocated with a zero byte at the end (null terminated) for convenience. This extra byte is not included in the value reported via datasize.

The data should be freed with free().

Parameters

process	The process to read.
exitcode	a pointer filled in with the process exit code if the process has exited, may be nullptr.

Returns: the data or nullptr on failure; call GetError() for more information.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: CreateProcess; CreateProcessWithProperties; Process.Destroy

◆ Wait()

bool SDL::Process::Wait	(	bool	block,
		int *	exitcode )

inline

Wait for a process to finish.

This can be called multiple times to get the status of a process.

The exit code will be the exit code of the process if it terminates normally, a negative signal if it terminated due to a signal, or -255 otherwise. It will not be changed if the process is still running.

If you create a process with standard output piped to the application (pipe_stdio being true) then you should read all of the process output before calling Process.Wait(). If you don't do this the process might be blocked indefinitely waiting for output to be read and Process.Wait() will never return true;

Parameters

block	If true, block until the process finishes; otherwise, report on the process' status.
exitcode	a pointer filled in with the process exit code if the process has exited, may be nullptr.

Returns: true if the process exited, false otherwise.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: CreateProcess; CreateProcessWithProperties; Process.Kill; Process.Destroy

◆ WaitProcess()

bool SDL::WaitProcess	(	ProcessRef	process,
		bool	block,
		int *	exitcode )

inline

Wait for a process to finish.

This can be called multiple times to get the status of a process.

The exit code will be the exit code of the process if it terminates normally, a negative signal if it terminated due to a signal, or -255 otherwise. It will not be changed if the process is still running.

If you create a process with standard output piped to the application (pipe_stdio being true) then you should read all of the process output before calling Process.Wait(). If you don't do this the process might be blocked indefinitely waiting for output to be read and Process.Wait() will never return true;

Parameters

process	The process to wait for.
block	If true, block until the process finishes; otherwise, report on the process' status.
exitcode	a pointer filled in with the process exit code if the process has exited, may be nullptr.

Returns: true if the process exited, false otherwise.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: CreateProcess; CreateProcessWithProperties; Process.Kill; Process.Destroy

Variable Documentation

◆ PROCESS_STDIO_INHERITED

ProcessIO SDL::PROCESS_STDIO_INHERITED

constexpr

Initial value:

=

SDL_PROCESS_STDIO_INHERITED

The I/O stream is inherited from the application.

◆ PROCESS_STDIO_NULL

ProcessIO SDL::PROCESS_STDIO_NULL

constexpr

Initial value:

=

SDL_PROCESS_STDIO_NULL

The I/O stream is ignored.

Namespaces

Classes

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ ProcessIO

◆ ProcessRef

Function Documentation

◆ CreateProcess()

◆ CreateProcessWithProperties()

◆ Destroy()

◆ DestroyProcess()

◆ GetInput()

◆ GetOutput()

◆ GetProcessInput()

◆ GetProcessOutput()

◆ GetProcessProperties()

◆ GetProperties()

◆ Kill()

◆ KillProcess()

◆ Process() [1/2]

◆ Process() [2/2]

◆ Read()

◆ ReadProcess()

◆ Wait()

◆ WaitProcess()

Variable Documentation

◆ PROCESS_STDIO_INHERITED

◆ PROCESS_STDIO_NULL