SDL 3.0
SDL_process.h
Go to the documentation of this file.
1/*
2 Simple DirectMedia Layer
3 Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
4
5 This software is provided 'as-is', without any express or implied
6 warranty. In no event will the authors be held liable for any damages
7 arising from the use of this software.
8
9 Permission is granted to anyone to use this software for any purpose,
10 including commercial applications, and to alter it and redistribute it
11 freely, subject to the following restrictions:
12
13 1. The origin of this software must not be misrepresented; you must not
14 claim that you wrote the original software. If you use this software
15 in a product, an acknowledgment in the product documentation would be
16 appreciated but is not required.
17 2. Altered source versions must be plainly marked as such, and must not be
18 misrepresented as being the original software.
19 3. This notice may not be removed or altered from any source distribution.
20*/
21
22/**
23 * # CategoryProcess
24 *
25 * Process control support.
26 *
27 * These functions provide a cross-platform way to spawn and manage OS-level
28 * processes.
29 *
30 * You can create a new subprocess with SDL_CreateProcess() and optionally
31 * read and write to it using SDL_ReadProcess() or SDL_GetProcessInput() and
32 * SDL_GetProcessOutput(). If more advanced functionality like chaining input
33 * between processes is necessary, you can use
34 * SDL_CreateProcessWithProperties().
35 *
36 * You can get the status of a created process with SDL_WaitProcess(), or
37 * terminate the process with SDL_KillProcess().
38 *
39 * Don't forget to call SDL_DestroyProcess() to clean up, whether the process
40 * process was killed, terminated on its own, or is still running!
41 */
42
43#ifndef SDL_process_h_
44#define SDL_process_h_
45
46#include <SDL3/SDL_stdinc.h>
47#include <SDL3/SDL_error.h>
48#include <SDL3/SDL_iostream.h>
49#include <SDL3/SDL_properties.h>
50
51#include <SDL3/SDL_begin_code.h>
52/* Set up for C function definitions, even when using C++ */
53#ifdef __cplusplus
54extern "C" {
55#endif
56
57typedef struct SDL_Process SDL_Process;
58
59/**
60 * Create a new process.
61 *
62 * The path to the executable is supplied in args[0]. args[1..N] are
63 * additional arguments passed on the command line of the new process, and the
64 * argument list should be terminated with a NULL, e.g.:
65 *
66 * ```c
67 * const char *args[] = { "myprogram", "argument", NULL };
68 * ```
69 *
70 * Setting pipe_stdio to true is equivalent to setting
71 * `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` and
72 * `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` to `SDL_PROCESS_STDIO_APP`, and
73 * will allow the use of SDL_ReadProcess() or SDL_GetProcessInput() and
74 * SDL_GetProcessOutput().
75 *
76 * See SDL_CreateProcessWithProperties() for more details.
77 *
78 * \param args the path and arguments for the new process.
79 * \param pipe_stdio true to create pipes to the process's standard input and
80 * from the process's standard output, false for the process
81 * to have no input and inherit the application's standard
82 * output.
83 * \returns the newly created and running process, or NULL if the process
84 * couldn't be created.
85 *
86 * \threadsafety It is safe to call this function from any thread.
87 *
88 * \since This function is available since SDL 3.1.3.
89 *
90 * \sa SDL_CreateProcessWithProperties
91 * \sa SDL_GetProcessProperties
92 * \sa SDL_ReadProcess
93 * \sa SDL_GetProcessInput
94 * \sa SDL_GetProcessOutput
95 * \sa SDL_KillProcess
96 * \sa SDL_WaitProcess
97 * \sa SDL_DestroyProcess
98 */
99extern SDL_DECLSPEC SDL_Process *SDLCALL SDL_CreateProcess(const char * const *args, bool pipe_stdio);
100
101/**
102 * Description of where standard I/O should be directed when creating a
103 * process.
104 *
105 * If a standard I/O stream is set to SDL_PROCESS_STDIO_INHERIT, it will go to
106 * the same place as the application's I/O stream. This is the default for
107 * standard output and standard error.
108 *
109 * If a standard I/O stream is set to SDL_PROCESS_STDIO_NULL, it is connected
110 * to `NUL:` on Windows and `/dev/null` on POSIX systems. This is the default
111 * for standard input.
112 *
113 * If a standard I/O stream is set to SDL_PROCESS_STDIO_APP, it is connected
114 * to a new SDL_IOStream that is available to the application. Standard input
115 * will be available as `SDL_PROP_PROCESS_STDIN_POINTER` and allows
116 * SDL_GetProcessInput(), standard output will be available as
117 * `SDL_PROP_PROCESS_STDOUT_POINTER` and allows SDL_ReadProcess() and
118 * SDL_GetProcessOutput(), and standard error will be available as
119 * `SDL_PROP_PROCESS_STDERR_POINTER` in the properties for the created
120 * process.
121 *
122 * If a standard I/O stream is set to SDL_PROCESS_STDIO_REDIRECT, it is
123 * connected to an existing SDL_IOStream provided by the application. Standard
124 * input is provided using `SDL_PROP_PROCESS_CREATE_STDIN_POINTER`, standard
125 * output is provided using `SDL_PROP_PROCESS_CREATE_STDOUT_POINTER`, and
126 * standard error is provided using `SDL_PROP_PROCESS_CREATE_STDERR_POINTER`
127 * in the creation properties. These existing streams should be closed by the
128 * application once the new process is created.
129 *
130 * In order to use an SDL_IOStream with SDL_PROCESS_STDIO_REDIRECT, it must
131 * have `SDL_PROP_IOSTREAM_WINDOWS_HANDLE_POINTER` or
132 * `SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER` set. This is true for streams
133 * representing files and process I/O.
134 *
135 * \since This enum is available since SDL 3.1.3.
136 *
137 * \sa SDL_CreateProcessWithProperties
138 * \sa SDL_GetProcessProperties
139 * \sa SDL_ReadProcess
140 * \sa SDL_GetProcessInput
141 * \sa SDL_GetProcessOutput
142 */
143typedef enum SDL_ProcessIO
144{
145 SDL_PROCESS_STDIO_INHERITED, /**< The I/O stream is inherited from the application. */
146 SDL_PROCESS_STDIO_NULL, /**< The I/O stream is ignored. */
147 SDL_PROCESS_STDIO_APP, /**< The I/O stream is connected to a new SDL_IOStream that the application can read or write */
148 SDL_PROCESS_STDIO_REDIRECT /**< The I/O stream is redirected to an existing SDL_IOStream. */
150
151/**
152 * Create a new process with the specified properties.
153 *
154 * These are the supported properties:
155 *
156 * - `SDL_PROP_PROCESS_CREATE_ARGS_POINTER`: an array of strings containing
157 * the program to run, any arguments, and a NULL pointer, e.g. const char
158 * *args[] = { "myprogram", "argument", NULL }. This is a required property.
159 * - `SDL_PROP_PROCESS_CREATE_ENVIRONMENT_POINTER`: an SDL_Environment
160 * pointer. If this property is set, it will be the entire environment for
161 * the process, otherwise the current environment is used.
162 * - `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER`: an SDL_ProcessIO value describing
163 * where standard input for the process comes from, defaults to
164 * `SDL_PROCESS_STDIO_NULL`.
165 * - `SDL_PROP_PROCESS_CREATE_STDIN_POINTER`: an SDL_IOStream pointer used for
166 * standard input when `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` is set to
167 * `SDL_PROCESS_STDIO_REDIRECT`.
168 * - `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER`: an SDL_ProcessIO value
169 * describing where standard output for the process goes go, defaults to
170 * `SDL_PROCESS_STDIO_INHERITED`.
171 * - `SDL_PROP_PROCESS_CREATE_STDOUT_POINTER`: an SDL_IOStream pointer used
172 * for standard output when `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` is set
173 * to `SDL_PROCESS_STDIO_REDIRECT`.
174 * - `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER`: an SDL_ProcessIO value
175 * describing where standard error for the process goes go, defaults to
176 * `SDL_PROCESS_STDIO_INHERITED`.
177 * - `SDL_PROP_PROCESS_CREATE_STDERR_POINTER`: an SDL_IOStream pointer used
178 * for standard error when `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER` is set to
179 * `SDL_PROCESS_STDIO_REDIRECT`.
180 * - `SDL_PROP_PROCESS_CREATE_STDERR_TO_STDOUT_BOOLEAN`: true if the error
181 * output of the process should be redirected into the standard output of
182 * the process. This property has no effect if
183 * `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER` is set.
184 * - `SDL_PROP_PROCESS_CREATE_BACKGROUND_BOOLEAN`: true if the process should
185 * run in the background. In this case the default input and output is
186 * `SDL_PROCESS_STDIO_NULL` and the exitcode of the process is not
187 * available, and will always be 0.
188 *
189 * On POSIX platforms, wait() and waitpid(-1, ...) should not be called, and
190 * SIGCHLD should not be ignored or handled because those would prevent SDL
191 * from properly tracking the lifetime of the underlying process. You should
192 * use SDL_WaitProcess() instead.
193 *
194 * \param props the properties to use.
195 * \returns the newly created and running process, or NULL if the process
196 * couldn't be created.
197 *
198 * \threadsafety It is safe to call this function from any thread.
199 *
200 * \since This function is available since SDL 3.1.3.
201 *
202 * \sa SDL_CreateProcess
203 * \sa SDL_GetProcessProperties
204 * \sa SDL_ReadProcess
205 * \sa SDL_GetProcessInput
206 * \sa SDL_GetProcessOutput
207 * \sa SDL_KillProcess
208 * \sa SDL_WaitProcess
209 * \sa SDL_DestroyProcess
210 */
212
213#define SDL_PROP_PROCESS_CREATE_ARGS_POINTER "SDL.process.create.args"
214#define SDL_PROP_PROCESS_CREATE_ENVIRONMENT_POINTER "SDL.process.create.environment"
215#define SDL_PROP_PROCESS_CREATE_STDIN_NUMBER "SDL.process.create.stdin_option"
216#define SDL_PROP_PROCESS_CREATE_STDIN_POINTER "SDL.process.create.stdin_source"
217#define SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER "SDL.process.create.stdout_option"
218#define SDL_PROP_PROCESS_CREATE_STDOUT_POINTER "SDL.process.create.stdout_source"
219#define SDL_PROP_PROCESS_CREATE_STDERR_NUMBER "SDL.process.create.stderr_option"
220#define SDL_PROP_PROCESS_CREATE_STDERR_POINTER "SDL.process.create.stderr_source"
221#define SDL_PROP_PROCESS_CREATE_STDERR_TO_STDOUT_BOOLEAN "SDL.process.create.stderr_to_stdout"
222#define SDL_PROP_PROCESS_CREATE_BACKGROUND_BOOLEAN "SDL.process.create.background"
223
224/**
225 * Get the properties associated with a process.
226 *
227 * The following read-only properties are provided by SDL:
228 *
229 * - `SDL_PROP_PROCESS_PID_NUMBER`: the process ID of the process.
230 * - `SDL_PROP_PROCESS_STDIN_POINTER`: an SDL_IOStream that can be used to
231 * write input to the process, if it was created with
232 * `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` set to `SDL_PROCESS_STDIO_APP`.
233 * - `SDL_PROP_PROCESS_STDOUT_POINTER`: a non-blocking SDL_IOStream that can
234 * be used to read output from the process, if it was created with
235 * `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` set to `SDL_PROCESS_STDIO_APP`.
236 * - `SDL_PROP_PROCESS_STDERR_POINTER`: a non-blocking SDL_IOStream that can
237 * be used to read error output from the process, if it was created with
238 * `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER` set to `SDL_PROCESS_STDIO_APP`.
239 * - `SDL_PROP_PROCESS_BACKGROUND_BOOLEAN`: true if the process is running in
240 * the background.
241 *
242 * \param process the process to query.
243 * \returns a valid property ID on success or 0 on failure; call
244 * SDL_GetError() for more information.
245 *
246 * \threadsafety It is safe to call this function from any thread.
247 *
248 * \since This function is available since SDL 3.1.3.
249 *
250 * \sa SDL_CreateProcess
251 * \sa SDL_CreateProcessWithProperties
252 */
253extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetProcessProperties(SDL_Process *process);
254
255#define SDL_PROP_PROCESS_PID_NUMBER "SDL.process.pid"
256#define SDL_PROP_PROCESS_STDIN_POINTER "SDL.process.stdin"
257#define SDL_PROP_PROCESS_STDOUT_POINTER "SDL.process.stdout"
258#define SDL_PROP_PROCESS_STDERR_POINTER "SDL.process.stderr"
259#define SDL_PROP_PROCESS_BACKGROUND_BOOLEAN "SDL.process.background"
260
261/**
262 * Read all the output from a process.
263 *
264 * If a process was created with I/O enabled, you can use this function to
265 * read the output. This function blocks until the process is complete,
266 * capturing all output, and providing the process exit code.
267 *
268 * The data is allocated with a zero byte at the end (null terminated) for
269 * convenience. This extra byte is not included in the value reported via
270 * `datasize`.
271 *
272 * The data should be freed with SDL_free().
273 *
274 * \param process The process to read.
275 * \param datasize a pointer filled in with the number of bytes read, may be
276 * NULL.
277 * \param exitcode a pointer filled in with the process exit code if the
278 * process has exited, may be NULL.
279 * \returns the data or NULL on failure; call SDL_GetError() for more
280 * information.
281 *
282 * \threadsafety This function is not thread safe.
283 *
284 * \since This function is available since SDL 3.1.3.
285 *
286 * \sa SDL_CreateProcess
287 * \sa SDL_CreateProcessWithProperties
288 * \sa SDL_DestroyProcess
289 */
290extern SDL_DECLSPEC void * SDLCALL SDL_ReadProcess(SDL_Process *process, size_t *datasize, int *exitcode);
291
292/**
293 * Get the SDL_IOStream associated with process standard input.
294 *
295 * The process must have been created with SDL_CreateProcess() and pipe_stdio
296 * set to true, or with SDL_CreateProcessWithProperties() and
297 * `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` set to `SDL_PROCESS_STDIO_APP`.
298 *
299 * Writing to this stream can return less data than expected if the process
300 * hasn't read its input. It may be blocked waiting for its output to be read,
301 * so if you may need to call SDL_GetOutputStream() and read the output in
302 * parallel with writing input.
303 *
304 * \param process The process to get the input stream for.
305 * \returns the input stream or NULL on failure; call SDL_GetError() for more
306 * information.
307 *
308 * \threadsafety It is safe to call this function from any thread.
309 *
310 * \since This function is available since SDL 3.1.3.
311 *
312 * \sa SDL_CreateProcess
313 * \sa SDL_CreateProcessWithProperties
314 * \sa SDL_GetProcessOutput
315 */
316extern SDL_DECLSPEC SDL_IOStream *SDLCALL SDL_GetProcessInput(SDL_Process *process);
317
318/**
319 * Get the SDL_IOStream associated with process standard output.
320 *
321 * The process must have been created with SDL_CreateProcess() and pipe_stdio
322 * set to true, or with SDL_CreateProcessWithProperties() and
323 * `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` set to `SDL_PROCESS_STDIO_APP`.
324 *
325 * Reading from this stream can return 0 with SDL_GetIOStatus() returning
326 * SDL_IO_STATUS_NOT_READY if no output is available yet.
327 *
328 * \param process The process to get the output stream for.
329 * \returns the output stream or NULL on failure; call SDL_GetError() for more
330 * information.
331 *
332 * \threadsafety It is safe to call this function from any thread.
333 *
334 * \since This function is available since SDL 3.1.3.
335 *
336 * \sa SDL_CreateProcess
337 * \sa SDL_CreateProcessWithProperties
338 * \sa SDL_GetProcessInput
339 */
340extern SDL_DECLSPEC SDL_IOStream *SDLCALL SDL_GetProcessOutput(SDL_Process *process);
341
342/**
343 * Stop a process.
344 *
345 * \param process The process to stop.
346 * \param force true to terminate the process immediately, false to try to
347 * stop the process gracefully. In general you should try to stop
348 * the process gracefully first as terminating a process may
349 * leave it with half-written data or in some other unstable
350 * state.
351 * \returns true on success or false on failure; call SDL_GetError() for more
352 * information.
353 *
354 * \threadsafety This function is not thread safe.
355 *
356 * \since This function is available since SDL 3.1.3.
357 *
358 * \sa SDL_CreateProcess
359 * \sa SDL_CreateProcessWithProperties
360 * \sa SDL_WaitProcess
361 * \sa SDL_DestroyProcess
362 */
363extern SDL_DECLSPEC bool SDLCALL SDL_KillProcess(SDL_Process *process, bool force);
364
365/**
366 * Wait for a process to finish.
367 *
368 * This can be called multiple times to get the status of a process.
369 *
370 * The exit code will be the exit code of the process if it terminates
371 * normally, a negative signal if it terminated due to a signal, or -255
372 * otherwise. It will not be changed if the process is still running.
373 *
374 * \param process The process to wait for.
375 * \param block If true, block until the process finishes; otherwise, report
376 * on the process' status.
377 * \param exitcode a pointer filled in with the process exit code if the
378 * process has exited, may be NULL.
379 * \returns true if the process exited, false otherwise.
380 *
381 * \threadsafety This function is not thread safe.
382 *
383 * \since This function is available since SDL 3.1.3.
384 *
385 * \sa SDL_CreateProcess
386 * \sa SDL_CreateProcessWithProperties
387 * \sa SDL_KillProcess
388 * \sa SDL_DestroyProcess
389 */
390extern SDL_DECLSPEC bool SDLCALL SDL_WaitProcess(SDL_Process *process, bool block, int *exitcode);
391
392/**
393 * Destroy a previously created process object.
394 *
395 * Note that this does not stop the process, just destroys the SDL object used
396 * to track it. If you want to stop the process you should use
397 * SDL_KillProcess().
398 *
399 * \param process The process object to destroy.
400 *
401 * \threadsafety This function is not thread safe.
402 *
403 * \since This function is available since SDL 3.1.3.
404 *
405 * \sa SDL_CreateProcess
406 * \sa SDL_CreateProcessWithProperties
407 * \sa SDL_KillProcess
408 */
409extern SDL_DECLSPEC void SDLCALL SDL_DestroyProcess(SDL_Process *process);
410
411/* Ends C function definitions when using C++ */
412#ifdef __cplusplus
413}
414#endif
415#include <SDL3/SDL_close_code.h>
416
417#endif /* SDL_process_h_ */
struct SDL_IOStream SDL_IOStream
Definition: SDL_iostream.h:182
SDL_IOStream * SDL_GetProcessInput(SDL_Process *process)
bool SDL_KillProcess(SDL_Process *process, bool force)
SDL_Process * SDL_CreateProcess(const char *const *args, bool pipe_stdio)
SDL_Process * SDL_CreateProcessWithProperties(SDL_PropertiesID props)
void SDL_DestroyProcess(SDL_Process *process)
void * SDL_ReadProcess(SDL_Process *process, size_t *datasize, int *exitcode)
SDL_IOStream * SDL_GetProcessOutput(SDL_Process *process)
bool SDL_WaitProcess(SDL_Process *process, bool block, int *exitcode)
SDL_PropertiesID SDL_GetProcessProperties(SDL_Process *process)
struct SDL_Process SDL_Process
Definition: SDL_process.h:57
SDL_ProcessIO
Definition: SDL_process.h:144
@ SDL_PROCESS_STDIO_APP
Definition: SDL_process.h:147
@ SDL_PROCESS_STDIO_INHERITED
Definition: SDL_process.h:145
@ SDL_PROCESS_STDIO_REDIRECT
Definition: SDL_process.h:148
@ SDL_PROCESS_STDIO_NULL
Definition: SDL_process.h:146
Uint32 SDL_PropertiesID