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