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::{CString, NulError, 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         /// Convert the `OsStr` slice into a `CString`.
 180         #[stable(feature = "rust1", since = "1.0.0")]
 181         fn to_cstring(&self) -> Result<CString, NulError>;
 182     }
 183
 184     #[stable(feature = "rust1", since = "1.0.0")]
 185     impl OsStrExt for OsStr {
 186         fn from_bytes(slice: &[u8]) -> &OsStr {
 187             unsafe { mem::transmute(slice) }
 188         }
 189         fn as_bytes(&self) -> &[u8] {
 190             &self.as_inner().inner
 191         }
 192         fn to_cstring(&self) -> Result<CString, NulError> {
 193             CString::new(self.as_bytes())
 194         }
 195     }
 196 }
 197
 198 /// Unix-specific extensions to primitives in the `std::fs` module.
 199 #[unstable(feature = "fs_ext",
 200            reason = "may want a more useful mode abstraction")]
 201 pub mod fs {
 202     use sys_common::{FromInner, AsInner, AsInnerMut};
 203     use fs::{Permissions, OpenOptions};
 204
 205     /// Unix-specific extensions to `Permissions`
 206     pub trait PermissionsExt {
 207         fn mode(&self) -> i32;
 208         fn set_mode(&mut self, mode: i32);
 209     }
 210
 211     impl PermissionsExt for Permissions {
 212         fn mode(&self) -> i32 { self.as_inner().mode() }
 213
 214         fn set_mode(&mut self, mode: i32) {
 215             *self = FromInner::from_inner(FromInner::from_inner(mode));
 216         }
 217     }
 218
 219     /// Unix-specific extensions to `OpenOptions`
 220     pub trait OpenOptionsExt {
 221         /// Set the mode bits that a new file will be created with.
 222         ///
 223         /// If a new file is created as part of a `File::open_opts` call then this
 224         /// specified `mode` will be used as the permission bits for the new file.
 225         fn mode(&mut self, mode: i32) -> &mut Self;
 226     }
 227
 228     impl OpenOptionsExt for OpenOptions {
 229         fn mode(&mut self, mode: i32) -> &mut OpenOptions {
 230             self.as_inner_mut().mode(mode); self
 231         }
 232     }
 233 }
 234
 235 ////////////////////////////////////////////////////////////////////////////////
 236 // Process and Command
 237 ////////////////////////////////////////////////////////////////////////////////
 238
 239 /// Unix-specific extensions to primitives in the `std::process` module.
 240 #[stable(feature = "rust1", since = "1.0.0")]
 241 pub mod process {
 242     use prelude::v1::*;
 243     use libc::{uid_t, gid_t};
 244     use process;
 245     use sys;
 246     use sys_common::{AsInnerMut, AsInner};
 247
 248     /// Unix-specific extensions to the `std::process::Command` builder
 249     #[stable(feature = "rust1", since = "1.0.0")]
 250     pub trait CommandExt {
 251         /// Sets the child process's user id. This translates to a
 252         /// `setuid` call in the child process. Failure in the `setuid`
 253         /// call will cause the spawn to fail.
 254         #[stable(feature = "rust1", since = "1.0.0")]
 255         fn uid(&mut self, id: uid_t) -> &mut process::Command;
 256
 257         /// Similar to `uid`, but sets the group id of the child process. This has
 258         /// the same semantics as the `uid` field.
 259         #[stable(feature = "rust1", since = "1.0.0")]
 260         fn gid(&mut self, id: gid_t) -> &mut process::Command;
 261     }
 262
 263     #[stable(feature = "rust1", since = "1.0.0")]
 264     impl CommandExt for process::Command {
 265         fn uid(&mut self, id: uid_t) -> &mut process::Command {
 266             self.as_inner_mut().uid = Some(id);
 267             self
 268         }
 269
 270         fn gid(&mut self, id: gid_t) -> &mut process::Command {
 271             self.as_inner_mut().gid = Some(id);
 272             self
 273         }
 274     }
 275
 276     /// Unix-specific extensions to `std::process::ExitStatus`
 277     #[stable(feature = "rust1", since = "1.0.0")]
 278     pub trait ExitStatusExt {
 279         /// If the process was terminated by a signal, returns that signal.
 280         #[stable(feature = "rust1", since = "1.0.0")]
 281         fn signal(&self) -> Option<i32>;
 282     }
 283
 284     #[stable(feature = "rust1", since = "1.0.0")]
 285     impl ExitStatusExt for process::ExitStatus {
 286         fn signal(&self) -> Option<i32> {
 287             match *self.as_inner() {
 288                 sys::process2::ExitStatus::Signal(s) => Some(s),
 289                 _ => None
 290             }
 291         }
 292     }
 293 }
 294
 295 ////////////////////////////////////////////////////////////////////////////////
 296 // Prelude
 297 ////////////////////////////////////////////////////////////////////////////////
 298
 299 /// A prelude for conveniently writing platform-specific code.
 300 ///
 301 /// Includes all extension traits, and some important type definitions.
 302 #[stable(feature = "rust1", since = "1.0.0")]
 303 pub mod prelude {
 304     #[doc(no_inline)]
 305     pub use super::io::{Fd, AsRawFd};
 306     #[doc(no_inline)] #[stable(feature = "rust1", since = "1.0.0")]
 307     pub use super::ffi::{OsStrExt, OsStringExt};
 308     #[doc(no_inline)]
 309     pub use super::fs::{PermissionsExt, OpenOptionsExt};
 310     #[doc(no_inline)] #[stable(feature = "rust1", since = "1.0.0")]
 311     pub use super::process::{CommandExt, ExitStatusExt};
 312 }