Skip to content

Commit e406cd1

Browse files
committedMay 6, 2017
Update documentation in windows::ffi
·
1.88.01.19.0
1 parent db16ca7 commit e406cd1

File tree

1 file changed

+91
-21
lines changed
  • src/libstd/sys/windows/ext

1 file changed

+91
-21
lines changed
 

‎src/libstd/sys/windows/ext/fs.rs

Lines changed: 91 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
// option. This file may not be copied, modified, or distributed
99
// except according to those terms.
1010

11-
//! Windows-specific extensions for the primitives in `std::fs`
11+
//! Windows-specific extensions for the primitives in the `std::fs` module.
1212
1313
#![stable(feature = "rust1", since = "1.0.0")]
1414

@@ -35,6 +35,25 @@ pub trait FileExt {
3535
/// Note that similar to `File::read`, it is not an error to return with a
3636
/// short read. When returning from such a short read, the file pointer is
3737
/// 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+
/// ```
3857
#[stable(feature = "file_offset", since = "1.15.0")]
3958
fn seek_read(&self, buf: &mut [u8], offset: u64) -> io::Result<usize>;
4059

@@ -52,6 +71,23 @@ pub trait FileExt {
5271
/// Note that similar to `File::write`, it is not an error to return a
5372
/// short write. When returning from such a short write, the file pointer
5473
/// 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+
/// ```
5591
#[stable(feature = "file_offset", since = "1.15.0")]
5692
fn seek_write(&self, buf: &[u8], offset: u64) -> io::Result<usize>;
5793
}
@@ -70,13 +106,13 @@ impl FileExt for fs::File {
70106
/// Windows-specific extensions to `OpenOptions`
71107
#[stable(feature = "open_options_ext", since = "1.10.0")]
72108
pub trait OpenOptionsExt {
73-
/// Overrides the `dwDesiredAccess` argument to the call to `CreateFile`
109+
/// Overrides the `dwDesiredAccess` argument to the call to [`CreateFile`]
74110
/// with the specified value.
75111
///
76112
/// This will override the `read`, `write`, and `append` flags on the
77113
/// `OpenOptions` structure. This method provides fine-grained control over
78114
/// the permissions to read, write and append data, attributes (like hidden
79-
/// and system) and extended attributes.
115+
/// and system), and extended attributes.
80116
///
81117
/// # Examples
82118
///
@@ -88,16 +124,20 @@ pub trait OpenOptionsExt {
88124
/// // to call `stat()` on the file
89125
/// let file = OpenOptions::new().access_mode(0).open("foo.txt");
90126
/// ```
127+
///
128+
/// [`CreateFile`]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa363858.aspx
91129
#[stable(feature = "open_options_ext", since = "1.10.0")]
92130
fn access_mode(&mut self, access: u32) -> &mut Self;
93131

94-
/// Overrides the `dwShareMode` argument to the call to `CreateFile` with
132+
/// Overrides the `dwShareMode` argument to the call to [`CreateFile`] with
95133
/// the specified value.
96134
///
97135
/// 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.
101141
///
102142
/// # Examples
103143
///
@@ -106,42 +146,46 @@ pub trait OpenOptionsExt {
106146
/// use std::os::windows::fs::OpenOptionsExt;
107147
///
108148
/// // Do not allow others to read or modify this file while we have it open
109-
/// // for writing
149+
/// // for writing.
110150
/// let file = OpenOptions::new().write(true)
111151
/// .share_mode(0)
112152
/// .open("foo.txt");
113153
/// ```
154+
///
155+
/// [`CreateFile`]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa363858.aspx
114156
#[stable(feature = "open_options_ext", since = "1.10.0")]
115157
fn share_mode(&mut self, val: u32) -> &mut Self;
116158

117159
/// 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`]).
120163
///
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.
123166
///
124167
/// # Examples
125168
///
126-
/// ```rust,ignore
169+
/// ```ignore
127170
/// extern crate winapi;
128171
/// use std::fs::OpenOptions;
129172
/// use std::os::windows::fs::OpenOptionsExt;
130173
///
131174
/// let mut options = OpenOptions::new();
132175
/// 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);
136177
/// let file = options.open("foo.txt");
137178
/// ```
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
138182
#[stable(feature = "open_options_ext", since = "1.10.0")]
139183
fn custom_flags(&mut self, flags: u32) -> &mut Self;
140184

141-
/// Sets the `dwFileAttributes` argument to the call to `CreateFile2` to
185+
/// Sets the `dwFileAttributes` argument to the call to [`CreateFile2`] to
142186
/// the specified value (or combines it with `custom_flags` and
143187
/// `security_qos_flags` to set the `dwFlagsAndAttributes` for
144-
/// `CreateFile`).
188+
/// [`CreateFile`]).
145189
///
146190
/// If a _new_ file is created because it does not yet exist and
147191
///`.create(true)` or `.create_new(true)` are specified, the new file is
@@ -155,7 +199,7 @@ pub trait OpenOptionsExt {
155199
///
156200
/// # Examples
157201
///
158-
/// ```rust,ignore
202+
/// ```ignore
159203
/// extern crate winapi;
160204
/// use std::fs::OpenOptions;
161205
/// use std::os::windows::fs::OpenOptionsExt;
@@ -164,12 +208,38 @@ pub trait OpenOptionsExt {
164208
/// .attributes(winapi::FILE_ATTRIBUTE_HIDDEN)
165209
/// .open("foo.txt");
166210
/// ```
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
167214
#[stable(feature = "open_options_ext", since = "1.10.0")]
168215
fn attributes(&mut self, val: u32) -> &mut Self;
169216

170-
/// Sets the `dwSecurityQosFlags` argument to the call to `CreateFile2` to
217+
/// Sets the `dwSecurityQosFlags` argument to the call to [`CreateFile2`] to
171218
/// 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
173243
#[stable(feature = "open_options_ext", since = "1.10.0")]
174244
fn security_qos_flags(&mut self, flags: u32) -> &mut OpenOptions;
175245
}

0 commit comments

Comments
 (0)
Please sign in to comment.