SDL_process.h File Reference
`#include <SDL3/SDL_stdinc.h>`
`#include <SDL3/SDL_error.h>`
`#include <SDL3/SDL_iostream.h>`
`#include <SDL3/SDL_properties.h>`
`#include <SDL3/SDL_begin_code.h>`
`#include <SDL3/SDL_close_code.h>`
Include dependency graph for SDL_process.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Macros

#define | SDL_PROP_PROCESS_CREATE_ARGS_POINTER "SDL.process.create.args"
#define | SDL_PROP_PROCESS_CREATE_ENVIRONMENT_POINTER "SDL.process.create.environment"
#define | SDL_PROP_PROCESS_CREATE_STDIN_NUMBER "SDL.process.create.stdin_option"
#define | SDL_PROP_PROCESS_CREATE_STDIN_POINTER "SDL.process.create.stdin_source"
#define | SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER "SDL.process.create.stdout_option"
#define | SDL_PROP_PROCESS_CREATE_STDOUT_POINTER "SDL.process.create.stdout_source"
#define | SDL_PROP_PROCESS_CREATE_STDERR_NUMBER "SDL.process.create.stderr_option"
#define | SDL_PROP_PROCESS_CREATE_STDERR_POINTER "SDL.process.create.stderr_source"
#define | SDL_PROP_PROCESS_CREATE_STDERR_TO_STDOUT_BOOLEAN "SDL.process.create.stderr_to_stdout"
#define | SDL_PROP_PROCESS_CREATE_BACKGROUND_BOOLEAN "SDL.process.create.background"
#define | SDL_PROP_PROCESS_PID_NUMBER "SDL.process.pid"
#define | SDL_PROP_PROCESS_STDIN_POINTER "SDL.process.stdin"
#define | SDL_PROP_PROCESS_STDOUT_POINTER "SDL.process.stdout"
#define | SDL_PROP_PROCESS_STDERR_POINTER "SDL.process.stderr"
#define | SDL_PROP_PROCESS_BACKGROUND_BOOLEAN "SDL.process.background"

## Typedefs

typedef struct SDL_Process | SDL_Process

## Enumerations

enum | SDL_ProcessIO { SDL_PROCESS_STDIO_INHERITED , SDL_PROCESS_STDIO_NULL , SDL_PROCESS_STDIO_APP , SDL_PROCESS_STDIO_REDIRECT }

## Functions

SDL_Process * | SDL_CreateProcess (const char *const *args, bool pipe_stdio)
SDL_Process * | SDL_CreateProcessWithProperties (SDL_PropertiesID props)
SDL_PropertiesID | SDL_GetProcessProperties (SDL_Process *process)
void * | SDL_ReadProcess (SDL_Process *process, size_t *datasize, int *exitcode)
SDL_IOStream * | SDL_GetProcessInput (SDL_Process *process)
SDL_IOStream * | SDL_GetProcessOutput (SDL_Process *process)
bool | SDL_KillProcess (SDL_Process *process, bool force)
bool | SDL_WaitProcess (SDL_Process *process, bool block, int *exitcode)
void | SDL_DestroyProcess (SDL_Process *process)

## Macro Definition Documentation

## SDL_PROP_PROCESS_BACKGROUND_BOOLEAN

#define SDL_PROP_PROCESS_BACKGROUND_BOOLEAN "SDL.process.background"

Definition at line 266 of file SDL_process.h.

## SDL_PROP_PROCESS_CREATE_ARGS_POINTER

#define SDL_PROP_PROCESS_CREATE_ARGS_POINTER "SDL.process.create.args"

Definition at line 220 of file SDL_process.h.

## SDL_PROP_PROCESS_CREATE_BACKGROUND_BOOLEAN

#define SDL_PROP_PROCESS_CREATE_BACKGROUND_BOOLEAN "SDL.process.create.background"

Definition at line 229 of file SDL_process.h.

## SDL_PROP_PROCESS_CREATE_ENVIRONMENT_POINTER

#define SDL_PROP_PROCESS_CREATE_ENVIRONMENT_POINTER "SDL.process.create.environment"

Definition at line 221 of file SDL_process.h.

## SDL_PROP_PROCESS_CREATE_STDERR_NUMBER

#define SDL_PROP_PROCESS_CREATE_STDERR_NUMBER "SDL.process.create.stderr_option"

Definition at line 226 of file SDL_process.h.

## SDL_PROP_PROCESS_CREATE_STDERR_POINTER

#define SDL_PROP_PROCESS_CREATE_STDERR_POINTER "SDL.process.create.stderr_source"

