gio/
subprocess_launcher.rs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
// Take a look at the license at the top of the repository in the LICENSE file.

#[cfg(any(unix, all(docsrs, unix)))]
use std::os::unix::io::IntoRawFd;

#[cfg(unix)]
use glib::translate::*;

#[cfg(unix)]
use crate::ffi;

use crate::SubprocessLauncher;

#[cfg(all(docsrs, not(unix)))]
pub trait IntoRawFd: Sized {
    fn into_raw_fd(self) -> i32 {
        0
    }
}

impl SubprocessLauncher {
    /// Transfer an arbitrary file descriptor from parent process to the
    /// child.  This function takes ownership of the @source_fd; it will be closed
    /// in the parent when @self is freed.
    ///
    /// By default, all file descriptors from the parent will be closed.
    /// This function allows you to create (for example) a custom `pipe()` or
    /// `socketpair()` before launching the process, and choose the target
    /// descriptor in the child.
    ///
    /// An example use case is GNUPG, which has a command line argument
    /// `--passphrase-fd` providing a file descriptor number where it expects
    /// the passphrase to be written.
    /// ## `source_fd`
    /// File descriptor in parent process
    /// ## `target_fd`
    /// Target descriptor for child process
    #[cfg(unix)]
    #[cfg_attr(docsrs, doc(cfg(unix)))]
    #[doc(alias = "g_subprocess_launcher_take_fd")]
    pub fn take_fd(&self, source_fd: impl IntoRawFd, target_fd: impl IntoRawFd) {
        unsafe {
            ffi::g_subprocess_launcher_take_fd(
                self.to_glib_none().0,
                source_fd.into_raw_fd(),
                target_fd.into_raw_fd(),
            );
        }
    }

    /// Sets the file descriptor to use as the stderr for spawned processes.
    ///
    /// If @fd is -1 then any previously given fd is unset.
    ///
    /// Note that the default behaviour is to pass stderr through to the
    /// stderr of the parent process.
    ///
    /// The passed @fd belongs to the #GSubprocessLauncher.  It will be
    /// automatically closed when the launcher is finalized.  The file
    /// descriptor will also be closed on the child side when executing the
    /// spawned process.
    ///
    /// You may not set a stderr fd if a stderr file path is already set or
    /// if the launcher flags contain any flags directing stderr elsewhere.
    ///
    /// This feature is only available on UNIX.
    /// ## `fd`
    /// a file descriptor, or -1
    #[cfg(unix)]
    #[cfg_attr(docsrs, doc(cfg(unix)))]
    #[doc(alias = "g_subprocess_launcher_take_stderr_fd")]
    pub fn take_stderr_fd(&self, fd: impl IntoRawFd) {
        unsafe {
            ffi::g_subprocess_launcher_take_stderr_fd(self.to_glib_none().0, fd.into_raw_fd());
        }
    }

    /// Sets the file descriptor to use as the stdin for spawned processes.
    ///
    /// If @fd is -1 then any previously given fd is unset.
    ///
    /// Note that if your intention is to have the stdin of the calling
    /// process inherited by the child then [`SubprocessFlags::STDIN_INHERIT`][crate::SubprocessFlags::STDIN_INHERIT]
    /// is a better way to go about doing that.
    ///
    /// The passed @fd is noted but will not be touched in the current
    /// process.  It is therefore necessary that it be kept open by the
    /// caller until the subprocess is spawned.  The file descriptor will
    /// also not be explicitly closed on the child side, so it must be marked
    /// O_CLOEXEC if that's what you want.
    ///
    /// You may not set a stdin fd if a stdin file path is already set or if
    /// the launcher flags contain any flags directing stdin elsewhere.
    ///
    /// This feature is only available on UNIX.
    /// ## `fd`
    /// a file descriptor, or -1
    #[cfg(unix)]
    #[cfg_attr(docsrs, doc(cfg(unix)))]
    #[doc(alias = "g_subprocess_launcher_take_stdin_fd")]
    pub fn take_stdin_fd(&self, fd: impl IntoRawFd) {
        unsafe {
            ffi::g_subprocess_launcher_take_stdin_fd(self.to_glib_none().0, fd.into_raw_fd());
        }
    }

    /// Sets the file descriptor to use as the stdout for spawned processes.
    ///
    /// If @fd is -1 then any previously given fd is unset.
    ///
    /// Note that the default behaviour is to pass stdout through to the
    /// stdout of the parent process.
    ///
    /// The passed @fd is noted but will not be touched in the current
    /// process.  It is therefore necessary that it be kept open by the
    /// caller until the subprocess is spawned.  The file descriptor will
    /// also not be explicitly closed on the child side, so it must be marked
    /// O_CLOEXEC if that's what you want.
    ///
    /// You may not set a stdout fd if a stdout file path is already set or
    /// if the launcher flags contain any flags directing stdout elsewhere.
    ///
    /// This feature is only available on UNIX.
    /// ## `fd`
    /// a file descriptor, or -1
    #[cfg(unix)]
    #[cfg_attr(docsrs, doc(cfg(unix)))]
    #[doc(alias = "g_subprocess_launcher_take_stdout_fd")]
    pub fn take_stdout_fd(&self, fd: impl IntoRawFd) {
        unsafe {
            ffi::g_subprocess_launcher_take_stdout_fd(self.to_glib_none().0, fd.into_raw_fd());
        }
    }
}