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