Definition at line 227 of file SDL_process.h.

## SDL_PROP_PROCESS_CREATE_STDERR_TO_STDOUT_BOOLEAN

#define SDL_PROP_PROCESS_CREATE_STDERR_TO_STDOUT_BOOLEAN "SDL.process.create.stderr_to_stdout"

Definition at line 228 of file SDL_process.h.

## SDL_PROP_PROCESS_CREATE_STDIN_NUMBER

#define SDL_PROP_PROCESS_CREATE_STDIN_NUMBER "SDL.process.create.stdin_option"

Definition at line 222 of file SDL_process.h.

## SDL_PROP_PROCESS_CREATE_STDIN_POINTER

#define SDL_PROP_PROCESS_CREATE_STDIN_POINTER "SDL.process.create.stdin_source"

Definition at line 223 of file SDL_process.h.

## SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER

#define SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER "SDL.process.create.stdout_option"

Definition at line 224 of file SDL_process.h.

## SDL_PROP_PROCESS_CREATE_STDOUT_POINTER

#define SDL_PROP_PROCESS_CREATE_STDOUT_POINTER "SDL.process.create.stdout_source"

Definition at line 225 of file SDL_process.h.

## SDL_PROP_PROCESS_PID_NUMBER

#define SDL_PROP_PROCESS_PID_NUMBER "SDL.process.pid"

Definition at line 262 of file SDL_process.h.

## SDL_PROP_PROCESS_STDERR_POINTER

#define SDL_PROP_PROCESS_STDERR_POINTER "SDL.process.stderr"

Definition at line 265 of file SDL_process.h.

## SDL_PROP_PROCESS_STDIN_POINTER

#define SDL_PROP_PROCESS_STDIN_POINTER "SDL.process.stdin"

Definition at line 263 of file SDL_process.h.

## SDL_PROP_PROCESS_STDOUT_POINTER

#define SDL_PROP_PROCESS_STDOUT_POINTER "SDL.process.stdout"

Definition at line 264 of file SDL_process.h.

## Typedef Documentation

## SDL_Process

typedef struct SDL_Process SDL_Process

# CategoryProcess

Process control support.

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

You can create a new subprocess with SDL_CreateProcess() and optionally read and write to it using SDL_ReadProcess() or SDL_GetProcessInput() and SDL_GetProcessOutput(). If more advanced functionality like chaining input between processes is necessary, you can use SDL_CreateProcessWithProperties().

You can get the status of a created process with SDL_WaitProcess(), or terminate the process with SDL_KillProcess().

Don't forget to call SDL_DestroyProcess() to clean up, whether the process process was killed, terminated on its own, or is still running! An opaque handle representing a system process.

Since
  This datatype is available since SDL 3.2.0.

See also
  SDL_CreateProcess

Definition at line 64 of file SDL_process.h.

## Enumeration Type Documentation

## SDL_ProcessIO

enum SDL_ProcessIO

Description of where standard I/O should be directed when creating a process.

If a standard I/O stream is set to SDL_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 SDL_PROCESS_STDIO_APP, it is connected to a new SDL_IOStream that is available to the application. Standard input will be available as `SDL_PROP_PROCESS_STDIN_POINTER` and allows SDL_GetProcessInput(), standard output will be available as `SDL_PROP_PROCESS_STDOUT_POINTER` and allows SDL_ReadProcess() and SDL_GetProcessOutput(), and standard error will be available as `SDL_PROP_PROCESS_STDERR_POINTER` in the properties for the created process.

If a standard I/O stream is set to SDL_PROCESS_STDIO_REDIRECT, it is connected to an existing SDL_IOStream provided by the application. Standard input is provided using `SDL_PROP_PROCESS_CREATE_STDIN_POINTER`, standard output is provided using `SDL_PROP_PROCESS_CREATE_STDOUT_POINTER`, and standard error is provided using `SDL_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 SDL_IOStream with SDL_PROCESS_STDIO_REDIRECT, it must have `SDL_PROP_IOSTREAM_WINDOWS_HANDLE_POINTER` or `SDL_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
  SDL_CreateProcessWithProperties
  SDL_GetProcessProperties
  SDL_ReadProcess
  SDL_GetProcessInput
  SDL_GetProcessOutput

Enumerator
SDL_PROCESS_STDIO_INHERITED | The I/O stream is inherited from the application.
SDL_PROCESS_STDIO_NULL | The I/O stream is ignored.
SDL_PROCESS_STDIO_APP | The I/O stream is connected to a new SDL_IOStream that the application can read or write
SDL_PROCESS_STDIO_REDIRECT | The I/O stream is redirected to an existing SDL_IOStream.

