8
8
// option. This file may not be copied, modified, or distributed
9
9
// except according to those terms.
10
10
11
- //! Windows-specific extensions for the primitives in `std::fs`
11
+ //! Windows-specific extensions for the primitives in the `std::fs` module.
12
12
13
13
#![ stable( feature = "rust1" , since = "1.0.0" ) ]
14
14
@@ -35,6 +35,25 @@ pub trait FileExt {
35
35
/// Note that similar to `File::read`, it is not an error to return with a
36
36
/// short read. When returning from such a short read, the file pointer is
37
37
/// still updated.
38
+ ///
39
+ /// # Examples
40
+ ///
41
+ /// ```
42
+ /// use std::io;
43
+ /// use std::io::prelude::*;
44
+ /// use std::fs::File;
45
+ /// use std::os::windows::prelude::*;
46
+ ///
47
+ /// # fn foo() -> io::Result<()> {
48
+ /// let mut file = File::open("foo.txt")?;
49
+ /// let mut buffer = [0; 10];
50
+ ///
51
+ /// // Read 10 bytes, starting 72 bytes from the
52
+ /// // start of the file.
53
+ /// file.seek_read(&mut buffer[..], 72)?;
54
+ /// # Ok(())
55
+ /// # }
56
+ /// ```
38
57
#[ stable( feature = "file_offset" , since = "1.15.0" ) ]
39
58
fn seek_read ( & self , buf : & mut [ u8 ] , offset : u64 ) -> io:: Result < usize > ;
40
59
@@ -52,6 +71,23 @@ pub trait FileExt {
52
71
/// Note that similar to `File::write`, it is not an error to return a
53
72
/// short write. When returning from such a short write, the file pointer
54
73
/// is still updated.
74
+ ///
75
+ /// # Examples
76
+ ///
77
+ /// ```
78
+ /// use std::io::prelude::*;
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.write(b"some bytes", offset)?;
88
+ /// # Ok(())
89
+ /// # }
90
+ /// ```
55
91
#[ stable( feature = "file_offset" , since = "1.15.0" ) ]
56
92
fn seek_write ( & self , buf : & [ u8 ] , offset : u64 ) -> io:: Result < usize > ;
57
93
}
@@ -70,13 +106,13 @@ impl FileExt for fs::File {
70
106
/// Windows-specific extensions to `OpenOptions`
71
107
#[ stable( feature = "open_options_ext" , since = "1.10.0" ) ]
72
108
pub trait OpenOptionsExt {
73
- /// Overrides the `dwDesiredAccess` argument to the call to `CreateFile`
109
+ /// Overrides the `dwDesiredAccess` argument to the call to [ `CreateFile`]
74
110
/// with the specified value.
75
111
///
76
112
/// This will override the `read`, `write`, and `append` flags on the
77
113
/// `OpenOptions` structure. This method provides fine-grained control over
78
114
/// the permissions to read, write and append data, attributes (like hidden
79
- /// and system) and extended attributes.
115
+ /// and system), and extended attributes.
80
116
///
81
117
/// # Examples
82
118
///
@@ -88,16 +124,20 @@ pub trait OpenOptionsExt {
88
124
/// // to call `stat()` on the file
89
125
/// let file = OpenOptions::new().access_mode(0).open("foo.txt");
90
126
/// ```
127
+ ///
128
+ /// [`CreateFile`]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa363858.aspx
91
129
#[ stable( feature = "open_options_ext" , since = "1.10.0" ) ]
92
130
fn access_mode ( & mut self , access : u32 ) -> & mut Self ;
93
131
94
- /// Overrides the `dwShareMode` argument to the call to `CreateFile` with
132
+ /// Overrides the `dwShareMode` argument to the call to [ `CreateFile`] with
95
133
/// the specified value.
96
134
///
97
135
/// 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.
136
+ /// `FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE`. This allows
137
+ /// other processes to to read, write, and delete/rename the same file
138
+ /// while it is open. Removing any of the flags will prevent other
139
+ /// processes from performing the corresponding operation until the file
140
+ /// handle is closed.
101
141
///
102
142
/// # Examples
103
143
///
@@ -106,42 +146,46 @@ pub trait OpenOptionsExt {
106
146
/// use std::os::windows::fs::OpenOptionsExt;
107
147
///
108
148
/// // Do not allow others to read or modify this file while we have it open
109
- /// // for writing
149
+ /// // for writing.
110
150
/// let file = OpenOptions::new().write(true)
111
151
/// .share_mode(0)
112
152
/// .open("foo.txt");
113
153
/// ```
154
+ ///
155
+ /// [`CreateFile`]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa363858.aspx
114
156
#[ stable( feature = "open_options_ext" , since = "1.10.0" ) ]
115
157
fn share_mode ( & mut self , val : u32 ) -> & mut Self ;
116
158
117
159
/// 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`).
160
+ /// [`CreateFile2`] to the specified value (or combines it with
161
+ /// `attributes` and `security_qos_flags` to set the `dwFlagsAndAttributes`
162
+ /// for [`CreateFile`]).
120
163
///
121
- /// Custom flags can only set flags, not remove flags set by Rusts options.
122
- /// This options overwrites any previously set custom flags.
164
+ /// Custom flags can only set flags, not remove flags set by Rust's options.
165
+ /// This option overwrites any previously set custom flags.
123
166
///
124
167
/// # Examples
125
168
///
126
- /// ```rust, ignore
169
+ /// ```ignore
127
170
/// extern crate winapi;
128
171
/// use std::fs::OpenOptions;
129
172
/// use std::os::windows::fs::OpenOptionsExt;
130
173
///
131
174
/// let mut options = OpenOptions::new();
132
175
/// options.create(true).write(true);
133
- /// if cfg!(windows) {
134
- /// options.custom_flags(winapi::FILE_FLAG_DELETE_ON_CLOSE);
135
- /// }
176
+ /// options.custom_flags(winapi::FILE_FLAG_DELETE_ON_CLOSE);
136
177
/// let file = options.open("foo.txt");
137
178
/// ```
179
+ ///
180
+ /// [`CreateFile`]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa363858.aspx
181
+ /// [`CreateFile2`]: https://msdn.microsoft.com/en-us/library/windows/desktop/hh449422.aspx
138
182
#[ stable( feature = "open_options_ext" , since = "1.10.0" ) ]
139
183
fn custom_flags ( & mut self , flags : u32 ) -> & mut Self ;
140
184
141
- /// Sets the `dwFileAttributes` argument to the call to `CreateFile2` to
185
+ /// Sets the `dwFileAttributes` argument to the call to [ `CreateFile2`] to
142
186
/// the specified value (or combines it with `custom_flags` and
143
187
/// `security_qos_flags` to set the `dwFlagsAndAttributes` for
144
- /// `CreateFile`).
188
+ /// [ `CreateFile`] ).
145
189
///
146
190
/// If a _new_ file is created because it does not yet exist and
147
191
///`.create(true)` or `.create_new(true)` are specified, the new file is
@@ -155,7 +199,7 @@ pub trait OpenOptionsExt {
155
199
///
156
200
/// # Examples
157
201
///
158
- /// ```rust, ignore
202
+ /// ```ignore
159
203
/// extern crate winapi;
160
204
/// use std::fs::OpenOptions;
161
205
/// use std::os::windows::fs::OpenOptionsExt;
@@ -164,12 +208,38 @@ pub trait OpenOptionsExt {
164
208
/// .attributes(winapi::FILE_ATTRIBUTE_HIDDEN)
165
209
/// .open("foo.txt");
166
210
/// ```
211
+ ///
212
+ /// [`CreateFile`]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa363858.aspx
213
+ /// [`CreateFile2`]: https://msdn.microsoft.com/en-us/library/windows/desktop/hh449422.aspx
167
214
#[ stable( feature = "open_options_ext" , since = "1.10.0" ) ]
168
215
fn attributes ( & mut self , val : u32 ) -> & mut Self ;
169
216
170
- /// Sets the `dwSecurityQosFlags` argument to the call to `CreateFile2` to
217
+ /// Sets the `dwSecurityQosFlags` argument to the call to [ `CreateFile2`] to
171
218
/// the specified value (or combines it with `custom_flags` and `attributes`
172
- /// to set the `dwFlagsAndAttributes` for `CreateFile`).
219
+ /// to set the `dwFlagsAndAttributes` for [`CreateFile`]).
220
+ ///
221
+ /// By default, `security_qos_flags` is set to `SECURITY_ANONYMOUS`. For
222
+ /// information about possible values, see [Impersonation Levels] on the
223
+ /// Windows Dev Center site.
224
+ ///
225
+ /// # Examples
226
+ ///
227
+ /// ```ignore
228
+ /// use std::fs::OpenOptions;
229
+ /// use std::os::windows::fs::OpenOptionsExt;
230
+ ///
231
+ /// let options = OpenOptions::new();
232
+ /// options.write(true).create(true);
233
+ ///
234
+ /// // Sets the flag value to `SecurityIdentification`.
235
+ /// options.security_qos_flags(1);
236
+ ///
237
+ /// let file = options.open("foo.txt");
238
+ /// ```
239
+ ///
240
+ /// [`CreateFile`]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa363858.aspx
241
+ /// [`CreateFile2`]: https://msdn.microsoft.com/en-us/library/windows/desktop/hh449422.aspx
242
+ /// [Impersonation Levels]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa379572.aspx
173
243
#[ stable( feature = "open_options_ext" , since = "1.10.0" ) ]
174
244
fn security_qos_flags ( & mut self , flags : u32 ) -> & mut OpenOptions ;
175
245
}
0 commit comments