gio/auto/subprocess_launcher.rs
1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4
5use crate::{ffi, Subprocess, SubprocessFlags};
6use glib::translate::*;
7#[cfg(unix)]
8#[cfg_attr(docsrs, doc(cfg(unix)))]
9use std::boxed::Box as Box_;
10
11glib::wrapper! {
12 /// This class contains a set of options for launching child processes,
13 /// such as where its standard input and output will be directed, the
14 /// argument list, the environment, and more.
15 ///
16 /// While the [`Subprocess`][crate::Subprocess] class has high level functions covering
17 /// popular cases, use of this class allows access to more advanced
18 /// options. It can also be used to launch multiple subprocesses with
19 /// a similar configuration.
20 ///
21 /// ## Properties
22 ///
23 ///
24 /// #### `flags`
25 /// [`SubprocessFlags`][crate::SubprocessFlags] for launched processes.
26 ///
27 /// Writeable | Construct Only
28 ///
29 /// # Implements
30 ///
31 /// [`trait@glib::ObjectExt`]
32 #[doc(alias = "GSubprocessLauncher")]
33 pub struct SubprocessLauncher(Object<ffi::GSubprocessLauncher>);
34
35 match fn {
36 type_ => || ffi::g_subprocess_launcher_get_type(),
37 }
38}
39
40impl SubprocessLauncher {
41 /// Creates a new #GSubprocessLauncher.
42 ///
43 /// The launcher is created with the default options. A copy of the
44 /// environment of the calling process is made at the time of this call
45 /// and will be used as the environment that the process is launched in.
46 /// ## `flags`
47 /// #GSubprocessFlags
48 #[doc(alias = "g_subprocess_launcher_new")]
49 pub fn new(flags: SubprocessFlags) -> SubprocessLauncher {
50 unsafe { from_glib_full(ffi::g_subprocess_launcher_new(flags.into_glib())) }
51 }
52
53 /// Closes all the file descriptors previously passed to the object with
54 /// g_subprocess_launcher_take_fd(), g_subprocess_launcher_take_stderr_fd(), etc.
55 ///
56 /// After calling this method, any subsequent calls to g_subprocess_launcher_spawn() or g_subprocess_launcher_spawnv() will
57 /// return [`IOErrorEnum::Closed`][crate::IOErrorEnum::Closed]. This method is idempotent if
58 /// called more than once.
59 ///
60 /// This function is called automatically when the #GSubprocessLauncher
61 /// is disposed, but is provided separately so that garbage collected
62 /// language bindings can call it earlier to guarantee when FDs are closed.
63 #[cfg(unix)]
64 #[cfg_attr(docsrs, doc(cfg(unix)))]
65 #[cfg(feature = "v2_68")]
66 #[cfg_attr(docsrs, doc(cfg(feature = "v2_68")))]
67 #[doc(alias = "g_subprocess_launcher_close")]
68 pub fn close(&self) {
69 unsafe {
70 ffi::g_subprocess_launcher_close(self.to_glib_none().0);
71 }
72 }
73
74 /// Returns the value of the environment variable @variable in the
75 /// environment of processes launched from this launcher.
76 ///
77 /// On UNIX, the returned string can be an arbitrary byte string.
78 /// On Windows, it will be UTF-8.
79 /// ## `variable`
80 /// the environment variable to get
81 ///
82 /// # Returns
83 ///
84 /// the value of the environment variable,
85 /// [`None`] if unset
86 #[doc(alias = "g_subprocess_launcher_getenv")]
87 pub fn getenv(&self, variable: impl AsRef<std::path::Path>) -> Option<std::path::PathBuf> {
88 unsafe {
89 from_glib_none(ffi::g_subprocess_launcher_getenv(
90 self.to_glib_none().0,
91 variable.as_ref().to_glib_none().0,
92 ))
93 }
94 }
95
96 /// Sets up a child setup function.
97 ///
98 /// The child setup function will be called after fork() but before
99 /// exec() on the child's side.
100 ///
101 /// @destroy_notify will not be automatically called on the child's side
102 /// of the fork(). It will only be called when the last reference on the
103 /// #GSubprocessLauncher is dropped or when a new child setup function is
104 /// given.
105 ///
106 /// [`None`] can be given as @child_setup to disable the functionality.
107 ///
108 /// Child setup functions are only available on UNIX.
109 /// ## `child_setup`
110 /// a #GSpawnChildSetupFunc to use as the child setup function
111 /// ## `destroy_notify`
112 /// a #GDestroyNotify for @user_data
113 #[cfg(unix)]
114 #[cfg_attr(docsrs, doc(cfg(unix)))]
115 #[doc(alias = "g_subprocess_launcher_set_child_setup")]
116 pub fn set_child_setup<P: Fn() + 'static>(&self, child_setup: P) {
117 let child_setup_data: Box_<P> = Box_::new(child_setup);
118 unsafe extern "C" fn child_setup_func<P: Fn() + 'static>(data: glib::ffi::gpointer) {
119 let callback = &*(data as *mut P);
120 (*callback)()
121 }
122 let child_setup = Some(child_setup_func::<P> as _);
123 unsafe extern "C" fn destroy_notify_func<P: Fn() + 'static>(data: glib::ffi::gpointer) {
124 let _callback = Box_::from_raw(data as *mut P);
125 }
126 let destroy_call3 = Some(destroy_notify_func::<P> as _);
127 let super_callback0: Box_<P> = child_setup_data;
128 unsafe {
129 ffi::g_subprocess_launcher_set_child_setup(
130 self.to_glib_none().0,
131 child_setup,
132 Box_::into_raw(super_callback0) as *mut _,
133 destroy_call3,
134 );
135 }
136 }
137
138 /// Sets the current working directory that processes will be launched
139 /// with.
140 ///
141 /// By default processes are launched with the current working directory
142 /// of the launching process at the time of launch.
143 /// ## `cwd`
144 /// the cwd for launched processes
145 #[doc(alias = "g_subprocess_launcher_set_cwd")]
146 pub fn set_cwd(&self, cwd: impl AsRef<std::path::Path>) {
147 unsafe {
148 ffi::g_subprocess_launcher_set_cwd(
149 self.to_glib_none().0,
150 cwd.as_ref().to_glib_none().0,
151 );
152 }
153 }
154
155 /// Sets the flags on the launcher.
156 ///
157 /// The default flags are [`SubprocessFlags::NONE`][crate::SubprocessFlags::NONE].
158 ///
159 /// You may not set flags that specify conflicting options for how to
160 /// handle a particular stdio stream (eg: specifying both
161 /// [`SubprocessFlags::STDIN_PIPE`][crate::SubprocessFlags::STDIN_PIPE] and
162 /// [`SubprocessFlags::STDIN_INHERIT`][crate::SubprocessFlags::STDIN_INHERIT]).
163 ///
164 /// You may also not set a flag that conflicts with a previous call to a
165 /// function like g_subprocess_launcher_set_stdin_file_path() or
166 /// g_subprocess_launcher_take_stdout_fd().
167 /// ## `flags`
168 /// #GSubprocessFlags
169 #[doc(alias = "g_subprocess_launcher_set_flags")]
170 pub fn set_flags(&self, flags: SubprocessFlags) {
171 unsafe {
172 ffi::g_subprocess_launcher_set_flags(self.to_glib_none().0, flags.into_glib());
173 }
174 }
175
176 /// Sets the file path to use as the stderr for spawned processes.
177 ///
178 /// If @path is [`None`] then any previously given path is unset.
179 ///
180 /// The file will be created or truncated when the process is spawned, as
181 /// would be the case if using '2>' at the shell.
182 ///
183 /// If you want to send both stdout and stderr to the same file then use
184 /// [`SubprocessFlags::STDERR_MERGE`][crate::SubprocessFlags::STDERR_MERGE].
185 ///
186 /// You may not set a stderr file path if a stderr fd is already set or
187 /// if the launcher flags contain any flags directing stderr elsewhere.
188 ///
189 /// This feature is only available on UNIX.
190 /// ## `path`
191 /// a filename or [`None`]
192 #[cfg(unix)]
193 #[cfg_attr(docsrs, doc(cfg(unix)))]
194 #[doc(alias = "g_subprocess_launcher_set_stderr_file_path")]
195 pub fn set_stderr_file_path(&self, path: Option<impl AsRef<std::path::Path>>) {
196 unsafe {
197 ffi::g_subprocess_launcher_set_stderr_file_path(
198 self.to_glib_none().0,
199 path.as_ref().map(|p| p.as_ref()).to_glib_none().0,
200 );
201 }
202 }
203
204 /// Sets the file path to use as the stdin for spawned processes.
205 ///
206 /// If @path is [`None`] then any previously given path is unset.
207 ///
208 /// The file must exist or spawning the process will fail.
209 ///
210 /// You may not set a stdin file path if a stdin fd is already set or if
211 /// the launcher flags contain any flags directing stdin elsewhere.
212 ///
213 /// This feature is only available on UNIX.
214 /// ## `path`
215 /// a filename or [`None`]
216 #[cfg(unix)]
217 #[cfg_attr(docsrs, doc(cfg(unix)))]
218 #[doc(alias = "g_subprocess_launcher_set_stdin_file_path")]
219 pub fn set_stdin_file_path(&self, path: Option<impl AsRef<std::path::Path>>) {
220 unsafe {
221 ffi::g_subprocess_launcher_set_stdin_file_path(
222 self.to_glib_none().0,
223 path.as_ref().map(|p| p.as_ref()).to_glib_none().0,
224 );
225 }
226 }
227
228 /// Sets the file path to use as the stdout for spawned processes.
229 ///
230 /// If @path is [`None`] then any previously given path is unset.
231 ///
232 /// The file will be created or truncated when the process is spawned, as
233 /// would be the case if using '>' at the shell.
234 ///
235 /// You may not set a stdout file path if a stdout fd is already set or
236 /// if the launcher flags contain any flags directing stdout elsewhere.
237 ///
238 /// This feature is only available on UNIX.
239 /// ## `path`
240 /// a filename or [`None`]
241 #[cfg(unix)]
242 #[cfg_attr(docsrs, doc(cfg(unix)))]
243 #[doc(alias = "g_subprocess_launcher_set_stdout_file_path")]
244 pub fn set_stdout_file_path(&self, path: Option<impl AsRef<std::path::Path>>) {
245 unsafe {
246 ffi::g_subprocess_launcher_set_stdout_file_path(
247 self.to_glib_none().0,
248 path.as_ref().map(|p| p.as_ref()).to_glib_none().0,
249 );
250 }
251 }
252
253 /// Sets the environment variable @variable in the environment of
254 /// processes launched from this launcher.
255 ///
256 /// On UNIX, both the variable's name and value can be arbitrary byte
257 /// strings, except that the variable's name cannot contain '='.
258 /// On Windows, they should be in UTF-8.
259 /// ## `variable`
260 /// the environment variable to set,
261 /// must not contain '='
262 /// ## `value`
263 /// the new value for the variable
264 /// ## `overwrite`
265 /// whether to change the variable if it already exists
266 #[doc(alias = "g_subprocess_launcher_setenv")]
267 pub fn setenv(
268 &self,
269 variable: impl AsRef<std::ffi::OsStr>,
270 value: impl AsRef<std::ffi::OsStr>,
271 overwrite: bool,
272 ) {
273 unsafe {
274 ffi::g_subprocess_launcher_setenv(
275 self.to_glib_none().0,
276 variable.as_ref().to_glib_none().0,
277 value.as_ref().to_glib_none().0,
278 overwrite.into_glib(),
279 );
280 }
281 }
282
283 //#[doc(alias = "g_subprocess_launcher_spawn")]
284 //pub fn spawn(&self, error: &mut glib::Error, argv0: &str, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) -> Subprocess {
285 // unsafe { TODO: call ffi:g_subprocess_launcher_spawn() }
286 //}
287
288 /// Creates a #GSubprocess given a provided varargs list of arguments.
289 /// ## `argv0`
290 /// Command line arguments
291 ///
292 /// # Returns
293 ///
294 /// A new #GSubprocess, or [`None`] on error (and @error will be set)
295 #[doc(alias = "g_subprocess_launcher_spawnv")]
296 #[doc(alias = "spawnv")]
297 pub fn spawn(&self, argv: &[&std::ffi::OsStr]) -> Result<Subprocess, glib::Error> {
298 unsafe {
299 let mut error = std::ptr::null_mut();
300 let ret = ffi::g_subprocess_launcher_spawnv(
301 self.to_glib_none().0,
302 argv.to_glib_none().0,
303 &mut error,
304 );
305 if error.is_null() {
306 Ok(from_glib_full(ret))
307 } else {
308 Err(from_glib_full(error))
309 }
310 }
311 }
312
313 /// Removes the environment variable @variable from the environment of
314 /// processes launched from this launcher.
315 ///
316 /// On UNIX, the variable's name can be an arbitrary byte string not
317 /// containing '='. On Windows, it should be in UTF-8.
318 /// ## `variable`
319 /// the environment variable to unset,
320 /// must not contain '='
321 #[doc(alias = "g_subprocess_launcher_unsetenv")]
322 pub fn unsetenv(&self, variable: impl AsRef<std::ffi::OsStr>) {
323 unsafe {
324 ffi::g_subprocess_launcher_unsetenv(
325 self.to_glib_none().0,
326 variable.as_ref().to_glib_none().0,
327 );
328 }
329 }
330}