src/libstd/sys/windows/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 //! Windows-specific extensions for the primitives in `std::fs`
  12
  13 #![stable(feature = "rust1", since = "1.0.0")]
  14
  15 use fs::{self, OpenOptions, Metadata};
  16 use io;
  17 use path::Path;
  18 use sys;
  19 use sys_common::{AsInnerMut, AsInner};
  20
  21 /// Windows-specific extensions to `File`
  22 #[stable(feature = "file_offset", since = "1.15.0")]
  23 pub trait FileExt {
  24     /// Seeks to a given position and reads a number of bytes.
  25     ///
  26     /// Returns the number of bytes read.
  27     ///
  28     /// The offset is relative to the start of the file and thus independent
  29     /// from the current cursor. The current cursor **is** affected by this
  30     /// function, it is set to the end of the read.
  31     ///
  32     /// Reading beyond the end of the file will always return with a length of
  33     /// 0.
  34     ///
  35     /// Note that similar to `File::read`, it is not an error to return with a
  36     /// short read. When returning from such a short read, the file pointer is
  37     /// still updated.
  38     #[stable(feature = "file_offset", since = "1.15.0")]
  39     fn seek_read(&self, buf: &mut [u8], offset: u64) -> io::Result<usize>;
  40
  41     /// Seeks to a given position and writes a number of bytes.
  42     ///
  43     /// Returns the number of bytes written.
  44     ///
  45     /// The offset is relative to the start of the file and thus independent
  46     /// from the current cursor. The current cursor **is** affected by this
  47     /// function, it is set to the end of the write.
  48     ///
  49     /// When writing beyond the end of the file, the file is appropiately
  50     /// extended and the intermediate bytes are left uninitialized.
  51     ///
  52     /// Note that similar to `File::write`, it is not an error to return a
  53     /// short write. When returning from such a short write, the file pointer
  54     /// is still updated.
  55     #[stable(feature = "file_offset", since = "1.15.0")]
  56     fn seek_write(&self, buf: &[u8], offset: u64) -> io::Result<usize>;
  57 }
  58
  59 #[stable(feature = "file_offset", since = "1.15.0")]
  60 impl FileExt for fs::File {
  61     fn seek_read(&self, buf: &mut [u8], offset: u64) -> io::Result<usize> {
  62         self.as_inner().read_at(buf, offset)
  63     }
  64
  65     fn seek_write(&self, buf: &[u8], offset: u64) -> io::Result<usize> {
  66         self.as_inner().write_at(buf, offset)
  67     }
  68 }
  69
  70 /// Windows-specific extensions to `OpenOptions`
  71 #[stable(feature = "open_options_ext", since = "1.10.0")]
  72 pub trait OpenOptionsExt {
  73     /// Overrides the `dwDesiredAccess` argument to the call to `CreateFile`
  74     /// with the specified value.
  75     ///
  76     /// This will override the `read`, `write`, and `append` flags on the
  77     /// `OpenOptions` structure. This method provides fine-grained control over
  78     /// the permissions to read, write and append data, attributes (like hidden
  79     /// and system) and extended attributes.
  80     ///
  81     /// # Examples
  82     ///
  83     /// ```no_run
  84     /// use std::fs::OpenOptions;
  85     /// use std::os::windows::fs::OpenOptionsExt;
  86     ///
  87     /// // Open without read and write permission, for example if you only need
  88     /// // to call `stat()` on the file
  89     /// let file = OpenOptions::new().access_mode(0).open("foo.txt");
  90     /// ```
  91     #[stable(feature = "open_options_ext", since = "1.10.0")]
  92     fn access_mode(&mut self, access: u32) -> &mut Self;
  93
  94     /// Overrides the `dwShareMode` argument to the call to `CreateFile` with
  95     /// the specified value.
  96     ///
  97     /// By default `share_mode` is set to
  98     /// `FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE`. Specifying
  99     /// less permissions denies others to read from, write to and/or delete the
 100     /// file while it is open.
 101     ///
 102     /// # Examples
 103     ///
 104     /// ```no_run
 105     /// use std::fs::OpenOptions;
 106     /// use std::os::windows::fs::OpenOptionsExt;
 107     ///
 108     /// // Do not allow others to read or modify this file while we have it open
 109     /// // for writing
 110     /// let file = OpenOptions::new().write(true)
 111     ///                              .share_mode(0)
 112     ///                              .open("foo.txt");
 113     /// ```
 114     #[stable(feature = "open_options_ext", since = "1.10.0")]
 115     fn share_mode(&mut self, val: u32) -> &mut Self;
 116
 117     /// Sets extra flags for the `dwFileFlags` argument to the call to
 118     /// `CreateFile2` (or combines it with `attributes` and `security_qos_flags`
 119     /// to set the `dwFlagsAndAttributes` for `CreateFile`).
 120     ///
 121     /// Custom flags can only set flags, not remove flags set by Rusts options.
 122     /// This options overwrites any previously set custom flags.
 123     ///
 124     /// # Examples
 125     ///
 126     /// ```rust,ignore
 127     /// extern crate winapi;
 128     /// use std::fs::OpenOptions;
 129     /// use std::os::windows::fs::OpenOptionsExt;
 130     ///
 131     /// let mut options = OpenOptions::new();
 132     /// options.create(true).write(true);
 133     /// if cfg!(windows) {
 134     ///     options.custom_flags(winapi::FILE_FLAG_DELETE_ON_CLOSE);
 135     /// }
 136     /// let file = options.open("foo.txt");
 137     /// ```
 138     #[stable(feature = "open_options_ext", since = "1.10.0")]
 139     fn custom_flags(&mut self, flags: u32) -> &mut Self;
 140
 141     /// Sets the `dwFileAttributes` argument to the call to `CreateFile2` to
 142     /// the specified value (or combines it with `custom_flags` and
 143     /// `security_qos_flags` to set the `dwFlagsAndAttributes` for
 144     /// `CreateFile`).
 145     ///
 146     /// If a _new_ file is created because it does not yet exist and
 147     /// `.create(true)` or `.create_new(true)` are specified, the new file is
 148     /// given the attributes declared with `.attributes()`.
 149     ///
 150     /// If an _existing_ file is opened with `.create(true).truncate(true)`, its
 151     /// existing attributes are preserved and combined with the ones declared
 152     /// with `.attributes()`.
 153     ///
 154     /// In all other cases the attributes get ignored.
 155     ///
 156     /// # Examples
 157     ///
 158     /// ```rust,ignore
 159     /// extern crate winapi;
 160     /// use std::fs::OpenOptions;
 161     /// use std::os::windows::fs::OpenOptionsExt;
 162     ///
 163     /// let file = OpenOptions::new().write(true).create(true)
 164     ///                              .attributes(winapi::FILE_ATTRIBUTE_HIDDEN)
 165     ///                              .open("foo.txt");
 166     /// ```
 167     #[stable(feature = "open_options_ext", since = "1.10.0")]
 168     fn attributes(&mut self, val: u32) -> &mut Self;
 169
 170     /// Sets the `dwSecurityQosFlags` argument to the call to `CreateFile2` to
 171     /// the specified value (or combines it with `custom_flags` and `attributes`
 172     /// to set the `dwFlagsAndAttributes` for `CreateFile`).
 173     #[stable(feature = "open_options_ext", since = "1.10.0")]
 174     fn security_qos_flags(&mut self, flags: u32) -> &mut OpenOptions;
 175 }
 176
 177 #[stable(feature = "open_options_ext", since = "1.10.0")]
 178 impl OpenOptionsExt for OpenOptions {
 179     fn access_mode(&mut self, access: u32) -> &mut OpenOptions {
 180         self.as_inner_mut().access_mode(access); self
 181     }
 182
 183     fn share_mode(&mut self, share: u32) -> &mut OpenOptions {
 184         self.as_inner_mut().share_mode(share); self
 185     }
 186
 187     fn custom_flags(&mut self, flags: u32) -> &mut OpenOptions {
 188         self.as_inner_mut().custom_flags(flags); self
 189     }
 190
 191     fn attributes(&mut self, attributes: u32) -> &mut OpenOptions {
 192         self.as_inner_mut().attributes(attributes); self
 193     }
 194
 195     fn security_qos_flags(&mut self, flags: u32) -> &mut OpenOptions {
 196         self.as_inner_mut().security_qos_flags(flags); self
 197     }
 198 }
 199
 200 /// Extension methods for `fs::Metadata` to access the raw fields contained
 201 /// within.
 202 #[stable(feature = "metadata_ext", since = "1.1.0")]
 203 pub trait MetadataExt {
 204     /// Returns the value of the `dwFileAttributes` field of this metadata.
 205     ///
 206     /// This field contains the file system attribute information for a file
 207     /// or directory.
 208     #[stable(feature = "metadata_ext", since = "1.1.0")]
 209     fn file_attributes(&self) -> u32;
 210
 211     /// Returns the value of the `ftCreationTime` field of this metadata.
 212     ///
 213     /// The returned 64-bit value represents the number of 100-nanosecond
 214     /// intervals since January 1, 1601 (UTC).
 215     #[stable(feature = "metadata_ext", since = "1.1.0")]
 216     fn creation_time(&self) -> u64;
 217
 218     /// Returns the value of the `ftLastAccessTime` field of this metadata.
 219     ///
 220     /// The returned 64-bit value represents the number of 100-nanosecond
 221     /// intervals since January 1, 1601 (UTC).
 222     #[stable(feature = "metadata_ext", since = "1.1.0")]
 223     fn last_access_time(&self) -> u64;
 224
 225     /// Returns the value of the `ftLastWriteTime` field of this metadata.
 226     ///
 227     /// The returned 64-bit value represents the number of 100-nanosecond
 228     /// intervals since January 1, 1601 (UTC).
 229     #[stable(feature = "metadata_ext", since = "1.1.0")]
 230     fn last_write_time(&self) -> u64;
 231
 232     /// Returns the value of the `nFileSize{High,Low}` fields of this
 233     /// metadata.
 234     ///
 235     /// The returned value does not have meaning for directories.
 236     #[stable(feature = "metadata_ext", since = "1.1.0")]
 237     fn file_size(&self) -> u64;
 238 }
 239
 240 #[stable(feature = "metadata_ext", since = "1.1.0")]
 241 impl MetadataExt for Metadata {
 242     fn file_attributes(&self) -> u32 { self.as_inner().attrs() }
 243     fn creation_time(&self) -> u64 { self.as_inner().created_u64() }
 244     fn last_access_time(&self) -> u64 { self.as_inner().accessed_u64() }
 245     fn last_write_time(&self) -> u64 { self.as_inner().modified_u64() }
 246     fn file_size(&self) -> u64 { self.as_inner().size() }
 247 }
 248
 249 /// Creates a new file symbolic link on the filesystem.
 250 ///
 251 /// The `dst` path will be a file symbolic link pointing to the `src`
 252 /// path.
 253 ///
 254 /// # Examples
 255 ///
 256 /// ```ignore
 257 /// use std::os::windows::fs;
 258 ///
 259 /// # fn foo() -> std::io::Result<()> {
 260 /// fs::symlink_file("a.txt", "b.txt")?;
 261 /// # Ok(())
 262 /// # }
 263 /// ```
 264 #[stable(feature = "symlink", since = "1.1.0")]
 265 pub fn symlink_file<P: AsRef<Path>, Q: AsRef<Path>>(src: P, dst: Q)
 266                                                     -> io::Result<()> {
 267     sys::fs::symlink_inner(src.as_ref(), dst.as_ref(), false)
 268 }
 269
 270 /// Creates a new directory symlink on the filesystem.
 271 ///
 272 /// The `dst` path will be a directory symbolic link pointing to the `src`
 273 /// path.
 274 ///
 275 /// # Examples
 276 ///
 277 /// ```ignore
 278 /// use std::os::windows::fs;
 279 ///
 280 /// # fn foo() -> std::io::Result<()> {
 281 /// fs::symlink_file("a", "b")?;
 282 /// # Ok(())
 283 /// # }
 284 /// ```
 285 #[stable(feature = "symlink", since = "1.1.0")]
 286 pub fn symlink_dir<P: AsRef<Path>, Q: AsRef<Path>>(src: P, dst: Q)
 287                                                    -> io::Result<()> {
 288     sys::fs::symlink_inner(src.as_ref(), dst.as_ref(), true)
 289 }