SDL::ProcessRef Struct Reference

Semi-safe reference for Process.

Inheritance diagram for SDL::ProcessRef:

Collaboration diagram for SDL::ProcessRef:

Public Member Functions
	ProcessRef (ProcessParam resource) noexcept
	Constructs from ProcessParam. More...
	ProcessRef (ProcessRaw resource) noexcept
	Constructs from ProcessParam. More...
constexpr	ProcessRef (const ProcessRef &other) noexcept=default
	Copy constructor.
	~ProcessRef ()
	Destructor.
constexpr	Process (std::nullptr_t=nullptr) noexcept
	Default ctor.
constexpr	Process (const ProcessRaw resource) noexcept
	Constructs from ProcessParam. More...
constexpr	Process (const Process &other) noexcept=default
	Copy constructor.
constexpr	Process (Process &&other) noexcept
	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...
Public Member Functions inherited from SDL::Process
constexpr	Process (std::nullptr_t=nullptr) noexcept
	Default ctor.
constexpr	Process (const ProcessRaw resource) noexcept
	Constructs from ProcessParam. More...
constexpr	Process (Process &&other) noexcept
	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.
constexpr Process &	operator= (Process &&other) noexcept
	Assignment operator.
constexpr ProcessRaw	get () const noexcept
	Retrieves underlying ProcessRaw.
constexpr ProcessRaw	release () noexcept
	Retrieves underlying ProcessRaw and clear this.
constexpr auto	operator<=> (const Process &other) const noexcept=default
	Comparison.
constexpr	operator bool () const noexcept
	Converts to bool.
constexpr	operator ProcessParam () const noexcept
	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...

Additional Inherited Members
Protected Member Functions inherited from SDL::Process
constexpr	Process (const Process &other) noexcept=default
	Copy constructor.
constexpr Process &	operator= (const Process &other) noexcept=default
	Assignment operator.

Constructor & Destructor Documentation

ProcessRef() [1/2]

SDL::ProcessRef::ProcessRef ( ProcessParam  resource )

inlinenoexcept

Parameters

resource

a ProcessRaw or Process.

This does not takes ownership!

ProcessRef() [2/2]

SDL::ProcessRef::ProcessRef ( ProcessRaw  resource )

inlinenoexcept

Parameters

resource

a ProcessRaw or Process.

This does not takes ownership!

Member Function Documentation

Process() [1/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() [2/3]

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

inlineexplicitconstexprnoexcept

Parameters

resource

a ProcessRaw to be wrapped.

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

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_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

Process.Process

Process.GetProperties

Process.Read

Process.GetInput

Process.GetOutput

Process.Kill

Process.Wait

Process.Destroy

---

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

• SDL3pp/SDL3pp_process.h