SDL::Process Class Reference

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

Inheritance diagram for SDL::Process:

Public Member Functions
constexpr	Process ()=default
	Default ctor.
constexpr	Process (const ProcessRaw resource)
	Constructs from ProcessParam. More...
constexpr	Process (const Process &other)=delete
	Copy constructor.
constexpr	Process (Process &&other)
	Move constructor.
constexpr	Process (const ProcessRef &other)=delete
constexpr	Process (ProcessRef &&other)=delete
	Process (const char *const *args, bool pipe_stdio)
	Create a new process. More...
	Process (PropertiesParam props)
	Create a new process with the specified properties. More...
	~Process ()
	Destructor.
Process &	operator= (Process other)
	Assignment operator.
constexpr ProcessRaw	get () const
	Retrieves underlying ProcessRaw.
constexpr ProcessRaw	release ()
	Retrieves underlying ProcessRaw and clear this.
constexpr auto	operator<=> (const Process &other) const =default
	Comparison.
constexpr bool	operator== (std::nullptr_t _) const
	Comparison.
constexpr	operator bool () const
	Converts to bool.
constexpr	operator ProcessParam () const
	Converts to ProcessParam.
void	Destroy ()
	Destroy a previously created process object. More...
PropertiesRef	GetProperties () const
	Get the properties associated with a process. More...
StringResult	Read (int *exitcode=nullptr)
	Read all the output from a process. More...
template<class T >
OwnArray< T >	ReadAs (int *exitcode=nullptr)
	Read all the output from a process. More...
IOStreamRef	GetInput ()
	Get the IOStream associated with process standard input. More...
IOStreamRef	GetOutput ()
	Get the IOStream associated with process standard output. More...
void	Kill (bool force)
	Stop a process. More...
bool	Wait (bool block, int *exitcode)
	Wait for a process to finish. More...

Detailed Description

Since

This datatype is available since SDL 3.2.0.

See also

Process.Process

Category:

Resource

Constructor & Destructor Documentation

Process() [1/3]

constexpr SDL::Process::Process ( const ProcessRaw  resource )

inlineexplicitconstexpr

Parameters

resource

a ProcessRaw to be wrapped.

This assumes the ownership, call release() if you need to take back.

Process() [2/3]

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

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

Process.Process

Process.GetProperties

Process.Read

Process.GetInput

Process.GetOutput

Process.Kill

Process.Wait

Process.Destroy

Process() [3/3]

SDL::Process::Process ( PropertiesParam  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 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_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.

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

Process.Process

Process.GetProperties

Process.Read

Process.GetInput

Process.GetOutput

Process.Kill

Process.Wait

Process.Destroy

Member Function Documentation

ReadAs()

template<class T >

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

---

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

• SDL3pp/SDL3pp_process.h