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