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 //! ```rust,ignore
  19 //! #![feature(globs)]
  20 //!
  21 //! use std::old_io::fs::File;
  22 //! use std::os::unix::prelude::*;
  23 //!
  24 //! fn main() {
  25 //!     let f = File::create(&Path::new("foo.txt")).unwrap();
  26 //!     let fd = f.as_raw_fd();
  27 //!
  28 //!     // use fd with native unix bindings
  29 //! }
  30 //! ```
  31
  32 #![stable(feature = "rust1", since = "1.0.0")]
  33
  34 /// Unix-specific extensions to general I/O primitives
  35 #[unstable(feature = "io_ext",
  36            reason = "may want a slightly different organization or a more \
  37                      general file descriptor primitive")]
  38 pub mod io {
  39     #[allow(deprecated)] use old_io;
  40     use fs;
  41     use libc;
  42     use net;
  43     use sys_common::AsInner;
  44
  45     /// Raw file descriptors.
  46     pub type Fd = libc::c_int;
  47
  48     /// Extract raw file descriptor
  49     pub trait AsRawFd {
  50         /// Extract the raw file descriptor, without taking any ownership.
  51         fn as_raw_fd(&self) -> Fd;
  52     }
  53
  54     #[allow(deprecated)]
  55     impl AsRawFd for old_io::fs::File {
  56         fn as_raw_fd(&self) -> Fd {
  57             self.as_inner().fd()
  58         }
  59     }
  60
  61     impl AsRawFd for fs::File {
  62         fn as_raw_fd(&self) -> Fd {
  63             self.as_inner().fd().raw()
  64         }
  65     }
  66
  67     #[allow(deprecated)]
  68     impl AsRawFd for old_io::pipe::PipeStream {
  69         fn as_raw_fd(&self) -> Fd {
  70             self.as_inner().fd()
  71         }
  72     }
  73
  74     #[allow(deprecated)]
  75     impl AsRawFd for old_io::net::pipe::UnixStream {
  76         fn as_raw_fd(&self) -> Fd {
  77             self.as_inner().fd()
  78         }
  79     }
  80
  81     #[allow(deprecated)]
  82     impl AsRawFd for old_io::net::pipe::UnixListener {
  83         fn as_raw_fd(&self) -> Fd {
  84             self.as_inner().fd()
  85         }
  86     }
  87
  88     #[allow(deprecated)]
  89     impl AsRawFd for old_io::net::pipe::UnixAcceptor {
  90         fn as_raw_fd(&self) -> Fd {
  91             self.as_inner().fd()
  92         }
  93     }
  94
  95     #[allow(deprecated)]
  96     impl AsRawFd for old_io::net::tcp::TcpStream {
  97         fn as_raw_fd(&self) -> Fd {
  98             self.as_inner().fd()
  99         }
 100     }
 101
 102     #[allow(deprecated)]
 103     impl AsRawFd for old_io::net::tcp::TcpListener {
 104         fn as_raw_fd(&self) -> Fd {
 105             self.as_inner().fd()
 106         }
 107     }
 108
 109     #[allow(deprecated)]
 110     impl AsRawFd for old_io::net::tcp::TcpAcceptor {
 111         fn as_raw_fd(&self) -> Fd {
 112             self.as_inner().fd()
 113         }
 114     }
 115
 116     #[allow(deprecated)]
 117     impl AsRawFd for old_io::net::udp::UdpSocket {
 118         fn as_raw_fd(&self) -> Fd {
 119             self.as_inner().fd()
 120         }
 121     }
 122
 123     impl AsRawFd for net::TcpStream {
 124         fn as_raw_fd(&self) -> Fd { *self.as_inner().socket().as_inner() }
 125     }
 126     impl AsRawFd for net::TcpListener {
 127         fn as_raw_fd(&self) -> Fd { *self.as_inner().socket().as_inner() }
 128     }
 129     impl AsRawFd for net::UdpSocket {
 130         fn as_raw_fd(&self) -> Fd { *self.as_inner().socket().as_inner() }
 131     }
 132 }
 133
 134 ////////////////////////////////////////////////////////////////////////////////
 135 // OsString and OsStr
 136 ////////////////////////////////////////////////////////////////////////////////
 137
 138 /// Unix-specific extension to the primitives in the `std::ffi` module
 139 #[stable(feature = "rust1", since = "1.0.0")]
 140 pub mod ffi {
 141     use ffi::{OsStr, OsString};
 142     use mem;
 143     use prelude::v1::*;
 144     use sys::os_str::Buf;
 145     use sys_common::{FromInner, IntoInner, AsInner};
 146
 147     /// Unix-specific extensions to `OsString`.
 148     #[stable(feature = "rust1", since = "1.0.0")]
 149     pub trait OsStringExt {
 150         /// Create an `OsString` from a byte vector.
 151         #[stable(feature = "rust1", since = "1.0.0")]
 152         fn from_vec(vec: Vec<u8>) -> Self;
 153
 154         /// Yield the underlying byte vector of this `OsString`.
 155         #[stable(feature = "rust1", since = "1.0.0")]
 156         fn into_vec(self) -> Vec<u8>;
 157     }
 158
 159     #[stable(feature = "rust1", since = "1.0.0")]
 160     impl OsStringExt for OsString {
 161         fn from_vec(vec: Vec<u8>) -> OsString {
 162             FromInner::from_inner(Buf { inner: vec })
 163         }
 164         fn into_vec(self) -> Vec<u8> {
 165             self.into_inner().inner
 166         }
 167     }
 168
 169     /// Unix-specific extensions to `OsStr`.
 170     #[stable(feature = "rust1", since = "1.0.0")]
 171     pub trait OsStrExt {
 172         #[stable(feature = "rust1", since = "1.0.0")]
 173         fn from_bytes(slice: &[u8]) -> &Self;
 174
 175         /// Get the underlying byte view of the `OsStr` slice.
 176         #[stable(feature = "rust1", since = "1.0.0")]
 177         fn as_bytes(&self) -> &[u8];
 178     }
 179
 180     #[stable(feature = "rust1", since = "1.0.0")]
 181     impl OsStrExt for OsStr {
 182         fn from_bytes(slice: &[u8]) -> &OsStr {
 183             unsafe { mem::transmute(slice) }
 184         }
 185         fn as_bytes(&self) -> &[u8] {
 186             &self.as_inner().inner
 187         }
 188     }
 189 }
 190
 191 /// Unix-specific extensions to primitives in the `std::fs` module.
 192 #[unstable(feature = "fs_ext",
 193            reason = "may want a more useful mode abstraction")]
 194 pub mod fs {
 195     use sys_common::{FromInner, AsInner, AsInnerMut};
 196     use fs::{Permissions, OpenOptions};
 197
 198     /// Unix-specific extensions to `Permissions`
 199     pub trait PermissionsExt {
 200         fn mode(&self) -> i32;
 201         fn set_mode(&mut self, mode: i32);
 202     }
 203
 204     impl PermissionsExt for Permissions {
 205         fn mode(&self) -> i32 { self.as_inner().mode() }
 206
 207         fn set_mode(&mut self, mode: i32) {
 208             *self = FromInner::from_inner(FromInner::from_inner(mode));
 209         }
 210     }
 211
 212     /// Unix-specific extensions to `OpenOptions`
 213     pub trait OpenOptionsExt {
 214         /// Set the mode bits that a new file will be created with.
 215         ///
 216         /// If a new file is created as part of a `File::open_opts` call then this
 217         /// specified `mode` will be used as the permission bits for the new file.
 218         fn mode(&mut self, mode: i32) -> &mut Self;
 219     }
 220
 221     impl OpenOptionsExt for OpenOptions {
 222         fn mode(&mut self, mode: i32) -> &mut OpenOptions {
 223             self.as_inner_mut().mode(mode); self
 224         }
 225     }
 226 }
 227
 228 ////////////////////////////////////////////////////////////////////////////////
 229 // Process and Command
 230 ////////////////////////////////////////////////////////////////////////////////
 231
 232 /// Unix-specific extensions to primitives in the `std::process` module.
 233 #[stable(feature = "rust1", since = "1.0.0")]
 234 pub mod process {
 235     use prelude::v1::*;
 236     use libc::{uid_t, gid_t};
 237     use process;
 238     use sys;
 239     use sys_common::{AsInnerMut, AsInner};
 240
 241     /// Unix-specific extensions to the `std::process::Command` builder
 242     #[stable(feature = "rust1", since = "1.0.0")]
 243     pub trait CommandExt {
 244         /// Sets the child process's user id. This translates to a
 245         /// `setuid` call in the child process. Failure in the `setuid`
 246         /// call will cause the spawn to fail.
 247         #[stable(feature = "rust1", since = "1.0.0")]
 248         fn uid(&mut self, id: uid_t) -> &mut process::Command;
 249
 250         /// Similar to `uid`, but sets the group id of the child process. This has
 251         /// the same semantics as the `uid` field.
 252         #[stable(feature = "rust1", since = "1.0.0")]
 253         fn gid(&mut self, id: gid_t) -> &mut process::Command;
 254     }
 255
 256     #[stable(feature = "rust1", since = "1.0.0")]
 257     impl CommandExt for process::Command {
 258         fn uid(&mut self, id: uid_t) -> &mut process::Command {
 259             self.as_inner_mut().uid = Some(id);
 260             self
 261         }
 262
 263         fn gid(&mut self, id: gid_t) -> &mut process::Command {
 264             self.as_inner_mut().gid = Some(id);
 265             self
 266         }
 267     }
 268
 269     /// Unix-specific extensions to `std::process::ExitStatus`
 270     #[stable(feature = "rust1", since = "1.0.0")]
 271     pub trait ExitStatusExt {
 272         /// If the process was terminated by a signal, returns that signal.
 273         #[stable(feature = "rust1", since = "1.0.0")]
 274         fn signal(&self) -> Option<i32>;
 275     }
 276
 277     #[stable(feature = "rust1", since = "1.0.0")]
 278     impl ExitStatusExt for process::ExitStatus {
 279         fn signal(&self) -> Option<i32> {
 280             match *self.as_inner() {
 281                 sys::process2::ExitStatus::Signal(s) => Some(s),
 282                 _ => None
 283             }
 284         }
 285     }
 286 }
 287
 288 ////////////////////////////////////////////////////////////////////////////////
 289 // Prelude
 290 ////////////////////////////////////////////////////////////////////////////////
 291
 292 /// A prelude for conveniently writing platform-specific code.
 293 ///
 294 /// Includes all extension traits, and some important type definitions.
 295 #[stable(feature = "rust1", since = "1.0.0")]
 296 pub mod prelude {
 297     #[doc(no_inline)]
 298     pub use super::io::{Fd, AsRawFd};
 299     #[doc(no_inline)] #[stable(feature = "rust1", since = "1.0.0")]
 300     pub use super::ffi::{OsStrExt, OsStringExt};
 301     #[doc(no_inline)]
 302     pub use super::fs::{PermissionsExt, OpenOptionsExt};
 303     #[doc(no_inline)] #[stable(feature = "rust1", since = "1.0.0")]
 304     pub use super::process::{CommandExt, ExitStatusExt};
 305 }