sdl3_sys/generated/
process.rs

1//! Process control support.
2//!
3//! These functions provide a cross-platform way to spawn and manage OS-level
4//! processes.
5//!
6//! You can create a new subprocess with [`SDL_CreateProcess()`] and optionally
7//! read and write to it using [`SDL_ReadProcess()`] or [`SDL_GetProcessInput()`] and
8//! [`SDL_GetProcessOutput()`]. If more advanced functionality like chaining input
9//! between processes is necessary, you can use
10//! [`SDL_CreateProcessWithProperties()`].
11//!
12//! You can get the status of a created process with [`SDL_WaitProcess()`], or
13//! terminate the process with [`SDL_KillProcess()`].
14//!
15//! Don't forget to call [`SDL_DestroyProcess()`] to clean up, whether the process
16//! process was killed, terminated on its own, or is still running!
17
18use super::stdinc::*;
19
20use super::error::*;
21
22use super::iostream::*;
23
24use super::properties::*;
25
26unsafe extern "C" {
27    /// Create a new process.
28    ///
29    /// The path to the executable is supplied in args\[0\]. args\[1..N\] are
30    /// additional arguments passed on the command line of the new process, and the
31    /// argument list should be terminated with a NULL, e.g.:
32    ///
33    /// ```c
34    /// const char *args[] = { "myprogram", "argument", NULL };
35    /// ```
36    ///
37    /// Setting pipe_stdio to true is equivalent to setting
38    /// [`SDL_PROP_PROCESS_CREATE_STDIN_NUMBER`] and
39    /// [`SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER`] to [`SDL_PROCESS_STDIO_APP`], and
40    /// will allow the use of [`SDL_ReadProcess()`] or [`SDL_GetProcessInput()`] and
41    /// [`SDL_GetProcessOutput()`].
42    ///
43    /// See [`SDL_CreateProcessWithProperties()`] for more details.
44    ///
45    /// ## Parameters
46    /// - `args`: the path and arguments for the new process.
47    /// - `pipe_stdio`: true to create pipes to the process's standard input and
48    ///   from the process's standard output, false for the process
49    ///   to have no input and inherit the application's standard
50    ///   output.
51    ///
52    /// ## Return value
53    /// Returns the newly created and running process, or NULL if the process
54    ///   couldn't be created.
55    ///
56    /// ## Thread safety
57    /// It is safe to call this function from any thread.
58    ///
59    /// ## Availability
60    /// This function is available since SDL 3.2.0.
61    ///
62    /// ## See also
63    /// - [`SDL_CreateProcessWithProperties`]
64    /// - [`SDL_GetProcessProperties`]
65    /// - [`SDL_ReadProcess`]
66    /// - [`SDL_GetProcessInput`]
67    /// - [`SDL_GetProcessOutput`]
68    /// - [`SDL_KillProcess`]
69    /// - [`SDL_WaitProcess`]
70    /// - [`SDL_DestroyProcess`]
71    pub fn SDL_CreateProcess(
72        args: *const *const ::core::ffi::c_char,
73        pipe_stdio: ::core::primitive::bool,
74    ) -> *mut SDL_Process;
75}
76
77/// Description of where standard I/O should be directed when creating a
78/// process.
79///
80/// If a standard I/O stream is set to [`SDL_PROCESS_STDIO_INHERITED`], it will go
81/// to the same place as the application's I/O stream. This is the default for
82/// standard output and standard error.
83///
84/// If a standard I/O stream is set to [`SDL_PROCESS_STDIO_NULL`], it is connected
85/// to `NUL:` on Windows and `/dev/null` on POSIX systems. This is the default
86/// for standard input.
87///
88/// If a standard I/O stream is set to [`SDL_PROCESS_STDIO_APP`], it is connected
89/// to a new [`SDL_IOStream`] that is available to the application. Standard input
90/// will be available as [`SDL_PROP_PROCESS_STDIN_POINTER`] and allows
91/// [`SDL_GetProcessInput()`], standard output will be available as
92/// [`SDL_PROP_PROCESS_STDOUT_POINTER`] and allows [`SDL_ReadProcess()`] and
93/// [`SDL_GetProcessOutput()`], and standard error will be available as
94/// [`SDL_PROP_PROCESS_STDERR_POINTER`] in the properties for the created
95/// process.
96///
97/// If a standard I/O stream is set to [`SDL_PROCESS_STDIO_REDIRECT`], it is
98/// connected to an existing [`SDL_IOStream`] provided by the application. Standard
99/// input is provided using [`SDL_PROP_PROCESS_CREATE_STDIN_POINTER`], standard
100/// output is provided using [`SDL_PROP_PROCESS_CREATE_STDOUT_POINTER`], and
101/// standard error is provided using [`SDL_PROP_PROCESS_CREATE_STDERR_POINTER`]
102/// in the creation properties. These existing streams should be closed by the
103/// application once the new process is created.
104///
105/// In order to use an [`SDL_IOStream`] with [`SDL_PROCESS_STDIO_REDIRECT`], it must
106/// have [`SDL_PROP_IOSTREAM_WINDOWS_HANDLE_POINTER`] or
107/// [`SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER`] set. This is true for streams
108/// representing files and process I/O.
109///
110/// ## Availability
111/// This enum is available since SDL 3.2.0.
112///
113/// ## See also
114/// - [`SDL_CreateProcessWithProperties`]
115/// - [`SDL_GetProcessProperties`]
116/// - [`SDL_ReadProcess`]
117/// - [`SDL_GetProcessInput`]
118/// - [`SDL_GetProcessOutput`]
119///
120/// ## Known values (`sdl3-sys`)
121/// | Associated constant | Global constant | Description |
122/// | ------------------- | --------------- | ----------- |
123/// | [`INHERITED`](SDL_ProcessIO::INHERITED) | [`SDL_PROCESS_STDIO_INHERITED`] | The I/O stream is inherited from the application. |
124/// | [`NULL`](SDL_ProcessIO::NULL) | [`SDL_PROCESS_STDIO_NULL`] | The I/O stream is ignored. |
125/// | [`APP`](SDL_ProcessIO::APP) | [`SDL_PROCESS_STDIO_APP`] | The I/O stream is connected to a new [`SDL_IOStream`] that the application can read or write |
126/// | [`REDIRECT`](SDL_ProcessIO::REDIRECT) | [`SDL_PROCESS_STDIO_REDIRECT`] | The I/O stream is redirected to an existing [`SDL_IOStream`]. |
127#[repr(transparent)]
128#[derive(Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
129pub struct SDL_ProcessIO(pub ::core::ffi::c_int);
130
131impl ::core::cmp::PartialEq<::core::ffi::c_int> for SDL_ProcessIO {
132    #[inline(always)]
133    fn eq(&self, other: &::core::ffi::c_int) -> bool {
134        &self.0 == other
135    }
136}
137
138impl ::core::cmp::PartialEq<SDL_ProcessIO> for ::core::ffi::c_int {
139    #[inline(always)]
140    fn eq(&self, other: &SDL_ProcessIO) -> bool {
141        self == &other.0
142    }
143}
144
145impl From<SDL_ProcessIO> for ::core::ffi::c_int {
146    #[inline(always)]
147    fn from(value: SDL_ProcessIO) -> Self {
148        value.0
149    }
150}
151
152#[cfg(feature = "debug-impls")]
153impl ::core::fmt::Debug for SDL_ProcessIO {
154    fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
155        #[allow(unreachable_patterns)]
156        f.write_str(match *self {
157            Self::INHERITED => "SDL_PROCESS_STDIO_INHERITED",
158            Self::NULL => "SDL_PROCESS_STDIO_NULL",
159            Self::APP => "SDL_PROCESS_STDIO_APP",
160            Self::REDIRECT => "SDL_PROCESS_STDIO_REDIRECT",
161
162            _ => return write!(f, "SDL_ProcessIO({})", self.0),
163        })
164    }
165}
166
167impl SDL_ProcessIO {
168    /// The I/O stream is inherited from the application.
169    pub const INHERITED: Self = Self((0 as ::core::ffi::c_int));
170    /// The I/O stream is ignored.
171    pub const NULL: Self = Self((1 as ::core::ffi::c_int));
172    /// The I/O stream is connected to a new [`SDL_IOStream`] that the application can read or write
173    pub const APP: Self = Self((2 as ::core::ffi::c_int));
174    /// The I/O stream is redirected to an existing [`SDL_IOStream`].
175    pub const REDIRECT: Self = Self((3 as ::core::ffi::c_int));
176}
177
178/// The I/O stream is inherited from the application.
179pub const SDL_PROCESS_STDIO_INHERITED: SDL_ProcessIO = SDL_ProcessIO::INHERITED;
180/// The I/O stream is ignored.
181pub const SDL_PROCESS_STDIO_NULL: SDL_ProcessIO = SDL_ProcessIO::NULL;
182/// The I/O stream is connected to a new [`SDL_IOStream`] that the application can read or write
183pub const SDL_PROCESS_STDIO_APP: SDL_ProcessIO = SDL_ProcessIO::APP;
184/// The I/O stream is redirected to an existing [`SDL_IOStream`].
185pub const SDL_PROCESS_STDIO_REDIRECT: SDL_ProcessIO = SDL_ProcessIO::REDIRECT;
186
187impl SDL_ProcessIO {
188    /// Initialize a `SDL_ProcessIO` from a raw value.
189    #[inline(always)]
190    pub const fn new(value: ::core::ffi::c_int) -> Self {
191        Self(value)
192    }
193}
194
195impl SDL_ProcessIO {
196    /// Get a copy of the inner raw value.
197    #[inline(always)]
198    pub const fn value(&self) -> ::core::ffi::c_int {
199        self.0
200    }
201}
202
203#[cfg(feature = "metadata")]
204impl sdl3_sys::metadata::GroupMetadata for SDL_ProcessIO {
205    const GROUP_METADATA: &'static sdl3_sys::metadata::Group =
206        &crate::metadata::process::METADATA_SDL_ProcessIO;
207}
208
209unsafe extern "C" {
210    /// Create a new process with the specified properties.
211    ///
212    /// These are the supported properties:
213    ///
214    /// - [`SDL_PROP_PROCESS_CREATE_ARGS_POINTER`]\: an array of strings containing
215    ///   the program to run, any arguments, and a NULL pointer, e.g. const char
216    ///   *args\[\] = { "myprogram", "argument", NULL }. This is a required property.
217    /// - [`SDL_PROP_PROCESS_CREATE_ENVIRONMENT_POINTER`]\: an [`SDL_Environment`]
218    ///   pointer. If this property is set, it will be the entire environment for
219    ///   the process, otherwise the current environment is used.
220    /// - [`SDL_PROP_PROCESS_CREATE_WORKING_DIRECTORY_STRING`]\: a UTF-8 encoded
221    ///   string representing the working directory for the process, defaults to
222    ///   the current working directory.
223    /// - [`SDL_PROP_PROCESS_CREATE_STDIN_NUMBER`]\: an [`SDL_ProcessIO`] value describing
224    ///   where standard input for the process comes from, defaults to
225    ///   [`SDL_PROCESS_STDIO_NULL`].
226    /// - [`SDL_PROP_PROCESS_CREATE_STDIN_POINTER`]\: an [`SDL_IOStream`] pointer used for
227    ///   standard input when [`SDL_PROP_PROCESS_CREATE_STDIN_NUMBER`] is set to
228    ///   [`SDL_PROCESS_STDIO_REDIRECT`].
229    /// - [`SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER`]\: an [`SDL_ProcessIO`] value
230    ///   describing where standard output for the process goes to, defaults to
231    ///   [`SDL_PROCESS_STDIO_INHERITED`].
232    /// - [`SDL_PROP_PROCESS_CREATE_STDOUT_POINTER`]\: an [`SDL_IOStream`] pointer used
233    ///   for standard output when [`SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER`] is set
234    ///   to [`SDL_PROCESS_STDIO_REDIRECT`].
235    /// - [`SDL_PROP_PROCESS_CREATE_STDERR_NUMBER`]\: an [`SDL_ProcessIO`] value
236    ///   describing where standard error for the process goes to, defaults to
237    ///   [`SDL_PROCESS_STDIO_INHERITED`].
238    /// - [`SDL_PROP_PROCESS_CREATE_STDERR_POINTER`]\: an [`SDL_IOStream`] pointer used
239    ///   for standard error when [`SDL_PROP_PROCESS_CREATE_STDERR_NUMBER`] is set to
240    ///   [`SDL_PROCESS_STDIO_REDIRECT`].
241    /// - [`SDL_PROP_PROCESS_CREATE_STDERR_TO_STDOUT_BOOLEAN`]\: true if the error
242    ///   output of the process should be redirected into the standard output of
243    ///   the process. This property has no effect if
244    ///   [`SDL_PROP_PROCESS_CREATE_STDERR_NUMBER`] is set.
245    /// - [`SDL_PROP_PROCESS_CREATE_BACKGROUND_BOOLEAN`]\: true if the process should
246    ///   run in the background. In this case the default input and output is
247    ///   [`SDL_PROCESS_STDIO_NULL`] and the exitcode of the process is not
248    ///   available, and will always be 0.
249    /// - [`SDL_PROP_PROCESS_CREATE_CMDLINE_STRING`]\: a string containing the program
250    ///   to run and any parameters. This string is passed directly to
251    ///   `CreateProcess` on Windows, and does nothing on other platforms. This
252    ///   property is only important if you want to start programs that does
253    ///   non-standard command-line processing, and in most cases using
254    ///   [`SDL_PROP_PROCESS_CREATE_ARGS_POINTER`] is sufficient.
255    ///
256    /// On POSIX platforms, wait() and waitpid(-1, ...) should not be called, and
257    /// SIGCHLD should not be ignored or handled because those would prevent SDL
258    /// from properly tracking the lifetime of the underlying process. You should
259    /// use [`SDL_WaitProcess()`] instead.
260    ///
261    /// ## Parameters
262    /// - `props`: the properties to use.
263    ///
264    /// ## Return value
265    /// Returns the newly created and running process, or NULL if the process
266    ///   couldn't be created.
267    ///
268    /// ## Thread safety
269    /// It is safe to call this function from any thread.
270    ///
271    /// ## Availability
272    /// This function is available since SDL 3.2.0.
273    ///
274    /// ## See also
275    /// - [`SDL_CreateProcess`]
276    /// - [`SDL_GetProcessProperties`]
277    /// - [`SDL_ReadProcess`]
278    /// - [`SDL_GetProcessInput`]
279    /// - [`SDL_GetProcessOutput`]
280    /// - [`SDL_KillProcess`]
281    /// - [`SDL_WaitProcess`]
282    /// - [`SDL_DestroyProcess`]
283    pub fn SDL_CreateProcessWithProperties(props: SDL_PropertiesID) -> *mut SDL_Process;
284}
285
286pub const SDL_PROP_PROCESS_CREATE_ARGS_POINTER: *const ::core::ffi::c_char =
287    c"SDL.process.create.args".as_ptr();
288
289pub const SDL_PROP_PROCESS_CREATE_ENVIRONMENT_POINTER: *const ::core::ffi::c_char =
290    c"SDL.process.create.environment".as_ptr();
291
292pub const SDL_PROP_PROCESS_CREATE_WORKING_DIRECTORY_STRING: *const ::core::ffi::c_char =
293    c"SDL.process.create.working_directory".as_ptr();
294
295pub const SDL_PROP_PROCESS_CREATE_STDIN_NUMBER: *const ::core::ffi::c_char =
296    c"SDL.process.create.stdin_option".as_ptr();
297
298pub const SDL_PROP_PROCESS_CREATE_STDIN_POINTER: *const ::core::ffi::c_char =
299    c"SDL.process.create.stdin_source".as_ptr();
300
301pub const SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER: *const ::core::ffi::c_char =
302    c"SDL.process.create.stdout_option".as_ptr();
303
304pub const SDL_PROP_PROCESS_CREATE_STDOUT_POINTER: *const ::core::ffi::c_char =
305    c"SDL.process.create.stdout_source".as_ptr();
306
307pub const SDL_PROP_PROCESS_CREATE_STDERR_NUMBER: *const ::core::ffi::c_char =
308    c"SDL.process.create.stderr_option".as_ptr();
309
310pub const SDL_PROP_PROCESS_CREATE_STDERR_POINTER: *const ::core::ffi::c_char =
311    c"SDL.process.create.stderr_source".as_ptr();
312
313pub const SDL_PROP_PROCESS_CREATE_STDERR_TO_STDOUT_BOOLEAN: *const ::core::ffi::c_char =
314    c"SDL.process.create.stderr_to_stdout".as_ptr();
315
316pub const SDL_PROP_PROCESS_CREATE_BACKGROUND_BOOLEAN: *const ::core::ffi::c_char =
317    c"SDL.process.create.background".as_ptr();
318
319pub const SDL_PROP_PROCESS_CREATE_CMDLINE_STRING: *const ::core::ffi::c_char =
320    c"SDL.process.create.cmdline".as_ptr();
321
322unsafe extern "C" {
323    /// Get the properties associated with a process.
324    ///
325    /// The following read-only properties are provided by SDL:
326    ///
327    /// - [`SDL_PROP_PROCESS_PID_NUMBER`]\: the process ID of the process.
328    /// - [`SDL_PROP_PROCESS_STDIN_POINTER`]\: an [`SDL_IOStream`] that can be used to
329    ///   write input to the process, if it was created with
330    ///   [`SDL_PROP_PROCESS_CREATE_STDIN_NUMBER`] set to [`SDL_PROCESS_STDIO_APP`].
331    /// - [`SDL_PROP_PROCESS_STDOUT_POINTER`]\: a non-blocking [`SDL_IOStream`] that can
332    ///   be used to read output from the process, if it was created with
333    ///   [`SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER`] set to [`SDL_PROCESS_STDIO_APP`].
334    /// - [`SDL_PROP_PROCESS_STDERR_POINTER`]\: a non-blocking [`SDL_IOStream`] that can
335    ///   be used to read error output from the process, if it was created with
336    ///   [`SDL_PROP_PROCESS_CREATE_STDERR_NUMBER`] set to [`SDL_PROCESS_STDIO_APP`].
337    /// - [`SDL_PROP_PROCESS_BACKGROUND_BOOLEAN`]\: true if the process is running in
338    ///   the background.
339    ///
340    /// ## Parameters
341    /// - `process`: the process to query.
342    ///
343    /// ## Return value
344    /// Returns a valid property ID on success or 0 on failure; call
345    ///   [`SDL_GetError()`] for more information.
346    ///
347    /// ## Thread safety
348    /// It is safe to call this function from any thread.
349    ///
350    /// ## Availability
351    /// This function is available since SDL 3.2.0.
352    ///
353    /// ## See also
354    /// - [`SDL_CreateProcess`]
355    /// - [`SDL_CreateProcessWithProperties`]
356    pub fn SDL_GetProcessProperties(process: *mut SDL_Process) -> SDL_PropertiesID;
357}
358
359pub const SDL_PROP_PROCESS_PID_NUMBER: *const ::core::ffi::c_char = c"SDL.process.pid".as_ptr();
360
361pub const SDL_PROP_PROCESS_STDIN_POINTER: *const ::core::ffi::c_char =
362    c"SDL.process.stdin".as_ptr();
363
364pub const SDL_PROP_PROCESS_STDOUT_POINTER: *const ::core::ffi::c_char =
365    c"SDL.process.stdout".as_ptr();
366
367pub const SDL_PROP_PROCESS_STDERR_POINTER: *const ::core::ffi::c_char =
368    c"SDL.process.stderr".as_ptr();
369
370pub const SDL_PROP_PROCESS_BACKGROUND_BOOLEAN: *const ::core::ffi::c_char =
371    c"SDL.process.background".as_ptr();
372
373unsafe extern "C" {
374    /// Read all the output from a process.
375    ///
376    /// If a process was created with I/O enabled, you can use this function to
377    /// read the output. This function blocks until the process is complete,
378    /// capturing all output, and providing the process exit code.
379    ///
380    /// The data is allocated with a zero byte at the end (null terminated) for
381    /// convenience. This extra byte is not included in the value reported via
382    /// `datasize`.
383    ///
384    /// The data should be freed with [`SDL_free()`].
385    ///
386    /// ## Parameters
387    /// - `process`: The process to read.
388    /// - `datasize`: a pointer filled in with the number of bytes read, may be
389    ///   NULL.
390    /// - `exitcode`: a pointer filled in with the process exit code if the
391    ///   process has exited, may be NULL.
392    ///
393    /// ## Return value
394    /// Returns the data or NULL on failure; call [`SDL_GetError()`] for more
395    ///   information.
396    ///
397    /// ## Thread safety
398    /// This function is not thread safe.
399    ///
400    /// ## Availability
401    /// This function is available since SDL 3.2.0.
402    ///
403    /// ## See also
404    /// - [`SDL_CreateProcess`]
405    /// - [`SDL_CreateProcessWithProperties`]
406    /// - [`SDL_DestroyProcess`]
407    pub fn SDL_ReadProcess(
408        process: *mut SDL_Process,
409        datasize: *mut ::core::primitive::usize,
410        exitcode: *mut ::core::ffi::c_int,
411    ) -> *mut ::core::ffi::c_void;
412}
413
414unsafe extern "C" {
415    /// Get the [`SDL_IOStream`] associated with process standard input.
416    ///
417    /// The process must have been created with [`SDL_CreateProcess()`] and pipe_stdio
418    /// set to true, or with [`SDL_CreateProcessWithProperties()`] and
419    /// [`SDL_PROP_PROCESS_CREATE_STDIN_NUMBER`] set to [`SDL_PROCESS_STDIO_APP`].
420    ///
421    /// Writing to this stream can return less data than expected if the process
422    /// hasn't read its input. It may be blocked waiting for its output to be read,
423    /// if so you may need to call [`SDL_GetProcessOutput()`] and read the output in
424    /// parallel with writing input.
425    ///
426    /// ## Parameters
427    /// - `process`: The process to get the input stream for.
428    ///
429    /// ## Return value
430    /// Returns the input stream or NULL on failure; call [`SDL_GetError()`] for more
431    ///   information.
432    ///
433    /// ## Thread safety
434    /// It is safe to call this function from any thread.
435    ///
436    /// ## Availability
437    /// This function is available since SDL 3.2.0.
438    ///
439    /// ## See also
440    /// - [`SDL_CreateProcess`]
441    /// - [`SDL_CreateProcessWithProperties`]
442    /// - [`SDL_GetProcessOutput`]
443    pub fn SDL_GetProcessInput(process: *mut SDL_Process) -> *mut SDL_IOStream;
444}
445
446unsafe extern "C" {
447    /// Get the [`SDL_IOStream`] associated with process standard output.
448    ///
449    /// The process must have been created with [`SDL_CreateProcess()`] and pipe_stdio
450    /// set to true, or with [`SDL_CreateProcessWithProperties()`] and
451    /// [`SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER`] set to [`SDL_PROCESS_STDIO_APP`].
452    ///
453    /// Reading from this stream can return 0 with [`SDL_GetIOStatus()`] returning
454    /// [`SDL_IO_STATUS_NOT_READY`] if no output is available yet.
455    ///
456    /// ## Parameters
457    /// - `process`: The process to get the output stream for.
458    ///
459    /// ## Return value
460    /// Returns the output stream or NULL on failure; call [`SDL_GetError()`] for more
461    ///   information.
462    ///
463    /// ## Thread safety
464    /// It is safe to call this function from any thread.
465    ///
466    /// ## Availability
467    /// This function is available since SDL 3.2.0.
468    ///
469    /// ## See also
470    /// - [`SDL_CreateProcess`]
471    /// - [`SDL_CreateProcessWithProperties`]
472    /// - [`SDL_GetProcessInput`]
473    pub fn SDL_GetProcessOutput(process: *mut SDL_Process) -> *mut SDL_IOStream;
474}
475
476unsafe extern "C" {
477    /// Stop a process.
478    ///
479    /// ## Parameters
480    /// - `process`: The process to stop.
481    /// - `force`: true to terminate the process immediately, false to try to
482    ///   stop the process gracefully. In general you should try to stop
483    ///   the process gracefully first as terminating a process may
484    ///   leave it with half-written data or in some other unstable
485    ///   state.
486    ///
487    /// ## Return value
488    /// Returns true on success or false on failure; call [`SDL_GetError()`] for more
489    ///   information.
490    ///
491    /// ## Thread safety
492    /// This function is not thread safe.
493    ///
494    /// ## Availability
495    /// This function is available since SDL 3.2.0.
496    ///
497    /// ## See also
498    /// - [`SDL_CreateProcess`]
499    /// - [`SDL_CreateProcessWithProperties`]
500    /// - [`SDL_WaitProcess`]
501    /// - [`SDL_DestroyProcess`]
502    pub fn SDL_KillProcess(
503        process: *mut SDL_Process,
504        force: ::core::primitive::bool,
505    ) -> ::core::primitive::bool;
506}
507
508unsafe extern "C" {
509    /// Wait for a process to finish.
510    ///
511    /// This can be called multiple times to get the status of a process.
512    ///
513    /// The exit code will be the exit code of the process if it terminates
514    /// normally, a negative signal if it terminated due to a signal, or -255
515    /// otherwise. It will not be changed if the process is still running.
516    ///
517    /// If you create a process with standard output piped to the application
518    /// (`pipe_stdio` being true) then you should read all of the process output
519    /// before calling [`SDL_WaitProcess()`]. If you don't do this the process might be
520    /// blocked indefinitely waiting for output to be read and [`SDL_WaitProcess()`]
521    /// will never return true;
522    ///
523    /// ## Parameters
524    /// - `process`: The process to wait for.
525    /// - `block`: If true, block until the process finishes; otherwise, report
526    ///   on the process' status.
527    /// - `exitcode`: a pointer filled in with the process exit code if the
528    ///   process has exited, may be NULL.
529    ///
530    /// ## Return value
531    /// Returns true if the process exited, false otherwise.
532    ///
533    /// ## Thread safety
534    /// This function is not thread safe.
535    ///
536    /// ## Availability
537    /// This function is available since SDL 3.2.0.
538    ///
539    /// ## See also
540    /// - [`SDL_CreateProcess`]
541    /// - [`SDL_CreateProcessWithProperties`]
542    /// - [`SDL_KillProcess`]
543    /// - [`SDL_DestroyProcess`]
544    pub fn SDL_WaitProcess(
545        process: *mut SDL_Process,
546        block: ::core::primitive::bool,
547        exitcode: *mut ::core::ffi::c_int,
548    ) -> ::core::primitive::bool;
549}
550
551unsafe extern "C" {
552    /// Destroy a previously created process object.
553    ///
554    /// Note that this does not stop the process, just destroys the SDL object used
555    /// to track it. If you want to stop the process you should use
556    /// [`SDL_KillProcess()`].
557    ///
558    /// ## Parameters
559    /// - `process`: The process object to destroy.
560    ///
561    /// ## Thread safety
562    /// This function is not thread safe.
563    ///
564    /// ## Availability
565    /// This function is available since SDL 3.2.0.
566    ///
567    /// ## See also
568    /// - [`SDL_CreateProcess`]
569    /// - [`SDL_CreateProcessWithProperties`]
570    /// - [`SDL_KillProcess`]
571    pub fn SDL_DestroyProcess(process: *mut SDL_Process);
572}
573
574/// An opaque handle representing a system process.
575///
576/// ## Availability
577/// This datatype is available since SDL 3.2.0.
578///
579/// ## See also
580/// - [`SDL_CreateProcess`]
581#[repr(C)]
582pub struct SDL_Process {
583    _opaque: [::core::primitive::u8; 0],
584}
585
586#[cfg(doc)]
587use crate::everything::*;
sdl3_sys/generated/process.rs

sdl3_sys/generated/
process.rs
