gio/

subprocess_launcher.rs

// 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::{AsFd, AsRawFd, IntoRawFd, OwnedFd};

use glib::translate::*;

use crate::ffi;
use crate::SubprocessLauncher;

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

impl SubprocessLauncher {
    /// Replace the entire environment of processes launched from this
    /// launcher with the given 'environ' variable.
    ///
    /// Typically you will build this variable by using g_listenv() to copy
    /// the process 'environ' and using the functions g_environ_setenv(),
    /// g_environ_unsetenv(), etc.
    ///
    /// As an alternative, you can use g_subprocess_launcher_setenv(),
    /// g_subprocess_launcher_unsetenv(), etc.
    ///
    /// Pass an empty array to set an empty environment. Pass [`None`] to inherit the
    /// parent process’ environment. As of GLib 2.54, the parent process’ environment
    /// will be copied when g_subprocess_launcher_set_environ() is called.
    /// Previously, it was copied when the subprocess was executed. This means the
    /// copied environment may now be modified (using g_subprocess_launcher_setenv(),
    /// etc.) before launching the subprocess.
    ///
    /// On UNIX, all strings in this array can be arbitrary byte strings.
    /// On Windows, they should be in UTF-8.
    /// ## `env`
    ///
    ///     the replacement environment
    #[doc(alias = "g_subprocess_launcher_set_environ")]
    pub fn set_environ(&self, env: &[std::ffi::OsString]) {
        unsafe {
            ffi::g_subprocess_launcher_set_environ(self.to_glib_none().0, env.to_glib_none().0);
        }
    }

    /// 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: OwnedFd, target_fd: impl AsFd) {
        let source_raw_fd = source_fd.into_raw_fd();
        let target_raw_fd = target_fd.as_fd().as_raw_fd();
        unsafe {
            ffi::g_subprocess_launcher_take_fd(self.to_glib_none().0, source_raw_fd, target_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: Option<OwnedFd>) {
        unsafe {
            let raw_fd = fd.map_or(-1, |fd| fd.into_raw_fd());
            ffi::g_subprocess_launcher_take_stderr_fd(self.to_glib_none().0, 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: Option<OwnedFd>) {
        let raw_fd = fd.map_or(-1, |fd| fd.into_raw_fd());
        unsafe {
            ffi::g_subprocess_launcher_take_stdin_fd(self.to_glib_none().0, 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: Option<OwnedFd>) {
        let raw_fd = fd.map_or(-1, |fd| fd.into_raw_fd());
        unsafe {
            ffi::g_subprocess_launcher_take_stdout_fd(self.to_glib_none().0, raw_fd);
        }
    }
}