1
0

SDL_process.h 18 KB

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