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