src/libstd/sys/unix/ext/process.rs

   1 // Copyright 2015 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 //! Unix-specific extensions to primitives in the `std::process` module.
  12
  13 #![stable(feature = "rust1", since = "1.0.0")]
  14
  15 use io;
  16 use os::unix::io::{FromRawFd, RawFd, AsRawFd, IntoRawFd};
  17 use process;
  18 use sys;
  19 use sys_common::{AsInnerMut, AsInner, FromInner, IntoInner};
  20
  21 /// Unix-specific extensions to the `std::process::Command` builder
  22 #[stable(feature = "rust1", since = "1.0.0")]
  23 pub trait CommandExt {
  24     /// Sets the child process's user id. This translates to a
  25     /// `setuid` call in the child process. Failure in the `setuid`
  26     /// call will cause the spawn to fail.
  27     #[stable(feature = "rust1", since = "1.0.0")]
  28     fn uid(&mut self, id: u32) -> &mut process::Command;
  29
  30     /// Similar to `uid`, but sets the group id of the child process. This has
  31     /// the same semantics as the `uid` field.
  32     #[stable(feature = "rust1", since = "1.0.0")]
  33     fn gid(&mut self, id: u32) -> &mut process::Command;
  34
  35     /// Schedules a closure to be run just before the `exec` function is
  36     /// invoked.
  37     ///
  38     /// The closure is allowed to return an I/O error whose OS error code will
  39     /// be communicated back to the parent and returned as an error from when
  40     /// the spawn was requested.
  41     ///
  42     /// Multiple closures can be registered and they will be called in order of
  43     /// their registration. If a closure returns `Err` then no further closures
  44     /// will be called and the spawn operation will immediately return with a
  45     /// failure.
  46     ///
  47     /// # Notes
  48     ///
  49     /// This closure will be run in the context of the child process after a
  50     /// `fork`. This primarily means that any modificatons made to memory on
  51     /// behalf of this closure will **not** be visible to the parent process.
  52     /// This is often a very constrained environment where normal operations
  53     /// like `malloc` or acquiring a mutex are not guaranteed to work (due to
  54     /// other threads perhaps still running when the `fork` was run).
  55     ///
  56     /// When this closure is run, aspects such as the stdio file descriptors and
  57     /// working directory have successfully been changed, so output to these
  58     /// locations may not appear where intended.
  59     #[unstable(feature = "process_exec", issue = "31398")]
  60     fn before_exec<F>(&mut self, f: F) -> &mut process::Command
  61         where F: FnMut() -> io::Result<()> + Send + Sync + 'static;
  62
  63     /// Performs all the required setup by this `Command`, followed by calling
  64     /// the `execvp` syscall.
  65     ///
  66     /// On success this function will not return, and otherwise it will return
  67     /// an error indicating why the exec (or another part of the setup of the
  68     /// `Command`) failed.
  69     ///
  70     /// This function, unlike `spawn`, will **not** `fork` the process to create
  71     /// a new child. Like spawn, however, the default behavior for the stdio
  72     /// descriptors will be to inherited from the current process.
  73     ///
  74     /// # Notes
  75     ///
  76     /// The process may be in a "broken state" if this function returns in
  77     /// error. For example the working directory, environment variables, signal
  78     /// handling settings, various user/group information, or aspects of stdio
  79     /// file descriptors may have changed. If a "transactional spawn" is
  80     /// required to gracefully handle errors it is recommended to use the
  81     /// cross-platform `spawn` instead.
  82     #[stable(feature = "process_exec2", since = "1.9.0")]
  83     fn exec(&mut self) -> io::Error;
  84 }
  85
  86 #[stable(feature = "rust1", since = "1.0.0")]
  87 impl CommandExt for process::Command {
  88     fn uid(&mut self, id: u32) -> &mut process::Command {
  89         self.as_inner_mut().uid(id);
  90         self
  91     }
  92
  93     fn gid(&mut self, id: u32) -> &mut process::Command {
  94         self.as_inner_mut().gid(id);
  95         self
  96     }
  97
  98     fn before_exec<F>(&mut self, f: F) -> &mut process::Command
  99         where F: FnMut() -> io::Result<()> + Send + Sync + 'static
 100     {
 101         self.as_inner_mut().before_exec(Box::new(f));
 102         self
 103     }
 104
 105     fn exec(&mut self) -> io::Error {
 106         self.as_inner_mut().exec(sys::process::Stdio::Inherit)
 107     }
 108 }
 109
 110 /// Unix-specific extensions to `std::process::ExitStatus`
 111 #[stable(feature = "rust1", since = "1.0.0")]
 112 pub trait ExitStatusExt {
 113     /// Creates a new `ExitStatus` from the raw underlying `i32` return value of
 114     /// a process.
 115     #[stable(feature = "exit_status_from", since = "1.12.0")]
 116     fn from_raw(raw: i32) -> Self;
 117
 118     /// If the process was terminated by a signal, returns that signal.
 119     #[stable(feature = "rust1", since = "1.0.0")]
 120     fn signal(&self) -> Option<i32>;
 121 }
 122
 123 #[stable(feature = "rust1", since = "1.0.0")]
 124 impl ExitStatusExt for process::ExitStatus {
 125     fn from_raw(raw: i32) -> Self {
 126         process::ExitStatus::from_inner(From::from(raw))
 127     }
 128
 129     fn signal(&self) -> Option<i32> {
 130         self.as_inner().signal()
 131     }
 132 }
 133
 134 #[stable(feature = "process_extensions", since = "1.2.0")]
 135 impl FromRawFd for process::Stdio {
 136     unsafe fn from_raw_fd(fd: RawFd) -> process::Stdio {
 137         let fd = sys::fd::FileDesc::new(fd);
 138         let io = sys::process::Stdio::Fd(fd);
 139         process::Stdio::from_inner(io)
 140     }
 141 }
 142
 143 #[stable(feature = "process_extensions", since = "1.2.0")]
 144 impl AsRawFd for process::ChildStdin {
 145     fn as_raw_fd(&self) -> RawFd {
 146         self.as_inner().fd().raw()
 147     }
 148 }
 149
 150 #[stable(feature = "process_extensions", since = "1.2.0")]
 151 impl AsRawFd for process::ChildStdout {
 152     fn as_raw_fd(&self) -> RawFd {
 153         self.as_inner().fd().raw()
 154     }
 155 }
 156
 157 #[stable(feature = "process_extensions", since = "1.2.0")]
 158 impl AsRawFd for process::ChildStderr {
 159     fn as_raw_fd(&self) -> RawFd {
 160         self.as_inner().fd().raw()
 161     }
 162 }
 163
 164 #[stable(feature = "into_raw_os", since = "1.4.0")]
 165 impl IntoRawFd for process::ChildStdin {
 166     fn into_raw_fd(self) -> RawFd {
 167         self.into_inner().into_fd().into_raw()
 168     }
 169 }
 170
 171 #[stable(feature = "into_raw_os", since = "1.4.0")]
 172 impl IntoRawFd for process::ChildStdout {
 173     fn into_raw_fd(self) -> RawFd {
 174         self.into_inner().into_fd().into_raw()
 175     }
 176 }
 177
 178 #[stable(feature = "into_raw_os", since = "1.4.0")]
 179 impl IntoRawFd for process::ChildStderr {
 180     fn into_raw_fd(self) -> RawFd {
 181         self.into_inner().into_fd().into_raw()
 182     }
 183 }