gio/
subprocess_launcher.rs

1// Take a look at the license at the top of the repository in the LICENSE file.
2
3#[cfg(any(unix, all(docsrs, unix)))]
4use std::os::unix::io::IntoRawFd;
5
6use glib::translate::*;
7
8use crate::ffi;
9use crate::SubprocessLauncher;
10
11#[cfg(all(docsrs, not(unix)))]
12pub trait IntoRawFd: Sized {
13    fn into_raw_fd(self) -> i32 {
14        0
15    }
16}
17
18impl SubprocessLauncher {
19    /// Replace the entire environment of processes launched from this
20    /// launcher with the given 'environ' variable.
21    ///
22    /// Typically you will build this variable by using g_listenv() to copy
23    /// the process 'environ' and using the functions g_environ_setenv(),
24    /// g_environ_unsetenv(), etc.
25    ///
26    /// As an alternative, you can use g_subprocess_launcher_setenv(),
27    /// g_subprocess_launcher_unsetenv(), etc.
28    ///
29    /// Pass an empty array to set an empty environment. Pass [`None`] to inherit the
30    /// parent process’ environment. As of GLib 2.54, the parent process’ environment
31    /// will be copied when g_subprocess_launcher_set_environ() is called.
32    /// Previously, it was copied when the subprocess was executed. This means the
33    /// copied environment may now be modified (using g_subprocess_launcher_setenv(),
34    /// etc.) before launching the subprocess.
35    ///
36    /// On UNIX, all strings in this array can be arbitrary byte strings.
37    /// On Windows, they should be in UTF-8.
38    /// ## `env`
39    ///
40    ///     the replacement environment
41    #[doc(alias = "g_subprocess_launcher_set_environ")]
42    pub fn set_environ(&self, env: &[std::ffi::OsString]) {
43        unsafe {
44            ffi::g_subprocess_launcher_set_environ(self.to_glib_none().0, env.to_glib_none().0);
45        }
46    }
47
48    /// Transfer an arbitrary file descriptor from parent process to the
49    /// child.  This function takes ownership of the @source_fd; it will be closed
50    /// in the parent when @self is freed.
51    ///
52    /// By default, all file descriptors from the parent will be closed.
53    /// This function allows you to create (for example) a custom `pipe()` or
54    /// `socketpair()` before launching the process, and choose the target
55    /// descriptor in the child.
56    ///
57    /// An example use case is GNUPG, which has a command line argument
58    /// `--passphrase-fd` providing a file descriptor number where it expects
59    /// the passphrase to be written.
60    /// ## `source_fd`
61    /// File descriptor in parent process
62    /// ## `target_fd`
63    /// Target descriptor for child process
64    #[cfg(unix)]
65    #[cfg_attr(docsrs, doc(cfg(unix)))]
66    #[doc(alias = "g_subprocess_launcher_take_fd")]
67    pub fn take_fd(&self, source_fd: impl IntoRawFd, target_fd: impl IntoRawFd) {
68        unsafe {
69            ffi::g_subprocess_launcher_take_fd(
70                self.to_glib_none().0,
71                source_fd.into_raw_fd(),
72                target_fd.into_raw_fd(),
73            );
74        }
75    }
76
77    /// Sets the file descriptor to use as the stderr for spawned processes.
78    ///
79    /// If @fd is -1 then any previously given fd is unset.
80    ///
81    /// Note that the default behaviour is to pass stderr through to the
82    /// stderr of the parent process.
83    ///
84    /// The passed @fd belongs to the #GSubprocessLauncher.  It will be
85    /// automatically closed when the launcher is finalized.  The file
86    /// descriptor will also be closed on the child side when executing the
87    /// spawned process.
88    ///
89    /// You may not set a stderr fd if a stderr file path is already set or
90    /// if the launcher flags contain any flags directing stderr elsewhere.
91    ///
92    /// This feature is only available on UNIX.
93    /// ## `fd`
94    /// a file descriptor, or -1
95    #[cfg(unix)]
96    #[cfg_attr(docsrs, doc(cfg(unix)))]
97    #[doc(alias = "g_subprocess_launcher_take_stderr_fd")]
98    pub fn take_stderr_fd(&self, fd: impl IntoRawFd) {
99        unsafe {
100            ffi::g_subprocess_launcher_take_stderr_fd(self.to_glib_none().0, fd.into_raw_fd());
101        }
102    }
103
104    /// Sets the file descriptor to use as the stdin for spawned processes.
105    ///
106    /// If @fd is -1 then any previously given fd is unset.
107    ///
108    /// Note that if your intention is to have the stdin of the calling
109    /// process inherited by the child then [`SubprocessFlags::STDIN_INHERIT`][crate::SubprocessFlags::STDIN_INHERIT]
110    /// is a better way to go about doing that.
111    ///
112    /// The passed @fd is noted but will not be touched in the current
113    /// process.  It is therefore necessary that it be kept open by the
114    /// caller until the subprocess is spawned.  The file descriptor will
115    /// also not be explicitly closed on the child side, so it must be marked
116    /// O_CLOEXEC if that's what you want.
117    ///
118    /// You may not set a stdin fd if a stdin file path is already set or if
119    /// the launcher flags contain any flags directing stdin elsewhere.
120    ///
121    /// This feature is only available on UNIX.
122    /// ## `fd`
123    /// a file descriptor, or -1
124    #[cfg(unix)]
125    #[cfg_attr(docsrs, doc(cfg(unix)))]
126    #[doc(alias = "g_subprocess_launcher_take_stdin_fd")]
127    pub fn take_stdin_fd(&self, fd: impl IntoRawFd) {
128        unsafe {
129            ffi::g_subprocess_launcher_take_stdin_fd(self.to_glib_none().0, fd.into_raw_fd());
130        }
131    }
132
133    /// Sets the file descriptor to use as the stdout for spawned processes.
134    ///
135    /// If @fd is -1 then any previously given fd is unset.
136    ///
137    /// Note that the default behaviour is to pass stdout through to the
138    /// stdout of the parent process.
139    ///
140    /// The passed @fd is noted but will not be touched in the current
141    /// process.  It is therefore necessary that it be kept open by the
142    /// caller until the subprocess is spawned.  The file descriptor will
143    /// also not be explicitly closed on the child side, so it must be marked
144    /// O_CLOEXEC if that's what you want.
145    ///
146    /// You may not set a stdout fd if a stdout file path is already set or
147    /// if the launcher flags contain any flags directing stdout elsewhere.
148    ///
149    /// This feature is only available on UNIX.
150    /// ## `fd`
151    /// a file descriptor, or -1
152    #[cfg(unix)]
153    #[cfg_attr(docsrs, doc(cfg(unix)))]
154    #[doc(alias = "g_subprocess_launcher_take_stdout_fd")]
155    pub fn take_stdout_fd(&self, fd: impl IntoRawFd) {
156        unsafe {
157            ffi::g_subprocess_launcher_take_stdout_fd(self.to_glib_none().0, fd.into_raw_fd());
158        }
159    }
160}