Atlas - SDL_process.h
Home / ext / SDL / include / SDL3 Lines: 1 | Size: 18490 bytes [Download] [Show on GitHub] [Search similar files] [Raw] [Raw (proxy)][FILE BEGIN]1/* 2 Simple DirectMedia Layer 3 Copyright (C) 1997-2025 Sam Lantinga <[email protected]> 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 57/** 58 * An opaque handle representing a system process. 59 * 60 * \since This datatype is available since SDL 3.2.0. 61 * 62 * \sa SDL_CreateProcess 63 */ 64typedef struct SDL_Process SDL_Process; 65 66/** 67 * Create a new process. 68 * 69 * The path to the executable is supplied in args[0]. args[1..N] are 70 * additional arguments passed on the command line of the new process, and the 71 * argument list should be terminated with a NULL, e.g.: 72 * 73 * ```c 74 * const char *args[] = { "myprogram", "argument", NULL }; 75 * ``` 76 * 77 * Setting pipe_stdio to true is equivalent to setting 78 * `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` and 79 * `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` to `SDL_PROCESS_STDIO_APP`, and 80 * will allow the use of SDL_ReadProcess() or SDL_GetProcessInput() and 81 * SDL_GetProcessOutput(). 82 * 83 * See SDL_CreateProcessWithProperties() for more details. 84 * 85 * \param args the path and arguments for the new process. 86 * \param pipe_stdio true to create pipes to the process's standard input and 87 * from the process's standard output, false for the process 88 * to have no input and inherit the application's standard 89 * output. 90 * \returns the newly created and running process, or NULL if the process 91 * couldn't be created. 92 * 93 * \threadsafety It is safe to call this function from any thread. 94 * 95 * \since This function is available since SDL 3.2.0. 96 * 97 * \sa SDL_CreateProcessWithProperties 98 * \sa SDL_GetProcessProperties 99 * \sa SDL_ReadProcess 100 * \sa SDL_GetProcessInput 101 * \sa SDL_GetProcessOutput 102 * \sa SDL_KillProcess 103 * \sa SDL_WaitProcess 104 * \sa SDL_DestroyProcess 105 */ 106extern SDL_DECLSPEC SDL_Process * SDLCALL SDL_CreateProcess(const char * const *args, bool pipe_stdio); 107 108/** 109 * Description of where standard I/O should be directed when creating a 110 * process. 111 * 112 * If a standard I/O stream is set to SDL_PROCESS_STDIO_INHERITED, it will go 113 * to the same place as the application's I/O stream. This is the default for 114 * standard output and standard error. 115 * 116 * If a standard I/O stream is set to SDL_PROCESS_STDIO_NULL, it is connected 117 * to `NUL:` on Windows and `/dev/null` on POSIX systems. This is the default 118 * for standard input. 119 * 120 * If a standard I/O stream is set to SDL_PROCESS_STDIO_APP, it is connected 121 * to a new SDL_IOStream that is available to the application. Standard input 122 * will be available as `SDL_PROP_PROCESS_STDIN_POINTER` and allows 123 * SDL_GetProcessInput(), standard output will be available as 124 * `SDL_PROP_PROCESS_STDOUT_POINTER` and allows SDL_ReadProcess() and 125 * SDL_GetProcessOutput(), and standard error will be available as 126 * `SDL_PROP_PROCESS_STDERR_POINTER` in the properties for the created 127 * process. 128 * 129 * If a standard I/O stream is set to SDL_PROCESS_STDIO_REDIRECT, it is 130 * connected to an existing SDL_IOStream provided by the application. Standard 131 * input is provided using `SDL_PROP_PROCESS_CREATE_STDIN_POINTER`, standard 132 * output is provided using `SDL_PROP_PROCESS_CREATE_STDOUT_POINTER`, and 133 * standard error is provided using `SDL_PROP_PROCESS_CREATE_STDERR_POINTER` 134 * in the creation properties. These existing streams should be closed by the 135 * application once the new process is created. 136 * 137 * In order to use an SDL_IOStream with SDL_PROCESS_STDIO_REDIRECT, it must 138 * have `SDL_PROP_IOSTREAM_WINDOWS_HANDLE_POINTER` or 139 * `SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER` set. This is true for streams 140 * representing files and process I/O. 141 * 142 * \since This enum is available since SDL 3.2.0. 143 * 144 * \sa SDL_CreateProcessWithProperties 145 * \sa SDL_GetProcessProperties 146 * \sa SDL_ReadProcess 147 * \sa SDL_GetProcessInput 148 * \sa SDL_GetProcessOutput 149 */ 150typedef enum SDL_ProcessIO 151{ 152 SDL_PROCESS_STDIO_INHERITED, /**< The I/O stream is inherited from the application. */ 153 SDL_PROCESS_STDIO_NULL, /**< The I/O stream is ignored. */ 154 SDL_PROCESS_STDIO_APP, /**< The I/O stream is connected to a new SDL_IOStream that the application can read or write */ 155 SDL_PROCESS_STDIO_REDIRECT /**< The I/O stream is redirected to an existing SDL_IOStream. */ 156} SDL_ProcessIO; 157 158/** 159 * Create a new process with the specified properties. 160 * 161 * These are the supported properties: 162 * 163 * - `SDL_PROP_PROCESS_CREATE_ARGS_POINTER`: an array of strings containing 164 * the program to run, any arguments, and a NULL pointer, e.g. const char 165 * *args[] = { "myprogram", "argument", NULL }. This is a required property. 166 * - `SDL_PROP_PROCESS_CREATE_ENVIRONMENT_POINTER`: an SDL_Environment 167 * pointer. If this property is set, it will be the entire environment for 168 * the process, otherwise the current environment is used. 169 * - `SDL_PROP_PROCESS_CREATE_WORKING_DIRECTORY_STRING`: a UTF-8 encoded 170 * string representing the working directory for the process, defaults to 171 * the current working directory. 172 * - `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER`: an SDL_ProcessIO value describing 173 * where standard input for the process comes from, defaults to 174 * `SDL_PROCESS_STDIO_NULL`. 175 * - `SDL_PROP_PROCESS_CREATE_STDIN_POINTER`: an SDL_IOStream pointer used for 176 * standard input when `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` is set to 177 * `SDL_PROCESS_STDIO_REDIRECT`. 178 * - `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER`: an SDL_ProcessIO value 179 * describing where standard output for the process goes to, defaults to 180 * `SDL_PROCESS_STDIO_INHERITED`. 181 * - `SDL_PROP_PROCESS_CREATE_STDOUT_POINTER`: an SDL_IOStream pointer used 182 * for standard output when `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` is set 183 * to `SDL_PROCESS_STDIO_REDIRECT`. 184 * - `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER`: an SDL_ProcessIO value 185 * describing where standard error for the process goes to, defaults to 186 * `SDL_PROCESS_STDIO_INHERITED`. 187 * - `SDL_PROP_PROCESS_CREATE_STDERR_POINTER`: an SDL_IOStream pointer used 188 * for standard error when `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER` is set to 189 * `SDL_PROCESS_STDIO_REDIRECT`. 190 * - `SDL_PROP_PROCESS_CREATE_STDERR_TO_STDOUT_BOOLEAN`: true if the error 191 * output of the process should be redirected into the standard output of 192 * the process. This property has no effect if 193 * `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER` is set. 194 * - `SDL_PROP_PROCESS_CREATE_BACKGROUND_BOOLEAN`: true if the process should 195 * run in the background. In this case the default input and output is 196 * `SDL_PROCESS_STDIO_NULL` and the exitcode of the process is not 197 * available, and will always be 0. 198 * - `SDL_PROP_PROCESS_CREATE_CMDLINE_STRING`: a string containing the program 199 * to run and any parameters. This string is passed directly to 200 * `CreateProcess` on Windows, and does nothing on other platforms. This 201 * property is only important if you want to start programs that does 202 * non-standard command-line processing, and in most cases using 203 * `SDL_PROP_PROCESS_CREATE_ARGS_POINTER` is sufficient. 204 * 205 * On POSIX platforms, wait() and waitpid(-1, ...) should not be called, and 206 * SIGCHLD should not be ignored or handled because those would prevent SDL 207 * from properly tracking the lifetime of the underlying process. You should 208 * use SDL_WaitProcess() instead. 209 * 210 * \param props the properties to use. 211 * \returns the newly created and running process, or NULL if the process 212 * couldn't be created. 213 * 214 * \threadsafety It is safe to call this function from any thread. 215 * 216 * \since This function is available since SDL 3.2.0. 217 * 218 * \sa SDL_CreateProcess 219 * \sa SDL_GetProcessProperties 220 * \sa SDL_ReadProcess 221 * \sa SDL_GetProcessInput 222 * \sa SDL_GetProcessOutput 223 * \sa SDL_KillProcess 224 * \sa SDL_WaitProcess 225 * \sa SDL_DestroyProcess 226 */ 227extern SDL_DECLSPEC SDL_Process * SDLCALL SDL_CreateProcessWithProperties(SDL_PropertiesID props); 228 229#define SDL_PROP_PROCESS_CREATE_ARGS_POINTER "SDL.process.create.args" 230#define SDL_PROP_PROCESS_CREATE_ENVIRONMENT_POINTER "SDL.process.create.environment" 231#define SDL_PROP_PROCESS_CREATE_WORKING_DIRECTORY_STRING "SDL.process.create.working_directory" 232#define SDL_PROP_PROCESS_CREATE_STDIN_NUMBER "SDL.process.create.stdin_option" 233#define SDL_PROP_PROCESS_CREATE_STDIN_POINTER "SDL.process.create.stdin_source" 234#define SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER "SDL.process.create.stdout_option" 235#define SDL_PROP_PROCESS_CREATE_STDOUT_POINTER "SDL.process.create.stdout_source" 236#define SDL_PROP_PROCESS_CREATE_STDERR_NUMBER "SDL.process.create.stderr_option" 237#define SDL_PROP_PROCESS_CREATE_STDERR_POINTER "SDL.process.create.stderr_source" 238#define SDL_PROP_PROCESS_CREATE_STDERR_TO_STDOUT_BOOLEAN "SDL.process.create.stderr_to_stdout" 239#define SDL_PROP_PROCESS_CREATE_BACKGROUND_BOOLEAN "SDL.process.create.background" 240#define SDL_PROP_PROCESS_CREATE_CMDLINE_STRING "SDL.process.create.cmdline" 241 242/** 243 * Get the properties associated with a process. 244 * 245 * The following read-only properties are provided by SDL: 246 * 247 * - `SDL_PROP_PROCESS_PID_NUMBER`: the process ID of the process. 248 * - `SDL_PROP_PROCESS_STDIN_POINTER`: an SDL_IOStream that can be used to 249 * write input to the process, if it was created with 250 * `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` set to `SDL_PROCESS_STDIO_APP`. 251 * - `SDL_PROP_PROCESS_STDOUT_POINTER`: a non-blocking SDL_IOStream that can 252 * be used to read output from the process, if it was created with 253 * `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` set to `SDL_PROCESS_STDIO_APP`. 254 * - `SDL_PROP_PROCESS_STDERR_POINTER`: a non-blocking SDL_IOStream that can 255 * be used to read error output from the process, if it was created with 256 * `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER` set to `SDL_PROCESS_STDIO_APP`. 257 * - `SDL_PROP_PROCESS_BACKGROUND_BOOLEAN`: true if the process is running in 258 * the background. 259 * 260 * \param process the process to query. 261 * \returns a valid property ID on success or 0 on failure; call 262 * SDL_GetError() for more information. 263 * 264 * \threadsafety It is safe to call this function from any thread. 265 * 266 * \since This function is available since SDL 3.2.0. 267 * 268 * \sa SDL_CreateProcess 269 * \sa SDL_CreateProcessWithProperties 270 */ 271extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetProcessProperties(SDL_Process *process); 272 273#define SDL_PROP_PROCESS_PID_NUMBER "SDL.process.pid" 274#define SDL_PROP_PROCESS_STDIN_POINTER "SDL.process.stdin" 275#define SDL_PROP_PROCESS_STDOUT_POINTER "SDL.process.stdout" 276#define SDL_PROP_PROCESS_STDERR_POINTER "SDL.process.stderr" 277#define SDL_PROP_PROCESS_BACKGROUND_BOOLEAN "SDL.process.background" 278 279/** 280 * Read all the output from a process. 281 * 282 * If a process was created with I/O enabled, you can use this function to 283 * read the output. This function blocks until the process is complete, 284 * capturing all output, and providing the process exit code. 285 * 286 * The data is allocated with a zero byte at the end (null terminated) for 287 * convenience. This extra byte is not included in the value reported via 288 * `datasize`. 289 * 290 * The data should be freed with SDL_free(). 291 * 292 * \param process The process to read. 293 * \param datasize a pointer filled in with the number of bytes read, may be 294 * NULL. 295 * \param exitcode a pointer filled in with the process exit code if the 296 * process has exited, may be NULL. 297 * \returns the data or NULL on failure; call SDL_GetError() for more 298 * information. 299 * 300 * \threadsafety This function is not thread safe. 301 * 302 * \since This function is available since SDL 3.2.0. 303 * 304 * \sa SDL_CreateProcess 305 * \sa SDL_CreateProcessWithProperties 306 * \sa SDL_DestroyProcess 307 */ 308extern SDL_DECLSPEC void * SDLCALL SDL_ReadProcess(SDL_Process *process, size_t *datasize, int *exitcode); 309 310/** 311 * Get the SDL_IOStream associated with process standard input. 312 * 313 * The process must have been created with SDL_CreateProcess() and pipe_stdio 314 * set to true, or with SDL_CreateProcessWithProperties() and 315 * `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` set to `SDL_PROCESS_STDIO_APP`. 316 * 317 * Writing to this stream can return less data than expected if the process 318 * hasn't read its input. It may be blocked waiting for its output to be read, 319 * if so you may need to call SDL_GetProcessOutput() and read the output in 320 * parallel with writing input. 321 * 322 * \param process The process to get the input stream for. 323 * \returns the input stream or NULL on failure; call SDL_GetError() for more 324 * information. 325 * 326 * \threadsafety It is safe to call this function from any thread. 327 * 328 * \since This function is available since SDL 3.2.0. 329 * 330 * \sa SDL_CreateProcess 331 * \sa SDL_CreateProcessWithProperties 332 * \sa SDL_GetProcessOutput 333 */ 334extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_GetProcessInput(SDL_Process *process); 335 336/** 337 * Get the SDL_IOStream associated with process standard output. 338 * 339 * The process must have been created with SDL_CreateProcess() and pipe_stdio 340 * set to true, or with SDL_CreateProcessWithProperties() and 341 * `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` set to `SDL_PROCESS_STDIO_APP`. 342 * 343 * Reading from this stream can return 0 with SDL_GetIOStatus() returning 344 * SDL_IO_STATUS_NOT_READY if no output is available yet. 345 * 346 * \param process The process to get the output stream for. 347 * \returns the output stream or NULL on failure; call SDL_GetError() for more 348 * information. 349 * 350 * \threadsafety It is safe to call this function from any thread. 351 * 352 * \since This function is available since SDL 3.2.0. 353 * 354 * \sa SDL_CreateProcess 355 * \sa SDL_CreateProcessWithProperties 356 * \sa SDL_GetProcessInput 357 */ 358extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_GetProcessOutput(SDL_Process *process); 359 360/** 361 * Stop a process. 362 * 363 * \param process The process to stop. 364 * \param force true to terminate the process immediately, false to try to 365 * stop the process gracefully. In general you should try to stop 366 * the process gracefully first as terminating a process may 367 * leave it with half-written data or in some other unstable 368 * state. 369 * \returns true on success or false on failure; call SDL_GetError() for more 370 * information. 371 * 372 * \threadsafety This function is not thread safe. 373 * 374 * \since This function is available since SDL 3.2.0. 375 * 376 * \sa SDL_CreateProcess 377 * \sa SDL_CreateProcessWithProperties 378 * \sa SDL_WaitProcess 379 * \sa SDL_DestroyProcess 380 */ 381extern SDL_DECLSPEC bool SDLCALL SDL_KillProcess(SDL_Process *process, bool force); 382 383/** 384 * Wait for a process to finish. 385 * 386 * This can be called multiple times to get the status of a process. 387 * 388 * The exit code will be the exit code of the process if it terminates 389 * normally, a negative signal if it terminated due to a signal, or -255 390 * otherwise. It will not be changed if the process is still running. 391 * 392 * If you create a process with standard output piped to the application 393 * (`pipe_stdio` being true) then you should read all of the process output 394 * before calling SDL_WaitProcess(). If you don't do this the process might be 395 * blocked indefinitely waiting for output to be read and SDL_WaitProcess() 396 * will never return true; 397 * 398 * \param process The process to wait for. 399 * \param block If true, block until the process finishes; otherwise, report 400 * on the process' status. 401 * \param exitcode a pointer filled in with the process exit code if the 402 * process has exited, may be NULL. 403 * \returns true if the process exited, false otherwise. 404 * 405 * \threadsafety This function is not thread safe. 406 * 407 * \since This function is available since SDL 3.2.0. 408 * 409 * \sa SDL_CreateProcess 410 * \sa SDL_CreateProcessWithProperties 411 * \sa SDL_KillProcess 412 * \sa SDL_DestroyProcess 413 */ 414extern SDL_DECLSPEC bool SDLCALL SDL_WaitProcess(SDL_Process *process, bool block, int *exitcode); 415 416/** 417 * Destroy a previously created process object. 418 * 419 * Note that this does not stop the process, just destroys the SDL object used 420 * to track it. If you want to stop the process you should use 421 * SDL_KillProcess(). 422 * 423 * \param process The process object to destroy. 424 * 425 * \threadsafety This function is not thread safe. 426 * 427 * \since This function is available since SDL 3.2.0. 428 * 429 * \sa SDL_CreateProcess 430 * \sa SDL_CreateProcessWithProperties 431 * \sa SDL_KillProcess 432 */ 433extern SDL_DECLSPEC void SDLCALL SDL_DestroyProcess(SDL_Process *process); 434 435/* Ends C function definitions when using C++ */ 436#ifdef __cplusplus 437} 438#endif 439#include <SDL3/SDL_close_code.h> 440 441#endif /* SDL_process_h_ */ 442[FILE END](C) 2025 0x4248 (C) 2025 4248 Media and 4248 Systems, All part of 0x4248 See LICENCE files for more information. Not all files are by 0x4248 always check Licencing.