Definition at line 150 of file SDL_process.h.

{
SDL_PROCESS_STDIO_INHERITED, /**< The I/O stream is inherited from the application. */
SDL_PROCESS_STDIO_NULL, /**< The I/O stream is ignored. */
SDL_PROCESS_STDIO_APP, /**< The I/O stream is connected to a new SDL_IOStream that the application can read or write */
SDL_PROCESS_STDIO_REDIRECT /**< The I/O stream is redirected to an existing SDL_IOStream. */
} SDL_ProcessIO;
SDL_ProcessIO
SDL_ProcessIO
Definition SDL_process.h:151
SDL_PROCESS_STDIO_APP
@ SDL_PROCESS_STDIO_APP
Definition SDL_process.h:154
SDL_PROCESS_STDIO_INHERITED
@ SDL_PROCESS_STDIO_INHERITED
Definition SDL_process.h:152
SDL_PROCESS_STDIO_REDIRECT
@ SDL_PROCESS_STDIO_REDIRECT
Definition SDL_process.h:155
SDL_PROCESS_STDIO_NULL
@ SDL_PROCESS_STDIO_NULL
Definition SDL_process.h:153

## Function Documentation

## SDL_CreateProcess()

SDL_Process * SDL_CreateProcess | ( | const char *const * | args,
|  | bool | pipe_stdio
| ) |  |

extern

Create a new process.

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 NULL, e.g.:

const char *args[] = { "myprogram", "argument", NULL };
NULL
#define NULL
Definition SDL_begin_code.h:417

Setting pipe_stdio to true is equivalent to setting `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` and `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` to `SDL_PROCESS_STDIO_APP`, and will allow the use of SDL_ReadProcess() or SDL_GetProcessInput() and SDL_GetProcessOutput().

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

Returns
  the newly created and running process, or NULL if the process couldn't be created.

\threadsafety It is safe to call this function from any thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_CreateProcessWithProperties
  SDL_GetProcessProperties
  SDL_ReadProcess
  SDL_GetProcessInput
  SDL_GetProcessOutput
  SDL_KillProcess
  SDL_WaitProcess
  SDL_DestroyProcess

## SDL_CreateProcessWithProperties()

SDL_Process * SDL_CreateProcessWithProperties | ( | SDL_PropertiesID | props | ) |

extern

Create a new process with the specified properties.

These are the supported properties:

- `SDL_PROP_PROCESS_CREATE_ARGS_POINTER`: an array of strings containing the program to run, any arguments, and a NULL pointer, e.g. const char *args[] = { "myprogram", "argument", NULL }. This is a required property.
- `SDL_PROP_PROCESS_CREATE_ENVIRONMENT_POINTER`: an SDL_Environment pointer. If this property is set, it will be the entire environment for the process, otherwise the current environment is used.
- `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER`: an SDL_ProcessIO value describing where standard input for the process comes from, defaults to `SDL_PROCESS_STDIO_NULL`.
- `SDL_PROP_PROCESS_CREATE_STDIN_POINTER`: an SDL_IOStream pointer used for standard input when `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` is set to `SDL_PROCESS_STDIO_REDIRECT`.
- `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER`: an SDL_ProcessIO value describing where standard output for the process goes to, defaults to `SDL_PROCESS_STDIO_INHERITED`.
- `SDL_PROP_PROCESS_CREATE_STDOUT_POINTER`: an SDL_IOStream pointer used for standard output when `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` is set to `SDL_PROCESS_STDIO_REDIRECT`.
- `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER`: an SDL_ProcessIO value describing where standard error for the process goes to, defaults to `SDL_PROCESS_STDIO_INHERITED`.
- `SDL_PROP_PROCESS_CREATE_STDERR_POINTER`: an SDL_IOStream pointer used for standard error when `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER` is set to `SDL_PROCESS_STDIO_REDIRECT`.
- `SDL_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 `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER` is set.
- `SDL_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 SDL_WaitProcess() instead.

Parameters

  props | the properties to use.

Returns
  the newly created and running process, or NULL if the process couldn't be created.

\threadsafety It is safe to call this function from any thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_CreateProcess
  SDL_GetProcessProperties
  SDL_ReadProcess
  SDL_GetProcessInput
  SDL_GetProcessOutput
  SDL_KillProcess
  SDL_WaitProcess
  SDL_DestroyProcess

