Process Control

Process control support. More...

Classes
struct	SDL::ProcessRef
	An opaque handle representing a system process. More...
struct	SDL::Process
	Handle to an owned process. More...
struct	SDL::ProcessUnsafe
	Unsafe Handle to process. More...

Typedefs
using	SDL::ProcessShared = ResourceShared< Process >
	Handle to a shared process.
using	SDL::ProcessWeak = ResourceWeak< Process >
	Weak handle to a shared process.
using	SDL::ProcessIO = SDL_ProcessIO
	Description of where standard I/O should be directed when creating a process.

Functions
ProcessShared	SDL::Process::share ()
	Move this process into a ProcessShared.

Variables
constexpr ProcessIO	SDL::PROCESS_STDIO_INHERITED
	The I/O stream is inherited from the application.
constexpr ProcessIO	SDL::PROCESS_STDIO_NULL
	The I/O stream is ignored.
constexpr ProcessIO	SDL::PROCESS_STDIO_APP = SDL_PROCESS_STDIO_APP
	The I/O stream is connected to a new IOStream that the application can read or write.
constexpr ProcessIO	SDL::PROCESS_STDIO_REDIRECT = SDL_PROCESS_STDIO_REDIRECT
	The I/O stream is redirected to an existing IOStream.

Detailed Description

These functions provide a cross-platform way to spawn and manage OS-level processes.

You can create a new subprocess with Process.Create() and optionally read and write to it using ProcessRef.Read() or ProcessRef.GetInput() and ProcessRef.GetOutput(). If more advanced functionality like chaining input between processes is necessary, you can use Process.CreateWithProperties().

You can get the status of a created process with ProcessRef.Wait(), or terminate the process with ProcessRef.Kill().

Don't forget to call Process.Destroy() to clean up, whether the process process was killed, terminated on its own, or is still running!

Typedef Documentation

ProcessIO

using SDL::ProcessIO = typedef SDL_ProcessIO

If a standard I/O stream is set to PROCESS_STDIO_INHERITED, it will go to the same place as the application's I/O stream. This is the default for standard output and standard error.

If a standard I/O stream is set to SDL_PROCESS_STDIO_NULL, it is connected to NUL: on Windows and /dev/null on POSIX systems. This is the default for standard input.

If a standard I/O stream is set to PROCESS_STDIO_APP, it is connected to a new IOStream that is available to the application. Standard input will be available as prop::process.STDIN_POINTER and allows ProcessRef.GetInput(), standard output will be available as prop::process.STDOUT_POINTER and allows ProcessRef.Read() and ProcessRef.GetOutput(), and standard error will be available as prop::process.STDERR_POINTER in the properties for the created process.

If a standard I/O stream is set to PROCESS_STDIO_REDIRECT, it is connected to an existing IOStream provided by the application. Standard input is provided using prop::process.CREATE_STDIN_POINTER, standard output is provided using prop::process.CREATE_STDOUT_POINTER, and standard error is provided using prop::process.CREATE_STDERR_POINTER in the creation properties. These existing streams should be closed by the application once the new process is created.

In order to use an IOStream with PROCESS_STDIO_REDIRECT, it must have prop::IOStream.WINDOWS_HANDLE_POINTER or prop::IOStream.FILE_DESCRIPTOR_NUMBER set. This is true for streams representing files and process I/O.

Since

This enum is available since SDL 3.2.0.

See also

Process.CreateWithProperties

ProcessRef.GetProperties

ProcessRef.Read

ProcessRef.GetInput

ProcessRef.GetOutput

ProcessShared

using SDL::ProcessShared = typedef ResourceShared<Process>

Category:

Resource

See also

ProcessRef

Process

ProcessWeak

using SDL::ProcessWeak = typedef ResourceWeak<Process>

Category:

Resource

See also

ProcessShared

ProcessRef

Variable Documentation

PROCESS_STDIO_INHERITED

constexpr ProcessIO SDL::PROCESS_STDIO_INHERITED

constexpr

Initial value:

=
  SDL_PROCESS_STDIO_INHERITED

PROCESS_STDIO_NULL

constexpr ProcessIO SDL::PROCESS_STDIO_NULL

constexpr

Initial value:

=
  SDL_PROCESS_STDIO_NULL