      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
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    154
    155
    156
    157
    158
    159
    160
    161
    162
    163
    164
    165
    166
    167
    168
    169
    170
    171
    172
    173
    174
    175
    176
    177
    178
    179
    180
    181
    182
    183
    184
    185
    186
    187
    188
    189
    190
    191
    192
    193
    194
    195
    196
    197
    198
    199
    200
    201
    202
    203

    // Copyright 2015 The Rust Project Developers. See the COPYRIGHT
    // file at the top-level directory of this distribution and at
    // http://rust-lang.org/COPYRIGHT.
    //
    // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
    // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
    // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
    // option. This file may not be copied, modified, or distributed
    // except according to those terms.

    //! Unix-specific extensions to primitives in the `std::process` module.

    #![stable(feature = "rust1", since = "1.0.0")]

    use io;
    use os::unix::io::{FromRawFd, RawFd, AsRawFd, IntoRawFd};
    use process;
    use sys;
    use sys_common::{AsInnerMut, AsInner, FromInner, IntoInner};

    /// Unix-specific extensions to the [`process::Command`] builder.
    ///
    /// [`process::Command`]: ../../../../std/process/struct.Command.html
    #[stable(feature = "rust1", since = "1.0.0")]
    pub trait CommandExt {
        /// Sets the child process's user id. This translates to a
        /// `setuid` call in the child process. Failure in the `setuid`
        /// call will cause the spawn to fail.
        #[stable(feature = "rust1", since = "1.0.0")]
        fn uid(&mut self, id: u32) -> &mut process::Command;

        /// Similar to `uid`, but sets the group id of the child process. This has
        /// the same semantics as the `uid` field.
        #[stable(feature = "rust1", since = "1.0.0")]
        fn gid(&mut self, id: u32) -> &mut process::Command;

        /// Schedules a closure to be run just before the `exec` function is
        /// invoked.
        ///
        /// The closure is allowed to return an I/O error whose OS error code will
        /// be communicated back to the parent and returned as an error from when
        /// the spawn was requested.
        ///
        /// Multiple closures can be registered and they will be called in order of
        /// their registration. If a closure returns `Err` then no further closures
        /// will be called and the spawn operation will immediately return with a
        /// failure.
        ///
        /// # Notes
        ///
        /// This closure will be run in the context of the child process after a
        /// `fork`. This primarily means that any modifications made to memory on
        /// behalf of this closure will **not** be visible to the parent process.
        /// This is often a very constrained environment where normal operations
        /// like `malloc` or acquiring a mutex are not guaranteed to work (due to
        /// other threads perhaps still running when the `fork` was run).
        ///
        /// When this closure is run, aspects such as the stdio file descriptors and
        /// working directory have successfully been changed, so output to these
        /// locations may not appear where intended.
        #[stable(feature = "process_exec", since = "1.15.0")]
        fn before_exec<F>(&mut self, f: F) -> &mut process::Command
            where F: FnMut() -> io::Result<()> + Send + Sync + 'static;

        /// Performs all the required setup by this `Command`, followed by calling
        /// the `execvp` syscall.
        ///
        /// On success this function will not return, and otherwise it will return
        /// an error indicating why the exec (or another part of the setup of the
        /// `Command`) failed.
        ///
        /// `exec` not returning has the same implications as calling
        /// [`process::exit`] – no destructors on the current stack or any other
        /// thread’s stack will be run. Therefore, it is recommended to only call
        /// `exec` at a point where it is fine to not run any destructors. Note,
        /// that the `execvp` syscall independently guarantees that all memory is
        /// freed and all file descriptors with the `CLOEXEC` option (set by default
        /// on all file descriptors opened by the standard library) are closed.
        ///
        /// This function, unlike `spawn`, will **not** `fork` the process to create
        /// a new child. Like spawn, however, the default behavior for the stdio
        /// descriptors will be to inherited from the current process.
        ///
        /// [`process::exit`]: ../../../process/fn.exit.html
        ///
        /// # Notes
        ///
        /// The process may be in a "broken state" if this function returns in
        /// error. For example the working directory, environment variables, signal
        /// handling settings, various user/group information, or aspects of stdio
        /// file descriptors may have changed. If a "transactional spawn" is
        /// required to gracefully handle errors it is recommended to use the
        /// cross-platform `spawn` instead.
        #[stable(feature = "process_exec2", since = "1.9.0")]
        fn exec(&mut self) -> io::Error;
    }

    #[stable(feature = "rust1", since = "1.0.0")]
    impl CommandExt for process::Command {
        fn uid(&mut self, id: u32) -> &mut process::Command {
            self.as_inner_mut().uid(id);
            self
        }

        fn gid(&mut self, id: u32) -> &mut process::Command {
            self.as_inner_mut().gid(id);
            self
        }

        fn before_exec<F>(&mut self, f: F) -> &mut process::Command
            where F: FnMut() -> io::Result<()> + Send + Sync + 'static
        {
            self.as_inner_mut().before_exec(Box::new(f));
            self
        }

        fn exec(&mut self) -> io::Error {
            self.as_inner_mut().exec(sys::process::Stdio::Inherit)
        }
    }

    /// Unix-specific extensions to [`process::ExitStatus`].
    ///
    /// [`process::ExitStatus`]: ../../../../std/process/struct.ExitStatus.html
    #[stable(feature = "rust1", since = "1.0.0")]
    pub trait ExitStatusExt {
        /// Creates a new `ExitStatus` from the raw underlying `i32` return value of
        /// a process.
        #[stable(feature = "exit_status_from", since = "1.12.0")]
        fn from_raw(raw: i32) -> Self;

        /// If the process was terminated by a signal, returns that signal.
        #[stable(feature = "rust1", since = "1.0.0")]
        fn signal(&self) -> Option<i32>;
    }

    #[stable(feature = "rust1", since = "1.0.0")]
    impl ExitStatusExt for process::ExitStatus {
        fn from_raw(raw: i32) -> Self {
            process::ExitStatus::from_inner(From::from(raw))
        }

        fn signal(&self) -> Option<i32> {
            self.as_inner().signal()
        }
    }

    #[stable(feature = "process_extensions", since = "1.2.0")]
    impl FromRawFd for process::Stdio {
        unsafe fn from_raw_fd(fd: RawFd) -> process::Stdio {
            let fd = sys::fd::FileDesc::new(fd);
            let io = sys::process::Stdio::Fd(fd);
            process::Stdio::from_inner(io)
        }
    }

    #[stable(feature = "process_extensions", since = "1.2.0")]
    impl AsRawFd for process::ChildStdin {
        fn as_raw_fd(&self) -> RawFd {
            self.as_inner().fd().raw()
        }
    }

    #[stable(feature = "process_extensions", since = "1.2.0")]
    impl AsRawFd for process::ChildStdout {
        fn as_raw_fd(&self) -> RawFd {
            self.as_inner().fd().raw()
        }
    }

    #[stable(feature = "process_extensions", since = "1.2.0")]
    impl AsRawFd for process::ChildStderr {
        fn as_raw_fd(&self) -> RawFd {
            self.as_inner().fd().raw()
        }
    }

    #[stable(feature = "into_raw_os", since = "1.4.0")]
    impl IntoRawFd for process::ChildStdin {
        fn into_raw_fd(self) -> RawFd {
            self.into_inner().into_fd().into_raw()
        }
    }

    #[stable(feature = "into_raw_os", since = "1.4.0")]
    impl IntoRawFd for process::ChildStdout {
        fn into_raw_fd(self) -> RawFd {
            self.into_inner().into_fd().into_raw()
        }
    }

    #[stable(feature = "into_raw_os", since = "1.4.0")]
    impl IntoRawFd for process::ChildStderr {
        fn into_raw_fd(self) -> RawFd {
            self.into_inner().into_fd().into_raw()
        }
    }

    /// Returns the OS-assigned process identifier associated with this process's parent.
    #[stable(feature = "unix_ppid", since = "1.27.0")]
    pub fn parent_id() -> u32 {
        ::sys::os::getppid()
    }

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g. `str,u8` or `String,struct:Vec,test`)