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