src/libstd/sys/unix/ext.rs

   1 // Copyright 2014 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 //! Experimental extensions to `std` for Unix platforms.
  12 //!
  13 //! For now, this module is limited to extracting file descriptors,
  14 //! but its functionality will grow over time.
  15 //!
  16 //! # Example
  17 //!
  18 //! ```no_run
  19 //! use std::fs::File;
  20 //! use std::os::unix::prelude::*;
  21 //!
  22 //! fn main() {
  23 //!     let f = File::create("foo.txt").unwrap();
  24 //!     let fd = f.as_raw_fd();
  25 //!
  26 //!     // use fd with native unix bindings
  27 //! }
  28 //! ```
  29
  30 #![stable(feature = "rust1", since = "1.0.0")]
  31
  32 /// Unix-specific extensions to general I/O primitives
  33 #[stable(feature = "rust1", since = "1.0.0")]
  34 pub mod io {
  35     use fs;
  36     use libc;
  37     use net;
  38     use sys_common::{net2, AsInner, FromInner};
  39     use sys;
  40
  41     /// Raw file descriptors.
  42     #[stable(feature = "rust1", since = "1.0.0")]
  43     pub type RawFd = libc::c_int;
  44
  45     /// A trait to extract the raw unix file descriptor from an underlying
  46     /// object.
  47     ///
  48     /// This is only available on unix platforms and must be imported in order
  49     /// to call the method. Windows platforms have a corresponding `AsRawHandle`
  50     /// and `AsRawSocket` set of traits.
  51     #[stable(feature = "rust1", since = "1.0.0")]
  52     pub trait AsRawFd {
  53         /// Extracts the raw file descriptor.
  54         ///
  55         /// This method does **not** pass ownership of the raw file descriptor
  56         /// to the caller. The descriptor is only guarantee to be valid while
  57         /// the original object has not yet been destroyed.
  58         #[stable(feature = "rust1", since = "1.0.0")]
  59         fn as_raw_fd(&self) -> RawFd;
  60     }
  61
  62     /// A trait to express the ability to construct an object from a raw file
  63     /// descriptor.
  64     #[unstable(feature = "from_raw_os",
  65                reason = "recent addition to std::os::unix::io")]
  66     pub trait FromRawFd {
  67         /// Constructs a new instances of `Self` from the given raw file
  68         /// descriptor.
  69         ///
  70         /// This function **consumes ownership** of the specified file
  71         /// descriptor. The returned object will take responsibility for closing
  72         /// it when the object goes out of scope.
  73         ///
  74         /// This function is also unsafe as the primitives currently returned
  75         /// have the contract that they are the sole owner of the file
  76         /// descriptor they are wrapping. Usage of this function could
  77         /// accidentally allow violating this contract which can cause memory
  78         /// unsafety in code that relies on it being true.
  79         unsafe fn from_raw_fd(fd: RawFd) -> Self;
  80     }
  81
  82     #[stable(feature = "rust1", since = "1.0.0")]
  83     impl AsRawFd for fs::File {
  84         fn as_raw_fd(&self) -> RawFd {
  85             self.as_inner().fd().raw()
  86         }
  87     }
  88     #[unstable(feature = "from_raw_os", reason = "trait is unstable")]
  89     impl FromRawFd for fs::File {
  90         unsafe fn from_raw_fd(fd: RawFd) -> fs::File {
  91             fs::File::from_inner(sys::fs2::File::from_inner(fd))
  92         }
  93     }
  94
  95     #[stable(feature = "rust1", since = "1.0.0")]
  96     impl AsRawFd for net::TcpStream {
  97         fn as_raw_fd(&self) -> RawFd { *self.as_inner().socket().as_inner() }
  98     }
  99     #[stable(feature = "rust1", since = "1.0.0")]
 100     impl AsRawFd for net::TcpListener {
 101         fn as_raw_fd(&self) -> RawFd { *self.as_inner().socket().as_inner() }
 102     }
 103     #[stable(feature = "rust1", since = "1.0.0")]
 104     impl AsRawFd for net::UdpSocket {
 105         fn as_raw_fd(&self) -> RawFd { *self.as_inner().socket().as_inner() }
 106     }
 107
 108     #[unstable(feature = "from_raw_os", reason = "trait is unstable")]
 109     impl FromRawFd for net::TcpStream {
 110         unsafe fn from_raw_fd(fd: RawFd) -> net::TcpStream {
 111             let socket = sys::net::Socket::from_inner(fd);
 112             net::TcpStream::from_inner(net2::TcpStream::from_inner(socket))
 113         }
 114     }
 115     #[unstable(feature = "from_raw_os", reason = "trait is unstable")]
 116     impl FromRawFd for net::TcpListener {
 117         unsafe fn from_raw_fd(fd: RawFd) -> net::TcpListener {
 118             let socket = sys::net::Socket::from_inner(fd);
 119             net::TcpListener::from_inner(net2::TcpListener::from_inner(socket))
 120         }
 121     }
 122     #[unstable(feature = "from_raw_os", reason = "trait is unstable")]
 123     impl FromRawFd for net::UdpSocket {
 124         unsafe fn from_raw_fd(fd: RawFd) -> net::UdpSocket {
 125             let socket = sys::net::Socket::from_inner(fd);
 126             net::UdpSocket::from_inner(net2::UdpSocket::from_inner(socket))
 127         }
 128     }
 129 }
 130
 131 ////////////////////////////////////////////////////////////////////////////////
 132 // OsString and OsStr
 133 ////////////////////////////////////////////////////////////////////////////////
 134
 135 /// Unix-specific extension to the primitives in the `std::ffi` module
 136 #[stable(feature = "rust1", since = "1.0.0")]
 137 pub mod ffi {
 138     use ffi::{OsStr, OsString};
 139     use mem;
 140     use prelude::v1::*;
 141     use sys::os_str::Buf;
 142     use sys_common::{FromInner, IntoInner, AsInner};
 143
 144     /// Unix-specific extensions to `OsString`.
 145     #[stable(feature = "rust1", since = "1.0.0")]
 146     pub trait OsStringExt {
 147         /// Creates an `OsString` from a byte vector.
 148         #[stable(feature = "rust1", since = "1.0.0")]
 149         fn from_vec(vec: Vec<u8>) -> Self;
 150
 151         /// Yields the underlying byte vector of this `OsString`.
 152         #[stable(feature = "rust1", since = "1.0.0")]
 153         fn into_vec(self) -> Vec<u8>;
 154     }
 155
 156     #[stable(feature = "rust1", since = "1.0.0")]
 157     impl OsStringExt for OsString {
 158         fn from_vec(vec: Vec<u8>) -> OsString {
 159             FromInner::from_inner(Buf { inner: vec })
 160         }
 161         fn into_vec(self) -> Vec<u8> {
 162             self.into_inner().inner
 163         }
 164     }
 165
 166     /// Unix-specific extensions to `OsStr`.
 167     #[stable(feature = "rust1", since = "1.0.0")]
 168     pub trait OsStrExt {
 169         #[stable(feature = "rust1", since = "1.0.0")]
 170         fn from_bytes(slice: &[u8]) -> &Self;
 171
 172         /// Gets the underlying byte view of the `OsStr` slice.
 173         #[stable(feature = "rust1", since = "1.0.0")]
 174         fn as_bytes(&self) -> &[u8];
 175     }
 176
 177     #[stable(feature = "rust1", since = "1.0.0")]
 178     impl OsStrExt for OsStr {
 179         fn from_bytes(slice: &[u8]) -> &OsStr {
 180             unsafe { mem::transmute(slice) }
 181         }
 182         fn as_bytes(&self) -> &[u8] {
 183             &self.as_inner().inner
 184         }
 185     }
 186 }
 187
 188 /// Unix-specific extensions to primitives in the `std::fs` module.
 189 #[unstable(feature = "fs_ext",
 190            reason = "may want a more useful mode abstraction")]
 191 pub mod fs {
 192     use sys_common::{FromInner, AsInner, AsInnerMut};
 193     use fs::{Permissions, OpenOptions};
 194
 195     /// Unix-specific extensions to `Permissions`
 196     pub trait PermissionsExt {
 197         fn mode(&self) -> i32;
 198         fn set_mode(&mut self, mode: i32);
 199     }
 200
 201     impl PermissionsExt for Permissions {
 202         fn mode(&self) -> i32 { self.as_inner().mode() }
 203
 204         fn set_mode(&mut self, mode: i32) {
 205             *self = FromInner::from_inner(FromInner::from_inner(mode));
 206         }
 207     }
 208
 209     /// Unix-specific extensions to `OpenOptions`
 210     pub trait OpenOptionsExt {
 211         /// Sets the mode bits that a new file will be created with.
 212         ///
 213         /// If a new file is created as part of a `File::open_opts` call then this
 214         /// specified `mode` will be used as the permission bits for the new file.
 215         fn mode(&mut self, mode: i32) -> &mut Self;
 216     }
 217
 218     impl OpenOptionsExt for OpenOptions {
 219         fn mode(&mut self, mode: i32) -> &mut OpenOptions {
 220             self.as_inner_mut().mode(mode); self
 221         }
 222     }
 223 }
 224
 225 ////////////////////////////////////////////////////////////////////////////////
 226 // Process and Command
 227 ////////////////////////////////////////////////////////////////////////////////
 228
 229 /// Unix-specific extensions to primitives in the `std::process` module.
 230 #[stable(feature = "rust1", since = "1.0.0")]
 231 pub mod process {
 232     use prelude::v1::*;
 233     use libc::{uid_t, gid_t};
 234     use process;
 235     use sys;
 236     use sys_common::{AsInnerMut, AsInner};
 237
 238     /// Unix-specific extensions to the `std::process::Command` builder
 239     #[stable(feature = "rust1", since = "1.0.0")]
 240     pub trait CommandExt {
 241         /// Sets the child process's user id. This translates to a
 242         /// `setuid` call in the child process. Failure in the `setuid`
 243         /// call will cause the spawn to fail.
 244         #[stable(feature = "rust1", since = "1.0.0")]
 245         fn uid(&mut self, id: uid_t) -> &mut process::Command;
 246
 247         /// Similar to `uid`, but sets the group id of the child process. This has
 248         /// the same semantics as the `uid` field.
 249         #[stable(feature = "rust1", since = "1.0.0")]
 250         fn gid(&mut self, id: gid_t) -> &mut process::Command;
 251     }
 252
 253     #[stable(feature = "rust1", since = "1.0.0")]
 254     impl CommandExt for process::Command {
 255         fn uid(&mut self, id: uid_t) -> &mut process::Command {
 256             self.as_inner_mut().uid = Some(id);
 257             self
 258         }
 259
 260         fn gid(&mut self, id: gid_t) -> &mut process::Command {
 261             self.as_inner_mut().gid = Some(id);
 262             self
 263         }
 264     }
 265
 266     /// Unix-specific extensions to `std::process::ExitStatus`
 267     #[stable(feature = "rust1", since = "1.0.0")]
 268     pub trait ExitStatusExt {
 269         /// If the process was terminated by a signal, returns that signal.
 270         #[stable(feature = "rust1", since = "1.0.0")]
 271         fn signal(&self) -> Option<i32>;
 272     }
 273
 274     #[stable(feature = "rust1", since = "1.0.0")]
 275     impl ExitStatusExt for process::ExitStatus {
 276         fn signal(&self) -> Option<i32> {
 277             match *self.as_inner() {
 278                 sys::process2::ExitStatus::Signal(s) => Some(s),
 279                 _ => None
 280             }
 281         }
 282     }
 283 }
 284
 285 ////////////////////////////////////////////////////////////////////////////////
 286 // Prelude
 287 ////////////////////////////////////////////////////////////////////////////////
 288
 289 /// A prelude for conveniently writing platform-specific code.
 290 ///
 291 /// Includes all extension traits, and some important type definitions.
 292 #[stable(feature = "rust1", since = "1.0.0")]
 293 pub mod prelude {
 294     #[doc(no_inline)]
 295     pub use super::io::{RawFd, AsRawFd};
 296     #[doc(no_inline)] #[stable(feature = "rust1", since = "1.0.0")]
 297     pub use super::ffi::{OsStrExt, OsStringExt};
 298     #[doc(no_inline)]
 299     pub use super::fs::{PermissionsExt, OpenOptionsExt};
 300     #[doc(no_inline)] #[stable(feature = "rust1", since = "1.0.0")]
 301     pub use super::process::{CommandExt, ExitStatusExt};
 302 }