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.
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.
11 //! Unix-specific extensions to primitives in the `std::process` module.
13 #![stable(feature = "rust1", since = "1.0.0")]
18 use os::unix::io::{FromRawFd, RawFd, AsRawFd, IntoRawFd};
19 use os::unix::raw::{uid_t, gid_t};
22 use sys_common::{AsInnerMut, AsInner, FromInner, IntoInner};
24 /// Unix-specific extensions to the `std::process::Command` builder
25 #[stable(feature = "rust1", since = "1.0.0")]
26 pub trait CommandExt {
27 /// Sets the child process's user id. This translates to a
28 /// `setuid` call in the child process. Failure in the `setuid`
29 /// call will cause the spawn to fail.
30 #[stable(feature = "rust1", since = "1.0.0")]
31 fn uid(&mut self, id: uid_t) -> &mut process::Command;
33 /// Similar to `uid`, but sets the group id of the child process. This has
34 /// the same semantics as the `uid` field.
35 #[stable(feature = "rust1", since = "1.0.0")]
36 fn gid(&mut self, id: gid_t) -> &mut process::Command;
38 /// Create a new session (cf. `setsid(2)`) for the child process. This means
39 /// that the child is the leader of a new process group. The parent process
40 /// remains the child reaper of the new process.
42 /// This is not enough to create a daemon process. The *init* process should
43 /// be the child reaper of a daemon. This can be achieved if the parent
44 /// process exit. Moreover, a daemon should not have a controlling terminal.
45 /// To achieve this, a session leader (the child) must spawn another process
46 /// (the daemon) in the same session.
47 #[unstable(feature = "process_session_leader", reason = "recently added",
49 fn session_leader(&mut self, on: bool) -> &mut process::Command;
51 /// Schedules a closure to be run just before the `exec` function is
54 /// The closure is allowed to return an I/O error whose OS error code will
55 /// be communicated back to the parent and returned as an error from when
56 /// the spawn was requested.
58 /// Multiple closures can be registered and they will be called in order of
59 /// their registration. If a closure returns `Err` then no further closures
60 /// will be called and the spawn operation will immediately return with a
65 /// This closure will be run in the context of the child process after a
66 /// `fork`. This primarily means that any modificatons made to memory on
67 /// behalf of this closure will **not** be visible to the parent process.
68 /// This is often a very constrained environment where normal operations
69 /// like `malloc` or acquiring a mutex are not guaranteed to work (due to
70 /// other threads perhaps still running when the `fork` was run).
72 /// When this closure is run, aspects such as the stdio file descriptors and
73 /// working directory have successfully been changed, so output to these
74 /// locations may not appear where intended.
75 #[unstable(feature = "process_exec", issue = "31398")]
76 fn before_exec<F>(&mut self, f: F) -> &mut process::Command
77 where F: FnMut() -> io::Result<()> + Send + Sync + 'static;
80 #[stable(feature = "rust1", since = "1.0.0")]
81 impl CommandExt for process::Command {
82 fn uid(&mut self, id: uid_t) -> &mut process::Command {
83 self.as_inner_mut().uid(id);
87 fn gid(&mut self, id: gid_t) -> &mut process::Command {
88 self.as_inner_mut().gid(id);
92 fn session_leader(&mut self, on: bool) -> &mut process::Command {
93 self.as_inner_mut().session_leader(on);
97 fn before_exec<F>(&mut self, f: F) -> &mut process::Command
98 where F: FnMut() -> io::Result<()> + Send + Sync + 'static
100 self.as_inner_mut().before_exec(Box::new(f));
105 /// Unix-specific extensions to `std::process::ExitStatus`
106 #[stable(feature = "rust1", since = "1.0.0")]
107 pub trait ExitStatusExt {
108 /// If the process was terminated by a signal, returns that signal.
109 #[stable(feature = "rust1", since = "1.0.0")]
110 fn signal(&self) -> Option<i32>;
113 #[stable(feature = "rust1", since = "1.0.0")]
114 impl ExitStatusExt for process::ExitStatus {
115 fn signal(&self) -> Option<i32> {
116 self.as_inner().signal()
120 #[stable(feature = "process_extensions", since = "1.2.0")]
121 impl FromRawFd for process::Stdio {
122 unsafe fn from_raw_fd(fd: RawFd) -> process::Stdio {
123 let fd = sys::fd::FileDesc::new(fd);
124 let io = sys::process::Stdio::Fd(fd);
125 process::Stdio::from_inner(io)
129 #[stable(feature = "process_extensions", since = "1.2.0")]
130 impl AsRawFd for process::ChildStdin {
131 fn as_raw_fd(&self) -> RawFd {
132 self.as_inner().fd().raw()
136 #[stable(feature = "process_extensions", since = "1.2.0")]
137 impl AsRawFd for process::ChildStdout {
138 fn as_raw_fd(&self) -> RawFd {
139 self.as_inner().fd().raw()
143 #[stable(feature = "process_extensions", since = "1.2.0")]
144 impl AsRawFd for process::ChildStderr {
145 fn as_raw_fd(&self) -> RawFd {
146 self.as_inner().fd().raw()
150 #[stable(feature = "process_extensions", since = "1.2.0")]
151 impl IntoRawFd for process::ChildStdin {
152 fn into_raw_fd(self) -> RawFd {
153 self.into_inner().into_fd().into_raw()
157 #[stable(feature = "process_extensions", since = "1.2.0")]
158 impl IntoRawFd for process::ChildStdout {
159 fn into_raw_fd(self) -> RawFd {
160 self.into_inner().into_fd().into_raw()
164 #[stable(feature = "process_extensions", since = "1.2.0")]
165 impl IntoRawFd for process::ChildStderr {
166 fn into_raw_fd(self) -> RawFd {
167 self.into_inner().into_fd().into_raw()