SDL::ProcessRef Struct Reference

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

Inheritance diagram for SDL::ProcessRef:

Public Member Functions
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 IOStreamRef associated with process standard input.
IOStreamRef	GetOutput ()
	Get the IOStreamRef 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 from the underlying resource.
constexpr	Resource (const ResourceHandle< Resource< T > > auto &resource)
	Constructs from pointer like.
constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.
constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.
Public Member Functions inherited from SDL::Resource< SDL_Process * >
constexpr	Resource (SDL_Process * resource={})
	Constructs from the underlying resource.
constexpr	Resource (const ResourceHandle< Resource< SDL_Process * > > auto &resource)
	Constructs from pointer like.
constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.
constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.
constexpr	operator bool () const
	True if contains a valid resource.
constexpr	operator value_type () const
	Converts back to underlying type.
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 const SDL_Process *	operator-> () const
	Access to fields.
constexpr SDL_Process *	operator-> ()
	Access to fields.

Static Public Member Functions
static void	reset (SDL_Process *resource)
	Destroy a previously created process object.

Additional Inherited Members
Public Types inherited from SDL::Resource< SDL_Process * >
using	value_type = SDL_Process *
	The raw resource type.

Detailed Description

Since

This datatype is available since SDL 3.2.0.

Category:

Resource

See also

Process

Process.Create

Member Function Documentation

GetInput()

IOStreamRef SDL::ProcessRef::GetInput ( )

inline

The process must have been created with Process.Create() and pipe_stdio set to true, or with Process.CreateWithProperties() 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 ProcessRef.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

Process.Create

Process.CreateWithProperties

ProcessRef.GetOutput

GetOutput()

IOStreamRef SDL::ProcessRef::GetOutput ( )

inline

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

Reading from this stream can return 0 with IOStreamRef.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

Process.Create

Process.CreateWithProperties

ProcessRef.GetInput

GetProperties()

PropertiesRef SDL::ProcessRef::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 IOStreamRef 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 IOStreamRef 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 IOStreamRef 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

Process.Create

Process.CreateWithProperties

Kill()

void SDL::ProcessRef::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

Process.Create

Process.CreateWithProperties

ProcessRef.Wait

Process.Destroy

Read()

StringResult SDL::ProcessRef::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

Process.Create

Process.Destroy

ReadAs()

template<class T >

OwnArray< T > SDL::ProcessRef::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

ProcessRef.Create

reset()

static void SDL::ProcessRef::reset ( SDL_Process *  resource )

inlinestatic

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 ProcessRef.Kill().

Parameters

resource

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

Process.Create

Process.CreateWithProperties

ProcessRef.Kill

Wait()

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

Process.Create

Process.CreateWithProperties

ProcessRef.Kill

Process.Destroy

---

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

• SDL3pp/SDL3pp_process.h