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.
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.
11 //! Windows-specific extensions for the primitives in `std::fs`
13 #![stable(feature = "rust1", since = "1.0.0")]
15 use fs::{OpenOptions, Metadata};
19 use sys_common::{AsInnerMut, AsInner};
21 /// Windows-specific extensions to `OpenOptions`
22 #[unstable(feature = "open_options_ext",
23 reason = "may require more thought/methods",
25 pub trait OpenOptionsExt {
26 /// Overrides the `dwDesiredAccess` argument to the call to `CreateFile`
27 /// with the specified value.
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.
37 /// #![feature(open_options_ext)]
38 /// use std::fs::OpenOptions;
39 /// use std::os::windows::fs::OpenOptionsExt;
41 /// // Open without read and write permission, for example if you only need to call `stat()`
43 /// let file = OpenOptions::new().access_mode(0).open("foo.txt");
45 fn access_mode(&mut self, access: u32) -> &mut Self;
47 /// Overrides the `dwShareMode` argument to the call to `CreateFile` with
48 /// the specified value.
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.
57 /// #![feature(open_options_ext)]
58 /// use std::fs::OpenOptions;
59 /// use std::os::windows::fs::OpenOptionsExt;
61 /// let file = OpenOptions::new().write(true)
62 /// .share_mode(0) // Do not allow others to read or modify
65 fn share_mode(&mut self, val: u32) -> &mut Self;
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`).
71 /// Custom flags can only set flags, not remove flags set by Rusts options.
76 /// extern crate winapi;
77 /// use std::fs::OpenOptions;
78 /// use std::os::windows::fs::OpenOptionsExt;
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");
84 #[unstable(feature = "expand_open_options",
85 reason = "recently added",
87 fn custom_flags(&mut self, flags: u32) -> &mut Self;
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`).
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()`.
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
101 /// In all other cases the attributes get ignored.
106 /// #![feature(open_options_ext)]
107 /// extern crate winapi;
108 /// use std::fs::OpenOptions;
109 /// use std::os::windows::fs::OpenOptionsExt;
111 /// let file = OpenOptions::new().write(true).create(true)
112 /// .attributes(winapi::FILE_ATTRIBUTE_HIDDEN)
113 /// .open("foo.txt");
115 fn attributes(&mut self, val: u32) -> &mut Self;
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;
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;
127 #[unstable(feature = "open_options_ext",
128 reason = "may require more thought/methods",
130 impl OpenOptionsExt for OpenOptions {
131 fn access_mode(&mut self, access: u32) -> &mut OpenOptions {
132 self.as_inner_mut().access_mode(access); self
135 fn share_mode(&mut self, share: u32) -> &mut OpenOptions {
136 self.as_inner_mut().share_mode(share); self
139 fn custom_flags(&mut self, flags: u32) -> &mut OpenOptions {
140 self.as_inner_mut().custom_flags(flags); self
143 fn attributes(&mut self, attributes: u32) -> &mut OpenOptions {
144 self.as_inner_mut().attributes(attributes); self
147 fn security_qos_flags(&mut self, flags: u32) -> &mut OpenOptions {
148 self.as_inner_mut().security_qos_flags(flags); self
151 fn security_attributes(&mut self, attrs: sys::c::LPSECURITY_ATTRIBUTES) -> &mut OpenOptions {
152 self.as_inner_mut().security_attributes(attrs); self
156 /// Extension methods for `fs::Metadata` to access the raw fields contained
158 #[stable(feature = "metadata_ext", since = "1.1.0")]
159 pub trait MetadataExt {
160 /// Returns the value of the `dwFileAttributes` field of this metadata.
162 /// This field contains the file system attribute information for a file
164 #[stable(feature = "metadata_ext", since = "1.1.0")]
165 fn file_attributes(&self) -> u32;
167 /// Returns the value of the `ftCreationTime` field of this metadata.
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;
174 /// Returns the value of the `ftLastAccessTime` field of this metadata.
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;
181 /// Returns the value of the `ftLastWriteTime` field of this metadata.
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;
188 /// Returns the value of the `nFileSize{High,Low}` fields of this
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;
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() }
205 /// Creates a new file symbolic link on the filesystem.
207 /// The `dst` path will be a file symbolic link pointing to the `src`
213 /// use std::os::windows::fs;
215 /// # fn foo() -> std::io::Result<()> {
216 /// try!(fs::symlink_file("a.txt", "b.txt"));
220 #[stable(feature = "symlink", since = "1.1.0")]
221 pub fn symlink_file<P: AsRef<Path>, Q: AsRef<Path>>(src: P, dst: Q)
223 sys::fs::symlink_inner(src.as_ref(), dst.as_ref(), false)
226 /// Creates a new directory symlink on the filesystem.
228 /// The `dst` path will be a directory symbolic link pointing to the `src`
234 /// use std::os::windows::fs;
236 /// # fn foo() -> std::io::Result<()> {
237 /// try!(fs::symlink_file("a", "b"));
241 #[stable(feature = "symlink", since = "1.1.0")]
242 pub fn symlink_dir<P: AsRef<Path>, Q: AsRef<Path>>(src: P, dst: Q)
244 sys::fs::symlink_inner(src.as_ref(), dst.as_ref(), true)