An opaque handle representing a system process. More...

Inheritance diagram for SDL::ProcessBase:

[legend]

Public Member Functions
	ProcessBase (const char const args, bool pipe_stdio)
	Create a new process.

	ProcessBase (PropertiesBase &props)
	Create a new process with the specified properties.

PropertiesRef	GetProperties () const
	Get the properties associated with a process.

StringResult	Read (int *exitcode=nullptr)
	Read all the output from a process.

template<class T >
OwnArray< T >	ReadAs (int *exitcode=nullptr)
	Read all the output from a process.

IOStreamRef	GetInput ()
	Get the IOStreamBase associated with process standard input.

IOStreamRef	GetOutput ()
	Get the IOStreamBase associated with process standard output.

void	Kill (bool force)
	Stop a process.

bool	Wait (bool block, int *exitcode)
	Wait for a process to finish.

constexpr	Resource (T resource={})
	Constructs the underlying resource.

constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.

constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.

	Resource (const Resource &other)=delete

	Resource (Resource &&other)=delete

Public Member Functions inherited from SDL::Resource< SDL_Process * >
constexpr	Resource (SDL_Process * resource={})
	Constructs the underlying resource.

constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.

constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.

	Resource (const Resource &other)=delete

	Resource (Resource &&other)=delete

Resource &	operator= (const Resource &other)=delete

Resource &	operator= (Resource &&other)=delete

constexpr	operator bool () const
	True if contains a valid resource.

constexpr bool	operator== (const Resource &other) const=default
	Comparison.

constexpr bool	operator== (std::nullopt_t) const
	Comparison.

constexpr bool	operator== (std::nullptr_t) const
	Comparison.

constexpr SDL_Process *	get () const
	Return contained resource;.

constexpr SDL_Process *	release (SDL_Process * newResource={})
	Return contained resource and empties or replace value.

constexpr const SDL_Process *	operator-> () const
	Access to fields.

constexpr SDL_Process *	operator-> ()
	Access to fields.

Detailed Description

Since: This datatype is available since SDL 3.2.0.

See also: ProcessBase.ProcessBase

Category:: Resource

See also: Process; ProcessRef

Constructor & Destructor Documentation

◆ ProcessBase() [1/2]

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

inline

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 ProcessBase.Read() or ProcessBase.GetInput() and ProcessBase.GetOutput().

See ProcessBase.ProcessBase() 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.

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: ProcessBase.ProcessBase; ProcessBase.GetProperties; ProcessBase.Read; ProcessBase.GetInput; ProcessBase.GetOutput; ProcessBase.Kill; ProcessBase.Wait; ProcessRef.reset

◆ ProcessBase() [2/2]

SDL::ProcessBase::ProcessBase ( PropertiesBase & props )

inline

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 EnvironmentBase pointer. If this property is set, it will be the entire environment for the process, otherwise the current environment is used.
prop::process.CREATE_STDIN_NUMBER: an ProcessIO value describing where standard input for the process comes from, defaults to SDL_PROCESS_STDIO_NULL.
prop::process.CREATE_STDIN_POINTER: an IOStreamBase 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 IOStreamBase 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 IOStreamBase 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_NULL and the exitcode of the process is not available, and will always be 0.

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 ProcessBase.Wait() instead.

Parameters

props the properties to use.

Postcondition: the newly created and running process.

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: ProcessBase.ProcessBase; ProcessBase.GetProperties; ProcessBase.Read; ProcessBase.GetInput; ProcessBase.GetOutput; ProcessBase.Kill; ProcessBase.Wait

Member Function Documentation

◆ GetInput()

IOStreamRef SDL::ProcessBase::GetInput ( )

inline

The process must have been created with ProcessBase.ProcessBase() and pipe_stdio set to true, or with ProcessBase.ProcessBase() 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 ProcessBase.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: ProcessBase.ProcessBase; ProcessBase.ProcessBase; ProcessBase.GetOutput

◆ GetOutput()

IOStreamRef SDL::ProcessBase::GetOutput ( )

inline

The process must have been created with ProcessBase.ProcessBase() and pipe_stdio set to true, or with ProcessBase.ProcessBase() and prop::process.CREATE_STDOUT_NUMBER set to PROCESS_STDIO_APP.

Reading from this stream can return 0 with IOStreamBase.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: ProcessBase.ProcessBase; ProcessBase.ProcessBase; ProcessBase.GetInput

◆ GetProperties()

PropertiesRef SDL::ProcessBase::GetProperties ( ) const

inline

The following read-only properties are provided by SDL:

prop::process.PID_NUMBER: the process ID of the process.
prop::process.STDIN_POINTER: an IOStreamBase 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 IOStreamBase 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 IOStreamBase 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: ProcessBase.ProcessBase

◆ Kill()

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

inline

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: ProcessBase.ProcessBase; ProcessBase.ProcessBase; ProcessBase.Wait; ProcessRef.reset

◆ Read()

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

inline

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 on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: ProcessBase.ProcessBase

◆ ReadAs()

template<class T >

OwnArray< T > SDL::ProcessBase::ReadAs ( int * exitcode = nullptr )

inline

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: ProcessBase.ProcessBase

◆ Wait()

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

inline

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 ProcessBase.Wait(). If you don't do this the process might be blocked indefinitely waiting for output to be read and ProcessBase.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: ProcessBase.ProcessBase; ProcessBase.ProcessBase; ProcessBase.Kill; ProcessRef.reset

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

SDL3pp/SDL3pp_process.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ProcessBase() [1/2]

◆ ProcessBase() [2/2]

Member Function Documentation

◆ GetInput()

◆ GetOutput()

◆ GetProperties()

◆ Kill()

◆ Read()

◆ ReadAs()

◆ Wait()