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