## SDL_DestroyProcess()

void SDL_DestroyProcess | ( | SDL_Process * | process | ) |

extern

Destroy a previously created process object.

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 SDL_KillProcess().

Parameters

  process | The process object to destroy.

\threadsafety This function is not thread safe.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_CreateProcess
  SDL_CreateProcessWithProperties
  SDL_KillProcess

## SDL_GetProcessInput()

SDL_IOStream * SDL_GetProcessInput | ( | SDL_Process * | process | ) |

extern

Get the SDL_IOStream associated with process standard input.

The process must have been created with SDL_CreateProcess() and pipe_stdio set to true, or with SDL_CreateProcessWithProperties() and `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` set to `SDL_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 SDL_GetProcessOutput() and read the output in parallel with writing input.

Parameters

  process | The process to get the input stream for.

Returns
  the input stream or NULL on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_CreateProcess
  SDL_CreateProcessWithProperties
  SDL_GetProcessOutput

## SDL_GetProcessOutput()

SDL_IOStream * SDL_GetProcessOutput | ( | SDL_Process * | process | ) |

extern

Get the SDL_IOStream associated with process standard output.

The process must have been created with SDL_CreateProcess() and pipe_stdio set to true, or with SDL_CreateProcessWithProperties() and `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` set to `SDL_PROCESS_STDIO_APP`.

Reading from this stream can return 0 with SDL_GetIOStatus() returning SDL_IO_STATUS_NOT_READY if no output is available yet.

Parameters

  process | The process to get the output stream for.

Returns
  the output stream or NULL on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_CreateProcess
  SDL_CreateProcessWithProperties
  SDL_GetProcessInput

## SDL_GetProcessProperties()

SDL_PropertiesID SDL_GetProcessProperties | ( | SDL_Process * | process | ) |

extern

Get the properties associated with a process.

The following read-only properties are provided by SDL:

- `SDL_PROP_PROCESS_PID_NUMBER`: the process ID of the process.
- `SDL_PROP_PROCESS_STDIN_POINTER`: an SDL_IOStream that can be used to write input to the process, if it was created with `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` set to `SDL_PROCESS_STDIO_APP`.
- `SDL_PROP_PROCESS_STDOUT_POINTER`: a non-blocking SDL_IOStream that can be used to read output from the process, if it was created with `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` set to `SDL_PROCESS_STDIO_APP`.
- `SDL_PROP_PROCESS_STDERR_POINTER`: a non-blocking SDL_IOStream that can be used to read error output from the process, if it was created with `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER` set to `SDL_PROCESS_STDIO_APP`.
- `SDL_PROP_PROCESS_BACKGROUND_BOOLEAN`: true if the process is running in the background.

Parameters

  process | the process to query.

Returns
  a valid property ID on success or 0 on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_CreateProcess
  SDL_CreateProcessWithProperties

## SDL_KillProcess()

bool SDL_KillProcess | ( | SDL_Process * | process,
|  | bool | force
| ) |  |

extern

Stop a process.

Parameters

  process | The process to stop.
  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.

Returns
  true on success or false on failure; call SDL_GetError() for more information.

\threadsafety This function is not thread safe.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_CreateProcess
  SDL_CreateProcessWithProperties
  SDL_WaitProcess
  SDL_DestroyProcess

## SDL_ReadProcess()

void * SDL_ReadProcess | ( | SDL_Process * | process,
|  | size_t * | datasize,
|  | int * | exitcode
| ) |  |

extern

Read all the output from a process.

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 SDL_free().

Parameters

  process | The process to read.
  datasize | a pointer filled in with the number of bytes read, may be NULL.
  exitcode | a pointer filled in with the process exit code if the process has exited, may be NULL.

Returns
  the data or NULL on failure; call SDL_GetError() for more information.

\threadsafety This function is not thread safe.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_CreateProcess
  SDL_CreateProcessWithProperties
  SDL_DestroyProcess

## SDL_WaitProcess()

bool SDL_WaitProcess | ( | SDL_Process * | process,
|  | bool | block,
|  | int * | exitcode
| ) |  |

extern

Wait for a process to finish.

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 SDL_WaitProcess(). If you don't do this the process might be blocked indefinitely waiting for output to be read and SDL_WaitProcess() will never return true;

Parameters

  process | The process to wait for.
  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 NULL.

Returns
  true if the process exited, false otherwise.

\threadsafety This function is not thread safe.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_CreateProcess
  SDL_CreateProcessWithProperties
  SDL_KillProcess
  SDL_DestroyProcess