SDL::ProcessRef Struct Reference

Handle to a non owned process. More...

Inheritance diagram for SDL::ProcessRef:

Public Member Functions
constexpr	ProcessRef (const ProcessRef &other)
	Copy constructor.
constexpr	ProcessRef (ProcessRef &&other)
	Move constructor.
constexpr	~ProcessRef ()=default
	Default constructor.
ProcessRef &	operator= (ProcessRef other)
	Assignment operator.
void	reset (SDL_Process *newResource={})
	Destroy a previously created process object.
	ProcessBase (const char *const *args, bool pipe_stdio)
	Create a new process.
	ProcessBase (PropertiesBase &props)
	Create a new process with the specified properties.
Public Member Functions inherited from SDL::ProcessBase
	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

Category:

Resource

See also

ProcessBase

Process

Member Function 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

reset()

void SDL::ProcessRef::reset ( SDL_Process *  newResource = {} )

inline

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

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

---

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

• SDL3pp/SDL3pp_process.h