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 the `std::fs` module.
  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 ///
  23 /// [`File`]: ../../../fs/struct.File.html
  24 #[stable(feature = "file_offset", since = "1.15.0")]
  25 pub trait FileExt {
  26     /// Seeks to a given position and reads a number of bytes.
  27     ///
  28     /// Returns the number of bytes read.
  29     ///
  30     /// The offset is relative to the start of the file and thus independent
  31     /// from the current cursor. The current cursor **is** affected by this
  32     /// function, it is set to the end of the read.
  33     ///
  34     /// Reading beyond the end of the file will always return with a length of
  35     /// 0.
  36     ///
  37     /// Note that similar to `File::read`, it is not an error to return with a
  38     /// short read. When returning from such a short read, the file pointer is
  39     /// still updated.
  40     ///
  41     /// # Examples
  42     ///
  43     /// ```no_run
  44     /// use std::io;
  45     /// use std::fs::File;
  46     /// use std::os::windows::prelude::*;
  47     ///
  48     /// # fn foo() -> io::Result<()> {
  49     /// let mut file = File::open("foo.txt")?;
  50     /// let mut buffer = [0; 10];
  51     ///
  52     /// // Read 10 bytes, starting 72 bytes from the
  53     /// // start of the file.
  54     /// file.seek_read(&mut buffer[..], 72)?;
  55     /// # Ok(())
  56     /// # }
  57     /// ```
  58     #[stable(feature = "file_offset", since = "1.15.0")]
  59     fn seek_read(&self, buf: &mut [u8], offset: u64) -> io::Result<usize>;
  60
  61     /// Seeks to a given position and writes a number of bytes.
  62     ///
  63     /// Returns the number of bytes written.
  64     ///
  65     /// The offset is relative to the start of the file and thus independent
  66     /// from the current cursor. The current cursor **is** affected by this
  67     /// function, it is set to the end of the write.
  68     ///
  69     /// When writing beyond the end of the file, the file is appropriately
  70     /// extended and the intermediate bytes are left uninitialized.
  71     ///
  72     /// Note that similar to `File::write`, it is not an error to return a
  73     /// short write. When returning from such a short write, the file pointer
  74     /// is still updated.
  75     ///
  76     /// # Examples
  77     ///
  78     /// ```no_run
  79     /// use std::fs::File;
  80     /// use std::os::windows::prelude::*;
  81     ///
  82     /// # fn foo() -> std::io::Result<()> {
  83     /// let mut buffer = File::create("foo.txt")?;
  84     ///
  85     /// // Write a byte string starting 72 bytes from
  86     /// // the start of the file.
  87     /// buffer.seek_write(b"some bytes", 72)?;
  88     /// # Ok(())
  89     /// # }
  90     /// ```
  91     #[stable(feature = "file_offset", since = "1.15.0")]
  92     fn seek_write(&self, buf: &[u8], offset: u64) -> io::Result<usize>;
  93 }
  94
  95 #[stable(feature = "file_offset", since = "1.15.0")]
  96 impl FileExt for fs::File {
  97     fn seek_read(&self, buf: &mut [u8], offset: u64) -> io::Result<usize> {
  98         self.as_inner().read_at(buf, offset)
  99     }
 100
 101     fn seek_write(&self, buf: &[u8], offset: u64) -> io::Result<usize> {
 102         self.as_inner().write_at(buf, offset)
 103     }
 104 }
 105
 106 /// Windows-specific extensions to [`OpenOptions`].
 107 ///
 108 /// [`OpenOptions`]: ../../../fs/struct.OpenOptions.html
 109 #[stable(feature = "open_options_ext", since = "1.10.0")]
 110 pub trait OpenOptionsExt {
 111     /// Overrides the `dwDesiredAccess` argument to the call to [`CreateFile`]
 112     /// with the specified value.
 113     ///
 114     /// This will override the `read`, `write`, and `append` flags on the
 115     /// `OpenOptions` structure. This method provides fine-grained control over
 116     /// the permissions to read, write and append data, attributes (like hidden
 117     /// and system), and extended attributes.
 118     ///
 119     /// # Examples
 120     ///
 121     /// ```no_run
 122     /// use std::fs::OpenOptions;
 123     /// use std::os::windows::prelude::*;
 124     ///
 125     /// // Open without read and write permission, for example if you only need
 126     /// // to call `stat` on the file
 127     /// let file = OpenOptions::new().access_mode(0).open("foo.txt");
 128     /// ```
 129     ///
 130     /// [`CreateFile`]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa363858.aspx
 131     #[stable(feature = "open_options_ext", since = "1.10.0")]
 132     fn access_mode(&mut self, access: u32) -> &mut Self;
 133
 134     /// Overrides the `dwShareMode` argument to the call to [`CreateFile`] with
 135     /// the specified value.
 136     ///
 137     /// By default `share_mode` is set to
 138     /// `FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE`. This allows
 139     /// other processes to to read, write, and delete/rename the same file
 140     /// while it is open. Removing any of the flags will prevent other
 141     /// processes from performing the corresponding operation until the file
 142     /// handle is closed.
 143     ///
 144     /// # Examples
 145     ///
 146     /// ```no_run
 147     /// use std::fs::OpenOptions;
 148     /// use std::os::windows::prelude::*;
 149     ///
 150     /// // Do not allow others to read or modify this file while we have it open
 151     /// // for writing.
 152     /// let file = OpenOptions::new()
 153     ///     .write(true)
 154     ///     .share_mode(0)
 155     ///     .open("foo.txt");
 156     /// ```
 157     ///
 158     /// [`CreateFile`]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa363858.aspx
 159     #[stable(feature = "open_options_ext", since = "1.10.0")]
 160     fn share_mode(&mut self, val: u32) -> &mut Self;
 161
 162     /// Sets extra flags for the `dwFileFlags` argument to the call to
 163     /// [`CreateFile2`] to the specified value (or combines it with
 164     /// `attributes` and `security_qos_flags` to set the `dwFlagsAndAttributes`
 165     /// for [`CreateFile`]).
 166     ///
 167     /// Custom flags can only set flags, not remove flags set by Rust's options.
 168     /// This option overwrites any previously set custom flags.
 169     ///
 170     /// # Examples
 171     ///
 172     /// ```no_run
 173     /// # #[cfg(for_demonstration_only)]
 174     /// extern crate winapi;
 175     /// # mod winapi { pub const FILE_FLAG_DELETE_ON_CLOSE: u32 = 0x04000000; }
 176     ///
 177     /// use std::fs::OpenOptions;
 178     /// use std::os::windows::prelude::*;
 179     ///
 180     /// let file = OpenOptions::new()
 181     ///     .create(true)
 182     ///     .write(true)
 183     ///     .custom_flags(winapi::FILE_FLAG_DELETE_ON_CLOSE)
 184     ///     .open("foo.txt");
 185     /// ```
 186     ///
 187     /// [`CreateFile`]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa363858.aspx
 188     /// [`CreateFile2`]: https://msdn.microsoft.com/en-us/library/windows/desktop/hh449422.aspx
 189     #[stable(feature = "open_options_ext", since = "1.10.0")]
 190     fn custom_flags(&mut self, flags: u32) -> &mut Self;
 191
 192     /// Sets the `dwFileAttributes` argument to the call to [`CreateFile2`] to
 193     /// the specified value (or combines it with `custom_flags` and
 194     /// `security_qos_flags` to set the `dwFlagsAndAttributes` for
 195     /// [`CreateFile`]).
 196     ///
 197     /// If a _new_ file is created because it does not yet exist and
 198     /// `.create(true)` or `.create_new(true)` are specified, the new file is
 199     /// given the attributes declared with `.attributes()`.
 200     ///
 201     /// If an _existing_ file is opened with `.create(true).truncate(true)`, its
 202     /// existing attributes are preserved and combined with the ones declared
 203     /// with `.attributes()`.
 204     ///
 205     /// In all other cases the attributes get ignored.
 206     ///
 207     /// # Examples
 208     ///
 209     /// ```no_run
 210     /// # #[cfg(for_demonstration_only)]
 211     /// extern crate winapi;
 212     /// # mod winapi { pub const FILE_ATTRIBUTE_HIDDEN: u32 = 2; }
 213     ///
 214     /// use std::fs::OpenOptions;
 215     /// use std::os::windows::prelude::*;
 216     ///
 217     /// let file = OpenOptions::new()
 218     ///     .write(true)
 219     ///     .create(true)
 220     ///     .attributes(winapi::FILE_ATTRIBUTE_HIDDEN)
 221     ///     .open("foo.txt");
 222     /// ```
 223     ///
 224     /// [`CreateFile`]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa363858.aspx
 225     /// [`CreateFile2`]: https://msdn.microsoft.com/en-us/library/windows/desktop/hh449422.aspx
 226     #[stable(feature = "open_options_ext", since = "1.10.0")]
 227     fn attributes(&mut self, val: u32) -> &mut Self;
 228
 229     /// Sets the `dwSecurityQosFlags` argument to the call to [`CreateFile2`] to
 230     /// the specified value (or combines it with `custom_flags` and `attributes`
 231     /// to set the `dwFlagsAndAttributes` for [`CreateFile`]).
 232     ///
 233     /// By default, `security_qos_flags` is set to `SECURITY_ANONYMOUS`. For
 234     /// information about possible values, see [Impersonation Levels] on the
 235     /// Windows Dev Center site.
 236     ///
 237     /// # Examples
 238     ///
 239     /// ```no_run
 240     /// use std::fs::OpenOptions;
 241     /// use std::os::windows::prelude::*;
 242     ///
 243     /// let file = OpenOptions::new()
 244     ///     .write(true)
 245     ///     .create(true)
 246     ///
 247     ///     // Sets the flag value to `SecurityIdentification`.
 248     ///     .security_qos_flags(1)
 249     ///
 250     ///     .open("foo.txt");
 251     /// ```
 252     ///
 253     /// [`CreateFile`]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa363858.aspx
 254     /// [`CreateFile2`]: https://msdn.microsoft.com/en-us/library/windows/desktop/hh449422.aspx
 255     /// [Impersonation Levels]:
 256     ///     https://msdn.microsoft.com/en-us/library/windows/desktop/aa379572.aspx
 257     #[stable(feature = "open_options_ext", since = "1.10.0")]
 258     fn security_qos_flags(&mut self, flags: u32) -> &mut OpenOptions;
 259 }
 260
 261 #[stable(feature = "open_options_ext", since = "1.10.0")]
 262 impl OpenOptionsExt for OpenOptions {
 263     fn access_mode(&mut self, access: u32) -> &mut OpenOptions {
 264         self.as_inner_mut().access_mode(access); self
 265     }
 266
 267     fn share_mode(&mut self, share: u32) -> &mut OpenOptions {
 268         self.as_inner_mut().share_mode(share); self
 269     }
 270
 271     fn custom_flags(&mut self, flags: u32) -> &mut OpenOptions {
 272         self.as_inner_mut().custom_flags(flags); self
 273     }
 274
 275     fn attributes(&mut self, attributes: u32) -> &mut OpenOptions {
 276         self.as_inner_mut().attributes(attributes); self
 277     }
 278
 279     fn security_qos_flags(&mut self, flags: u32) -> &mut OpenOptions {
 280         self.as_inner_mut().security_qos_flags(flags); self
 281     }
 282 }
 283
 284 /// Extension methods for [`fs::Metadata`] to access the raw fields contained
 285 /// within.
 286 ///
 287 /// The data members that this trait exposes correspond to the members
 288 /// of the [`BY_HANDLE_FILE_INFORMATION`] structure.
 289 ///
 290 /// [`fs::Metadata`]: ../../../fs/struct.Metadata.html
 291 /// [`BY_HANDLE_FILE_INFORMATION`]:
 292 ///     https://msdn.microsoft.com/en-us/library/windows/desktop/aa363788.aspx
 293 #[stable(feature = "metadata_ext", since = "1.1.0")]
 294 pub trait MetadataExt {
 295     /// Returns the value of the `dwFileAttributes` field of this metadata.
 296     ///
 297     /// This field contains the file system attribute information for a file
 298     /// or directory. For possible values and their descriptions, see
 299     /// [File Attribute Constants] in the Windows Dev Center.
 300     ///
 301     /// # Examples
 302     ///
 303     /// ```no_run
 304     /// use std::io;
 305     /// use std::fs;
 306     /// use std::os::windows::prelude::*;
 307     ///
 308     /// # fn foo() -> io::Result<()> {
 309     /// let metadata = fs::metadata("foo.txt")?;
 310     /// let attributes = metadata.file_attributes();
 311     /// # Ok(())
 312     /// # }
 313     /// ```
 314     ///
 315     /// [File Attribute Constants]:
 316     ///     https://msdn.microsoft.com/en-us/library/windows/desktop/gg258117.aspx
 317     #[stable(feature = "metadata_ext", since = "1.1.0")]
 318     fn file_attributes(&self) -> u32;
 319
 320     /// Returns the value of the `ftCreationTime` field of this metadata.
 321     ///
 322     /// The returned 64-bit value is equivalent to a [`FILETIME`] struct,
 323     /// which represents the number of 100-nanosecond intervals since
 324     /// January 1, 1601 (UTC). The struct is automatically
 325     /// converted to a `u64` value, as that is the recommended way
 326     /// to use it.
 327     ///
 328     /// If the underlying filesystem does not support creation time, the
 329     /// returned value is 0.
 330     ///
 331     /// # Examples
 332     ///
 333     /// ```no_run
 334     /// use std::io;
 335     /// use std::fs;
 336     /// use std::os::windows::prelude::*;
 337     ///
 338     /// # fn foo() -> io::Result<()> {
 339     /// let metadata = fs::metadata("foo.txt")?;
 340     /// let creation_time = metadata.creation_time();
 341     /// # Ok(())
 342     /// # }
 343     /// ```
 344     ///
 345     /// [`FILETIME`]: https://msdn.microsoft.com/en-us/library/windows/desktop/ms724284.aspx
 346     #[stable(feature = "metadata_ext", since = "1.1.0")]
 347     fn creation_time(&self) -> u64;
 348
 349     /// Returns the value of the `ftLastAccessTime` field of this metadata.
 350     ///
 351     /// The returned 64-bit value is equivalent to a [`FILETIME`] struct,
 352     /// which represents the number of 100-nanosecond intervals since
 353     /// January 1, 1601 (UTC). The struct is automatically
 354     /// converted to a `u64` value, as that is the recommended way
 355     /// to use it.
 356     ///
 357     /// For a file, the value specifies the last time that a file was read
 358     /// from or written to. For a directory, the value specifies when
 359     /// the directory was created. For both files and directories, the
 360     /// specified date is correct, but the time of day is always set to
 361     /// midnight.
 362     ///
 363     /// If the underlying filesystem does not support last access time, the
 364     /// returned value is 0.
 365     ///
 366     /// # Examples
 367     ///
 368     /// ```no_run
 369     /// use std::io;
 370     /// use std::fs;
 371     /// use std::os::windows::prelude::*;
 372     ///
 373     /// # fn foo() -> io::Result<()> {
 374     /// let metadata = fs::metadata("foo.txt")?;
 375     /// let last_access_time = metadata.last_access_time();
 376     /// # Ok(())
 377     /// # }
 378     /// ```
 379     ///
 380     /// [`FILETIME`]: https://msdn.microsoft.com/en-us/library/windows/desktop/ms724284.aspx
 381     #[stable(feature = "metadata_ext", since = "1.1.0")]
 382     fn last_access_time(&self) -> u64;
 383
 384     /// Returns the value of the `ftLastWriteTime` field of this metadata.
 385     ///
 386     /// The returned 64-bit value is equivalent to a [`FILETIME`] struct,
 387     /// which represents the number of 100-nanosecond intervals since
 388     /// January 1, 1601 (UTC). The struct is automatically
 389     /// converted to a `u64` value, as that is the recommended way
 390     /// to use it.
 391     ///
 392     /// For a file, the value specifies the last time that a file was written
 393     /// to. For a directory, the structure specifies when the directory was
 394     /// created.
 395     ///
 396     /// If the underlying filesystem does not support the last write time,
 397     /// the returned value is 0.
 398     ///
 399     /// # Examples
 400     ///
 401     /// ```no_run
 402     /// use std::io;
 403     /// use std::fs;
 404     /// use std::os::windows::prelude::*;
 405     ///
 406     /// # fn foo() -> io::Result<()> {
 407     /// let metadata = fs::metadata("foo.txt")?;
 408     /// let last_write_time = metadata.last_write_time();
 409     /// # Ok(())
 410     /// # }
 411     /// ```
 412     ///
 413     /// [`FILETIME`]: https://msdn.microsoft.com/en-us/library/windows/desktop/ms724284.aspx
 414     #[stable(feature = "metadata_ext", since = "1.1.0")]
 415     fn last_write_time(&self) -> u64;
 416
 417     /// Returns the value of the `nFileSize{High,Low}` fields of this
 418     /// metadata.
 419     ///
 420     /// The returned value does not have meaning for directories.
 421     ///
 422     /// # Examples
 423     ///
 424     /// ```no_run
 425     /// use std::io;
 426     /// use std::fs;
 427     /// use std::os::windows::prelude::*;
 428     ///
 429     /// # fn foo() -> io::Result<()> {
 430     /// let metadata = fs::metadata("foo.txt")?;
 431     /// let file_size = metadata.file_size();
 432     /// # Ok(())
 433     /// # }
 434     /// ```
 435     #[stable(feature = "metadata_ext", since = "1.1.0")]
 436     fn file_size(&self) -> u64;
 437 }
 438
 439 #[stable(feature = "metadata_ext", since = "1.1.0")]
 440 impl MetadataExt for Metadata {
 441     fn file_attributes(&self) -> u32 { self.as_inner().attrs() }
 442     fn creation_time(&self) -> u64 { self.as_inner().created_u64() }
 443     fn last_access_time(&self) -> u64 { self.as_inner().accessed_u64() }
 444     fn last_write_time(&self) -> u64 { self.as_inner().modified_u64() }
 445     fn file_size(&self) -> u64 { self.as_inner().size() }
 446 }
 447
 448 /// Creates a new file symbolic link on the filesystem.
 449 ///
 450 /// The `dst` path will be a file symbolic link pointing to the `src`
 451 /// path.
 452 ///
 453 /// # Examples
 454 ///
 455 /// ```no_run
 456 /// use std::os::windows::fs;
 457 ///
 458 /// # fn foo() -> std::io::Result<()> {
 459 /// fs::symlink_file("a.txt", "b.txt")?;
 460 /// # Ok(())
 461 /// # }
 462 /// ```
 463 #[stable(feature = "symlink", since = "1.1.0")]
 464 pub fn symlink_file<P: AsRef<Path>, Q: AsRef<Path>>(src: P, dst: Q)
 465                                                     -> io::Result<()> {
 466     sys::fs::symlink_inner(src.as_ref(), dst.as_ref(), false)
 467 }
 468
 469 /// Creates a new directory symlink on the filesystem.
 470 ///
 471 /// The `dst` path will be a directory symbolic link pointing to the `src`
 472 /// path.
 473 ///
 474 /// # Examples
 475 ///
 476 /// ```no_run
 477 /// use std::os::windows::fs;
 478 ///
 479 /// # fn foo() -> std::io::Result<()> {
 480 /// fs::symlink_dir("a", "b")?;
 481 /// # Ok(())
 482 /// # }
 483 /// ```
 484 #[stable(feature = "symlink", since = "1.1.0")]
 485 pub fn symlink_dir<P: AsRef<Path>, Q: AsRef<Path>>(src: P, dst: Q)
 486                                                    -> io::Result<()> {
 487     sys::fs::symlink_inner(src.as_ref(), dst.as_ref(), true)
 488 }