src/libstd/sys/unix/ext/fs.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::fs` module.
  12
  13 #![stable(feature = "rust1", since = "1.0.0")]
  14
  15 use fs::{self, Permissions, OpenOptions};
  16 use io;
  17 use libc;
  18 use os::raw::c_long;
  19 use os::unix::raw;
  20 use path::Path;
  21 use sys::fs::MetadataExt as UnixMetadataExt;
  22 use sys;
  23 use sys_common::{FromInner, AsInner, AsInnerMut};
  24
  25 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
  26 pub const USER_READ: raw::mode_t = 0o400;
  27 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
  28 pub const USER_WRITE: raw::mode_t = 0o200;
  29 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
  30 pub const USER_EXECUTE: raw::mode_t = 0o100;
  31 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
  32 pub const USER_RWX: raw::mode_t = 0o700;
  33 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
  34 pub const GROUP_READ: raw::mode_t = 0o040;
  35 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
  36 pub const GROUP_WRITE: raw::mode_t = 0o020;
  37 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
  38 pub const GROUP_EXECUTE: raw::mode_t = 0o010;
  39 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
  40 pub const GROUP_RWX: raw::mode_t = 0o070;
  41 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
  42 pub const OTHER_READ: raw::mode_t = 0o004;
  43 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
  44 pub const OTHER_WRITE: raw::mode_t = 0o002;
  45 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
  46 pub const OTHER_EXECUTE: raw::mode_t = 0o001;
  47 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
  48 pub const OTHER_RWX: raw::mode_t = 0o007;
  49 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
  50 pub const ALL_READ: raw::mode_t = 0o444;
  51 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
  52 pub const ALL_WRITE: raw::mode_t = 0o222;
  53 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
  54 pub const ALL_EXECUTE: raw::mode_t = 0o111;
  55 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
  56 pub const ALL_RWX: raw::mode_t = 0o777;
  57 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
  58 pub const SETUID: raw::mode_t = 0o4000;
  59 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
  60 pub const SETGID: raw::mode_t = 0o2000;
  61 #[unstable(feature = "fs_mode", reason = "recently added API", issue = "27712")]
  62 pub const STICKY_BIT: raw::mode_t = 0o1000;
  63
  64 /// Unix-specific extensions to `Permissions`
  65 #[stable(feature = "fs_ext", since = "1.1.0")]
  66 pub trait PermissionsExt {
  67     /// Returns the underlying raw `mode_t` bits that are the standard Unix
  68     /// permissions for this file.
  69     #[stable(feature = "fs_ext", since = "1.1.0")]
  70     fn mode(&self) -> raw::mode_t;
  71
  72     /// Sets the underlying raw `mode_t` bits for this set of permissions.
  73     #[stable(feature = "fs_ext", since = "1.1.0")]
  74     fn set_mode(&mut self, mode: raw::mode_t);
  75
  76     /// Creates a new instance of `Permissions` from the given set of Unix
  77     /// permission bits.
  78     #[stable(feature = "fs_ext", since = "1.1.0")]
  79     fn from_mode(mode: raw::mode_t) -> Self;
  80 }
  81
  82 #[stable(feature = "fs_ext", since = "1.1.0")]
  83 impl PermissionsExt for Permissions {
  84     fn mode(&self) -> raw::mode_t { self.as_inner().mode() }
  85
  86     fn set_mode(&mut self, mode: raw::mode_t) {
  87         *self = FromInner::from_inner(FromInner::from_inner(mode));
  88     }
  89
  90     fn from_mode(mode: raw::mode_t) -> Permissions {
  91         FromInner::from_inner(FromInner::from_inner(mode))
  92     }
  93 }
  94
  95 /// Unix-specific extensions to `OpenOptions`
  96 #[stable(feature = "fs_ext", since = "1.1.0")]
  97 pub trait OpenOptionsExt {
  98     /// Sets the mode bits that a new file will be created with.
  99     ///
 100     /// If a new file is created as part of a `File::open_opts` call then this
 101     /// specified `mode` will be used as the permission bits for the new file.
 102     /// If no `mode` is set, the default of `0o666` will be used.
 103     /// The operating system masks out bits with the systems `umask`, to produce
 104     /// the final permissions.
 105     #[stable(feature = "fs_ext", since = "1.1.0")]
 106     fn mode(&mut self, mode: raw::mode_t) -> &mut Self;
 107 }
 108
 109 #[stable(feature = "fs_ext", since = "1.1.0")]
 110 impl OpenOptionsExt for OpenOptions {
 111     fn mode(&mut self, mode: raw::mode_t) -> &mut OpenOptions {
 112         self.as_inner_mut().mode(mode); self
 113     }
 114 }
 115
 116 // Hm, why are there casts here to the returned type, shouldn't the types always
 117 // be the same? Right you are! Turns out, however, on android at least the types
 118 // in the raw `stat` structure are not the same as the types being returned. Who
 119 // knew!
 120 //
 121 // As a result to make sure this compiles for all platforms we do the manual
 122 // casts and rely on manual lowering to `stat` if the raw type is desired.
 123 #[stable(feature = "metadata_ext", since = "1.1.0")]
 124 pub trait MetadataExt {
 125     #[stable(feature = "metadata_ext", since = "1.1.0")]
 126     fn dev(&self) -> raw::dev_t;
 127     #[stable(feature = "metadata_ext", since = "1.1.0")]
 128     fn ino(&self) -> raw::ino_t;
 129     #[stable(feature = "metadata_ext", since = "1.1.0")]
 130     fn mode(&self) -> raw::mode_t;
 131     #[stable(feature = "metadata_ext", since = "1.1.0")]
 132     fn nlink(&self) -> raw::nlink_t;
 133     #[stable(feature = "metadata_ext", since = "1.1.0")]
 134     fn uid(&self) -> raw::uid_t;
 135     #[stable(feature = "metadata_ext", since = "1.1.0")]
 136     fn gid(&self) -> raw::gid_t;
 137     #[stable(feature = "metadata_ext", since = "1.1.0")]
 138     fn rdev(&self) -> raw::dev_t;
 139     #[stable(feature = "metadata_ext", since = "1.1.0")]
 140     fn size(&self) -> raw::off_t;
 141     #[stable(feature = "metadata_ext", since = "1.1.0")]
 142     fn atime(&self) -> raw::time_t;
 143     #[stable(feature = "metadata_ext", since = "1.1.0")]
 144     fn atime_nsec(&self) -> c_long;
 145     #[stable(feature = "metadata_ext", since = "1.1.0")]
 146     fn mtime(&self) -> raw::time_t;
 147     #[stable(feature = "metadata_ext", since = "1.1.0")]
 148     fn mtime_nsec(&self) -> c_long;
 149     #[stable(feature = "metadata_ext", since = "1.1.0")]
 150     fn ctime(&self) -> raw::time_t;
 151     #[stable(feature = "metadata_ext", since = "1.1.0")]
 152     fn ctime_nsec(&self) -> c_long;
 153     #[stable(feature = "metadata_ext", since = "1.1.0")]
 154     fn blksize(&self) -> raw::blksize_t;
 155     #[stable(feature = "metadata_ext", since = "1.1.0")]
 156     fn blocks(&self) -> raw::blkcnt_t;
 157 }
 158
 159 #[stable(feature = "metadata_ext", since = "1.1.0")]
 160 impl MetadataExt for fs::Metadata {
 161     fn dev(&self) -> raw::dev_t { self.as_raw_stat().st_dev as raw::dev_t }
 162     fn ino(&self) -> raw::ino_t { self.as_raw_stat().st_ino as raw::ino_t }
 163     fn mode(&self) -> raw::mode_t { self.as_raw_stat().st_mode as raw::mode_t }
 164     fn nlink(&self) -> raw::nlink_t { self.as_raw_stat().st_nlink as raw::nlink_t }
 165     fn uid(&self) -> raw::uid_t { self.as_raw_stat().st_uid as raw::uid_t }
 166     fn gid(&self) -> raw::gid_t { self.as_raw_stat().st_gid as raw::gid_t }
 167     fn rdev(&self) -> raw::dev_t { self.as_raw_stat().st_rdev as raw::dev_t }
 168     fn size(&self) -> raw::off_t { self.as_raw_stat().st_size as raw::off_t }
 169     fn atime(&self) -> raw::time_t { self.as_raw_stat().st_atime }
 170     fn atime_nsec(&self) -> c_long { self.as_raw_stat().st_atime_nsec as c_long }
 171     fn mtime(&self) -> raw::time_t { self.as_raw_stat().st_mtime }
 172     fn mtime_nsec(&self) -> c_long { self.as_raw_stat().st_mtime_nsec as c_long }
 173     fn ctime(&self) -> raw::time_t { self.as_raw_stat().st_ctime }
 174     fn ctime_nsec(&self) -> c_long { self.as_raw_stat().st_ctime_nsec as c_long }
 175
 176     fn blksize(&self) -> raw::blksize_t {
 177         self.as_raw_stat().st_blksize as raw::blksize_t
 178     }
 179     fn blocks(&self) -> raw::blkcnt_t {
 180         self.as_raw_stat().st_blocks as raw::blkcnt_t
 181     }
 182 }
 183
 184 /// Add special unix types (block/char device, fifo and socket)
 185 #[stable(feature = "file_type_ext", since = "1.5.0")]
 186 pub trait FileTypeExt {
 187     /// Returns whether this file type is a block device.
 188     #[stable(feature = "file_type_ext", since = "1.5.0")]
 189     fn is_block_device(&self) -> bool;
 190     /// Returns whether this file type is a char device.
 191     #[stable(feature = "file_type_ext", since = "1.5.0")]
 192     fn is_char_device(&self) -> bool;
 193     /// Returns whether this file type is a fifo.
 194     #[stable(feature = "file_type_ext", since = "1.5.0")]
 195     fn is_fifo(&self) -> bool;
 196     /// Returns whether this file type is a socket.
 197     #[stable(feature = "file_type_ext", since = "1.5.0")]
 198     fn is_socket(&self) -> bool;
 199 }
 200
 201 #[stable(feature = "file_type_ext", since = "1.5.0")]
 202 impl FileTypeExt for fs::FileType {
 203     fn is_block_device(&self) -> bool { self.as_inner().is(libc::S_IFBLK) }
 204     fn is_char_device(&self) -> bool { self.as_inner().is(libc::S_IFCHR) }
 205     fn is_fifo(&self) -> bool { self.as_inner().is(libc::S_IFIFO) }
 206     fn is_socket(&self) -> bool { self.as_inner().is(libc::S_IFSOCK) }
 207 }
 208
 209 /// Unix-specific extension methods for `fs::DirEntry`
 210 #[stable(feature = "dir_entry_ext", since = "1.1.0")]
 211 pub trait DirEntryExt {
 212     /// Returns the underlying `d_ino` field in the contained `dirent`
 213     /// structure.
 214     #[stable(feature = "dir_entry_ext", since = "1.1.0")]
 215     fn ino(&self) -> raw::ino_t;
 216 }
 217
 218 #[stable(feature = "dir_entry_ext", since = "1.1.0")]
 219 impl DirEntryExt for fs::DirEntry {
 220     fn ino(&self) -> raw::ino_t { self.as_inner().ino() }
 221 }
 222
 223 /// Creates a new symbolic link on the filesystem.
 224 ///
 225 /// The `dst` path will be a symbolic link pointing to the `src` path.
 226 ///
 227 /// # Note
 228 ///
 229 /// On Windows, you must specify whether a symbolic link points to a file
 230 /// or directory.  Use `os::windows::fs::symlink_file` to create a
 231 /// symbolic link to a file, or `os::windows::fs::symlink_dir` to create a
 232 /// symbolic link to a directory.  Additionally, the process must have
 233 /// `SeCreateSymbolicLinkPrivilege` in order to be able to create a
 234 /// symbolic link.
 235 ///
 236 /// # Examples
 237 ///
 238 /// ```
 239 /// use std::os::unix::fs;
 240 ///
 241 /// # fn foo() -> std::io::Result<()> {
 242 /// try!(fs::symlink("a.txt", "b.txt"));
 243 /// # Ok(())
 244 /// # }
 245 /// ```
 246 #[stable(feature = "symlink", since = "1.1.0")]
 247 pub fn symlink<P: AsRef<Path>, Q: AsRef<Path>>(src: P, dst: Q) -> io::Result<()>
 248 {
 249     sys::fs::symlink(src.as_ref(), dst.as_ref())
 250 }
 251
 252 #[stable(feature = "dir_builder", since = "1.6.0")]
 253 /// An extension trait for `fs::DirBuilder` for unix-specific options.
 254 pub trait DirBuilderExt {
 255     /// Sets the mode to create new directories with. This option defaults to
 256     /// 0o777.
 257     #[stable(feature = "dir_builder", since = "1.6.0")]
 258     fn mode(&mut self, mode: raw::mode_t) -> &mut Self;
 259 }
 260
 261 #[stable(feature = "dir_builder", since = "1.6.0")]
 262 impl DirBuilderExt for fs::DirBuilder {
 263     fn mode(&mut self, mode: raw::mode_t) -> &mut fs::DirBuilder {
 264         self.as_inner_mut().set_mode(mode);
 265         self
 266     }
 267 }
 268