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}