std/os/windows/fs.rs
1//! Windows-specific extensions to primitives in the [`std::fs`] module.
2//!
3//! [`std::fs`]: crate::fs
4
5#![stable(feature = "rust1", since = "1.0.0")]
6
7use crate::fs::{self, Metadata, OpenOptions};
8use crate::io::BorrowedCursor;
9use crate::path::Path;
10use crate::sealed::Sealed;
11use crate::sys::{AsInner, AsInnerMut, IntoInner};
12use crate::time::SystemTime;
13use crate::{io, sys};
14
15/// Windows-specific extensions to [`fs::File`].
16#[stable(feature = "file_offset", since = "1.15.0")]
17pub trait FileExt {
18 /// Seeks to a given position and reads a number of bytes.
19 ///
20 /// Returns the number of bytes read.
21 ///
22 /// The offset is relative to the start of the file and thus independent
23 /// from the current cursor. The current cursor **is** affected by this
24 /// function, it is set to the end of the read.
25 ///
26 /// Reading beyond the end of the file will always return with a length of
27 /// 0\.
28 ///
29 /// Note that similar to `File::read`, it is not an error to return with a
30 /// short read. When returning from such a short read, the file pointer is
31 /// still updated.
32 ///
33 /// # Examples
34 ///
35 /// ```no_run
36 /// use std::io;
37 /// use std::fs::File;
38 /// use std::os::windows::prelude::*;
39 ///
40 /// fn main() -> io::Result<()> {
41 /// let mut file = File::open("foo.txt")?;
42 /// let mut buffer = [0; 10];
43 ///
44 /// // Read 10 bytes, starting 72 bytes from the
45 /// // start of the file.
46 /// file.seek_read(&mut buffer[..], 72)?;
47 /// Ok(())
48 /// }
49 /// ```
50 #[stable(feature = "file_offset", since = "1.15.0")]
51 fn seek_read(&self, buf: &mut [u8], offset: u64) -> io::Result<usize>;
52
53 /// Seeks to a given position and reads some bytes into the buffer.
54 ///
55 /// This is equivalent to the [`seek_read`](FileExt::seek_read) method, except that it is passed
56 /// a [`BorrowedCursor`] rather than `&mut [u8]` to allow use with uninitialized buffers. The
57 /// new data will be appended to any existing contents of `buf`.
58 ///
59 /// Reading beyond the end of the file will always succeed without reading any bytes.
60 ///
61 /// # Examples
62 ///
63 /// ```no_run
64 /// #![feature(core_io_borrowed_buf)]
65 /// #![feature(read_buf_at)]
66 ///
67 /// use std::io;
68 /// use std::io::BorrowedBuf;
69 /// use std::fs::File;
70 /// use std::mem::MaybeUninit;
71 /// use std::os::windows::prelude::*;
72 ///
73 /// fn main() -> io::Result<()> {
74 /// let mut file = File::open("pi.txt")?;
75 ///
76 /// // Read some bytes starting from offset 2
77 /// let mut buf: [MaybeUninit<u8>; 10] = [MaybeUninit::uninit(); 10];
78 /// let mut buf = BorrowedBuf::from(buf.as_mut_slice());
79 /// file.seek_read_buf(buf.unfilled(), 2)?;
80 ///
81 /// assert!(buf.filled().starts_with(b"1"));
82 ///
83 /// Ok(())
84 /// }
85 /// ```
86 #[unstable(feature = "read_buf_at", issue = "140771")]
87 fn seek_read_buf(&self, buf: BorrowedCursor<'_>, offset: u64) -> io::Result<()> {
88 io::default_read_buf(|b| self.seek_read(b, offset), buf)
89 }
90
91 /// Seeks to a given position and writes a number of bytes.
92 ///
93 /// Returns the number of bytes written.
94 ///
95 /// The offset is relative to the start of the file and thus independent
96 /// from the current cursor. The current cursor **is** affected by this
97 /// function, it is set to the end of the write.
98 ///
99 /// When writing beyond the end of the file, the file is appropriately
100 /// extended and the intermediate bytes are set to zero.
101 ///
102 /// Note that similar to `File::write`, it is not an error to return a
103 /// short write. When returning from such a short write, the file pointer
104 /// is still updated.
105 ///
106 /// # Examples
107 ///
108 /// ```no_run
109 /// use std::fs::File;
110 /// use std::os::windows::prelude::*;
111 ///
112 /// fn main() -> std::io::Result<()> {
113 /// let mut buffer = File::create("foo.txt")?;
114 ///
115 /// // Write a byte string starting 72 bytes from
116 /// // the start of the file.
117 /// buffer.seek_write(b"some bytes", 72)?;
118 /// Ok(())
119 /// }
120 /// ```
121 #[stable(feature = "file_offset", since = "1.15.0")]
122 fn seek_write(&self, buf: &[u8], offset: u64) -> io::Result<usize>;
123}
124
125#[stable(feature = "file_offset", since = "1.15.0")]
126impl FileExt for fs::File {
127 fn seek_read(&self, buf: &mut [u8], offset: u64) -> io::Result<usize> {
128 self.as_inner().read_at(buf, offset)
129 }
130
131 fn seek_read_buf(&self, buf: BorrowedCursor<'_>, offset: u64) -> io::Result<()> {
132 self.as_inner().read_buf_at(buf, offset)
133 }
134
135 fn seek_write(&self, buf: &[u8], offset: u64) -> io::Result<usize> {
136 self.as_inner().write_at(buf, offset)
137 }
138}
139
140/// Windows-specific extensions to [`fs::OpenOptions`].
141#[stable(feature = "open_options_ext", since = "1.10.0")]
142pub trait OpenOptionsExt {
143 /// Overrides the `dwDesiredAccess` argument to the call to [`CreateFile`]
144 /// with the specified value.
145 ///
146 /// This will override the `read`, `write`, and `append` flags on the
147 /// `OpenOptions` structure. This method provides fine-grained control over
148 /// the permissions to read, write and append data, attributes (like hidden
149 /// and system), and extended attributes.
150 ///
151 /// # Examples
152 ///
153 /// ```no_run
154 /// use std::fs::OpenOptions;
155 /// use std::os::windows::prelude::*;
156 ///
157 /// // Open without read and write permission, for example if you only need
158 /// // to call `stat` on the file
159 /// let file = OpenOptions::new().access_mode(0).open("foo.txt");
160 /// ```
161 ///
162 /// [`CreateFile`]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea
163 #[stable(feature = "open_options_ext", since = "1.10.0")]
164 fn access_mode(&mut self, access: u32) -> &mut Self;
165
166 /// Overrides the `dwShareMode` argument to the call to [`CreateFile`] with
167 /// the specified value.
168 ///
169 /// By default `share_mode` is set to
170 /// `FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE`. This allows
171 /// other processes to read, write, and delete/rename the same file
172 /// while it is open. Removing any of the flags will prevent other
173 /// processes from performing the corresponding operation until the file
174 /// handle is closed.
175 ///
176 /// # Examples
177 ///
178 /// ```no_run
179 /// use std::fs::OpenOptions;
180 /// use std::os::windows::prelude::*;
181 ///
182 /// // Do not allow others to read or modify this file while we have it open
183 /// // for writing.
184 /// let file = OpenOptions::new()
185 /// .write(true)
186 /// .share_mode(0)
187 /// .open("foo.txt");
188 /// ```
189 ///
190 /// [`CreateFile`]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea
191 #[stable(feature = "open_options_ext", since = "1.10.0")]
192 fn share_mode(&mut self, val: u32) -> &mut Self;
193
194 /// Sets extra flags for the `dwFileFlags` argument to the call to
195 /// [`CreateFile2`] to the specified value (or combines it with
196 /// `attributes` and `security_qos_flags` to set the `dwFlagsAndAttributes`
197 /// for [`CreateFile`]).
198 ///
199 /// Custom flags can only set flags, not remove flags set by Rust's options.
200 /// This option overwrites any previously set custom flags.
201 ///
202 /// # Examples
203 ///
204 /// ```no_run
205 /// # #![allow(unexpected_cfgs)]
206 /// # #[cfg(for_demonstration_only)]
207 /// extern crate winapi;
208 /// # mod winapi { pub const FILE_FLAG_DELETE_ON_CLOSE: u32 = 0x04000000; }
209 ///
210 /// use std::fs::OpenOptions;
211 /// use std::os::windows::prelude::*;
212 ///
213 /// let file = OpenOptions::new()
214 /// .create(true)
215 /// .write(true)
216 /// .custom_flags(winapi::FILE_FLAG_DELETE_ON_CLOSE)
217 /// .open("foo.txt");
218 /// ```
219 ///
220 /// [`CreateFile`]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea
221 /// [`CreateFile2`]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfile2
222 #[stable(feature = "open_options_ext", since = "1.10.0")]
223 fn custom_flags(&mut self, flags: u32) -> &mut Self;
224
225 /// Sets the `dwFileAttributes` argument to the call to [`CreateFile2`] to
226 /// the specified value (or combines it with `custom_flags` and
227 /// `security_qos_flags` to set the `dwFlagsAndAttributes` for
228 /// [`CreateFile`]).
229 ///
230 /// If a _new_ file is created because it does not yet exist and
231 /// `.create(true)` or `.create_new(true)` are specified, the new file is
232 /// given the attributes declared with `.attributes()`.
233 ///
234 /// If an _existing_ file is opened with `.create(true).truncate(true)`, its
235 /// existing attributes are preserved and combined with the ones declared
236 /// with `.attributes()`.
237 ///
238 /// In all other cases the attributes get ignored.
239 ///
240 /// # Examples
241 ///
242 /// ```no_run
243 /// # #![allow(unexpected_cfgs)]
244 /// # #[cfg(for_demonstration_only)]
245 /// extern crate winapi;
246 /// # mod winapi { pub const FILE_ATTRIBUTE_HIDDEN: u32 = 2; }
247 ///
248 /// use std::fs::OpenOptions;
249 /// use std::os::windows::prelude::*;
250 ///
251 /// let file = OpenOptions::new()
252 /// .write(true)
253 /// .create(true)
254 /// .attributes(winapi::FILE_ATTRIBUTE_HIDDEN)
255 /// .open("foo.txt");
256 /// ```
257 ///
258 /// [`CreateFile`]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea
259 /// [`CreateFile2`]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfile2
260 #[stable(feature = "open_options_ext", since = "1.10.0")]
261 fn attributes(&mut self, val: u32) -> &mut Self;
262
263 /// Sets the `dwSecurityQosFlags` argument to the call to [`CreateFile2`] to
264 /// the specified value (or combines it with `custom_flags` and `attributes`
265 /// to set the `dwFlagsAndAttributes` for [`CreateFile`]).
266 ///
267 /// By default `security_qos_flags` is not set. It should be specified when
268 /// opening a named pipe, to control to which degree a server process can
269 /// act on behalf of a client process (security impersonation level).
270 ///
271 /// When `security_qos_flags` is not set, a malicious program can gain the
272 /// elevated privileges of a privileged Rust process when it allows opening
273 /// user-specified paths, by tricking it into opening a named pipe. So
274 /// arguably `security_qos_flags` should also be set when opening arbitrary
275 /// paths. However the bits can then conflict with other flags, specifically
276 /// `FILE_FLAG_OPEN_NO_RECALL`.
277 ///
278 /// For information about possible values, see [Impersonation Levels] on the
279 /// Windows Dev Center site. The `SECURITY_SQOS_PRESENT` flag is set
280 /// automatically when using this method.
281
282 /// # Examples
283 ///
284 /// ```no_run
285 /// # #![allow(unexpected_cfgs)]
286 /// # #[cfg(for_demonstration_only)]
287 /// extern crate winapi;
288 /// # mod winapi { pub const SECURITY_IDENTIFICATION: u32 = 0; }
289 /// use std::fs::OpenOptions;
290 /// use std::os::windows::prelude::*;
291 ///
292 /// let file = OpenOptions::new()
293 /// .write(true)
294 /// .create(true)
295 ///
296 /// // Sets the flag value to `SecurityIdentification`.
297 /// .security_qos_flags(winapi::SECURITY_IDENTIFICATION)
298 ///
299 /// .open(r"\\.\pipe\MyPipe");
300 /// ```
301 ///
302 /// [`CreateFile`]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea
303 /// [`CreateFile2`]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfile2
304 /// [Impersonation Levels]:
305 /// https://docs.microsoft.com/en-us/windows/win32/api/winnt/ne-winnt-security_impersonation_level
306 #[stable(feature = "open_options_ext", since = "1.10.0")]
307 fn security_qos_flags(&mut self, flags: u32) -> &mut Self;
308
309 /// If set to `true`, prevent the "last access time" of the file from being changed.
310 ///
311 /// Default to `false`.
312 #[unstable(feature = "windows_freeze_file_times", issue = "149715")]
313 fn freeze_last_access_time(&mut self, freeze: bool) -> &mut Self;
314
315 /// If set to `true`, prevent the "last write time" of the file from being changed.
316 ///
317 /// Default to `false`.
318 #[unstable(feature = "windows_freeze_file_times", issue = "149715")]
319 fn freeze_last_write_time(&mut self, freeze: bool) -> &mut Self;
320}
321
322#[stable(feature = "open_options_ext", since = "1.10.0")]
323impl OpenOptionsExt for OpenOptions {
324 fn access_mode(&mut self, access: u32) -> &mut OpenOptions {
325 self.as_inner_mut().access_mode(access);
326 self
327 }
328
329 fn share_mode(&mut self, share: u32) -> &mut OpenOptions {
330 self.as_inner_mut().share_mode(share);
331 self
332 }
333
334 fn custom_flags(&mut self, flags: u32) -> &mut OpenOptions {
335 self.as_inner_mut().custom_flags(flags);
336 self
337 }
338
339 fn attributes(&mut self, attributes: u32) -> &mut OpenOptions {
340 self.as_inner_mut().attributes(attributes);
341 self
342 }
343
344 fn security_qos_flags(&mut self, flags: u32) -> &mut OpenOptions {
345 self.as_inner_mut().security_qos_flags(flags);
346 self
347 }
348
349 fn freeze_last_access_time(&mut self, freeze: bool) -> &mut Self {
350 self.as_inner_mut().freeze_last_access_time(freeze);
351 self
352 }
353
354 fn freeze_last_write_time(&mut self, freeze: bool) -> &mut Self {
355 self.as_inner_mut().freeze_last_write_time(freeze);
356 self
357 }
358}
359
360/// Windows-specific extensions to [`fs::Metadata`].
361///
362/// The data members that this trait exposes correspond to the members
363/// of the [`BY_HANDLE_FILE_INFORMATION`] structure.
364///
365/// [`BY_HANDLE_FILE_INFORMATION`]:
366/// https://docs.microsoft.com/windows/win32/api/fileapi/ns-fileapi-by_handle_file_information
367#[stable(feature = "metadata_ext", since = "1.1.0")]
368pub trait MetadataExt {
369 /// Returns the value of the `dwFileAttributes` field of this metadata.
370 ///
371 /// This field contains the file system attribute information for a file
372 /// or directory. For possible values and their descriptions, see
373 /// [File Attribute Constants] in the Windows Dev Center.
374 ///
375 /// # Examples
376 ///
377 /// ```no_run
378 /// use std::io;
379 /// use std::fs;
380 /// use std::os::windows::prelude::*;
381 ///
382 /// fn main() -> io::Result<()> {
383 /// let metadata = fs::metadata("foo.txt")?;
384 /// let attributes = metadata.file_attributes();
385 /// Ok(())
386 /// }
387 /// ```
388 ///
389 /// [File Attribute Constants]:
390 /// https://docs.microsoft.com/windows/win32/fileio/file-attribute-constants
391 #[stable(feature = "metadata_ext", since = "1.1.0")]
392 fn file_attributes(&self) -> u32;
393
394 /// Returns the value of the `ftCreationTime` field of this metadata.
395 ///
396 /// The returned 64-bit value is equivalent to a [`FILETIME`] struct,
397 /// which represents the number of 100-nanosecond intervals since
398 /// January 1, 1601 (UTC). The struct is automatically
399 /// converted to a `u64` value, as that is the recommended way
400 /// to use it.
401 ///
402 /// If the underlying filesystem does not support creation time, the
403 /// returned value is 0.
404 ///
405 /// # Examples
406 ///
407 /// ```no_run
408 /// use std::io;
409 /// use std::fs;
410 /// use std::os::windows::prelude::*;
411 ///
412 /// fn main() -> io::Result<()> {
413 /// let metadata = fs::metadata("foo.txt")?;
414 /// let creation_time = metadata.creation_time();
415 /// Ok(())
416 /// }
417 /// ```
418 ///
419 /// [`FILETIME`]: https://docs.microsoft.com/windows/win32/api/minwinbase/ns-minwinbase-filetime
420 #[stable(feature = "metadata_ext", since = "1.1.0")]
421 fn creation_time(&self) -> u64;
422
423 /// Returns the value of the `ftLastAccessTime` field of this metadata.
424 ///
425 /// The returned 64-bit value is equivalent to a [`FILETIME`] struct,
426 /// which represents the number of 100-nanosecond intervals since
427 /// January 1, 1601 (UTC). The struct is automatically
428 /// converted to a `u64` value, as that is the recommended way
429 /// to use it.
430 ///
431 /// For a file, the value specifies the last time that a file was read
432 /// from or written to. For a directory, the value specifies when
433 /// the directory was created. For both files and directories, the
434 /// specified date is correct, but the time of day is always set to
435 /// midnight.
436 ///
437 /// If the underlying filesystem does not support last access time, the
438 /// returned value is 0.
439 ///
440 /// # Examples
441 ///
442 /// ```no_run
443 /// use std::io;
444 /// use std::fs;
445 /// use std::os::windows::prelude::*;
446 ///
447 /// fn main() -> io::Result<()> {
448 /// let metadata = fs::metadata("foo.txt")?;
449 /// let last_access_time = metadata.last_access_time();
450 /// Ok(())
451 /// }
452 /// ```
453 ///
454 /// [`FILETIME`]: https://docs.microsoft.com/windows/win32/api/minwinbase/ns-minwinbase-filetime
455 #[stable(feature = "metadata_ext", since = "1.1.0")]
456 fn last_access_time(&self) -> u64;
457
458 /// Returns the value of the `ftLastWriteTime` field of this metadata.
459 ///
460 /// The returned 64-bit value is equivalent to a [`FILETIME`] struct,
461 /// which represents the number of 100-nanosecond intervals since
462 /// January 1, 1601 (UTC). The struct is automatically
463 /// converted to a `u64` value, as that is the recommended way
464 /// to use it.
465 ///
466 /// For a file, the value specifies the last time that a file was written
467 /// to. For a directory, the structure specifies when the directory was
468 /// created.
469 ///
470 /// If the underlying filesystem does not support the last write time,
471 /// the returned value is 0.
472 ///
473 /// # Examples
474 ///
475 /// ```no_run
476 /// use std::io;
477 /// use std::fs;
478 /// use std::os::windows::prelude::*;
479 ///
480 /// fn main() -> io::Result<()> {
481 /// let metadata = fs::metadata("foo.txt")?;
482 /// let last_write_time = metadata.last_write_time();
483 /// Ok(())
484 /// }
485 /// ```
486 ///
487 /// [`FILETIME`]: https://docs.microsoft.com/windows/win32/api/minwinbase/ns-minwinbase-filetime
488 #[stable(feature = "metadata_ext", since = "1.1.0")]
489 fn last_write_time(&self) -> u64;
490
491 /// Returns the value of the `nFileSize` fields of this
492 /// metadata.
493 ///
494 /// The returned value does not have meaning for directories.
495 ///
496 /// # Examples
497 ///
498 /// ```no_run
499 /// use std::io;
500 /// use std::fs;
501 /// use std::os::windows::prelude::*;
502 ///
503 /// fn main() -> io::Result<()> {
504 /// let metadata = fs::metadata("foo.txt")?;
505 /// let file_size = metadata.file_size();
506 /// Ok(())
507 /// }
508 /// ```
509 #[stable(feature = "metadata_ext", since = "1.1.0")]
510 fn file_size(&self) -> u64;
511
512 /// Returns the value of the `dwVolumeSerialNumber` field of this
513 /// metadata.
514 ///
515 /// This will return `None` if the `Metadata` instance was created from a
516 /// call to `DirEntry::metadata`. If this `Metadata` was created by using
517 /// `fs::metadata` or `File::metadata`, then this will return `Some`.
518 #[unstable(feature = "windows_by_handle", issue = "63010")]
519 fn volume_serial_number(&self) -> Option<u32>;
520
521 /// Returns the value of the `nNumberOfLinks` field of this
522 /// metadata.
523 ///
524 /// This will return `None` if the `Metadata` instance was created from a
525 /// call to `DirEntry::metadata`. If this `Metadata` was created by using
526 /// `fs::metadata` or `File::metadata`, then this will return `Some`.
527 #[unstable(feature = "windows_by_handle", issue = "63010")]
528 fn number_of_links(&self) -> Option<u32>;
529
530 /// Returns the value of the `nFileIndex` fields of this
531 /// metadata.
532 ///
533 /// This will return `None` if the `Metadata` instance was created from a
534 /// call to `DirEntry::metadata`. If this `Metadata` was created by using
535 /// `fs::metadata` or `File::metadata`, then this will return `Some`.
536 #[unstable(feature = "windows_by_handle", issue = "63010")]
537 fn file_index(&self) -> Option<u64>;
538
539 /// Returns the value of the `ChangeTime` fields of this metadata.
540 ///
541 /// `ChangeTime` is the last time file metadata was changed, such as
542 /// renames, attributes, etc.
543 ///
544 /// This will return `None` if `Metadata` instance was created from a call to
545 /// `DirEntry::metadata` or if the `target_vendor` is outside the current platform
546 /// support for this api.
547 #[unstable(feature = "windows_change_time", issue = "121478")]
548 fn change_time(&self) -> Option<u64>;
549}
550
551#[stable(feature = "metadata_ext", since = "1.1.0")]
552impl MetadataExt for Metadata {
553 fn file_attributes(&self) -> u32 {
554 self.as_inner().attrs()
555 }
556 fn creation_time(&self) -> u64 {
557 self.as_inner().created_u64()
558 }
559 fn last_access_time(&self) -> u64 {
560 self.as_inner().accessed_u64()
561 }
562 fn last_write_time(&self) -> u64 {
563 self.as_inner().modified_u64()
564 }
565 fn file_size(&self) -> u64 {
566 self.as_inner().size()
567 }
568 fn volume_serial_number(&self) -> Option<u32> {
569 self.as_inner().volume_serial_number()
570 }
571 fn number_of_links(&self) -> Option<u32> {
572 self.as_inner().number_of_links()
573 }
574 fn file_index(&self) -> Option<u64> {
575 self.as_inner().file_index()
576 }
577 fn change_time(&self) -> Option<u64> {
578 self.as_inner().changed_u64()
579 }
580}
581
582/// Windows-specific extensions to [`fs::FileType`].
583///
584/// On Windows, a symbolic link knows whether it is a file or directory.
585#[stable(feature = "windows_file_type_ext", since = "1.64.0")]
586pub trait FileTypeExt: Sealed {
587 /// Returns `true` if this file type is a symbolic link that is also a directory.
588 #[stable(feature = "windows_file_type_ext", since = "1.64.0")]
589 fn is_symlink_dir(&self) -> bool;
590 /// Returns `true` if this file type is a symbolic link that is also a file.
591 #[stable(feature = "windows_file_type_ext", since = "1.64.0")]
592 fn is_symlink_file(&self) -> bool;
593}
594
595#[stable(feature = "windows_file_type_ext", since = "1.64.0")]
596impl Sealed for fs::FileType {}
597
598#[stable(feature = "windows_file_type_ext", since = "1.64.0")]
599impl FileTypeExt for fs::FileType {
600 fn is_symlink_dir(&self) -> bool {
601 self.as_inner().is_symlink_dir()
602 }
603 fn is_symlink_file(&self) -> bool {
604 self.as_inner().is_symlink_file()
605 }
606}
607
608/// Windows-specific extensions to [`fs::FileTimes`].
609#[stable(feature = "file_set_times", since = "1.75.0")]
610pub trait FileTimesExt: Sealed {
611 /// Set the creation time of a file.
612 #[stable(feature = "file_set_times", since = "1.75.0")]
613 fn set_created(self, t: SystemTime) -> Self;
614}
615
616#[stable(feature = "file_set_times", since = "1.75.0")]
617impl FileTimesExt for fs::FileTimes {
618 fn set_created(mut self, t: SystemTime) -> Self {
619 self.as_inner_mut().set_created(t.into_inner());
620 self
621 }
622}
623
624/// Creates a new symlink to a non-directory file on the filesystem.
625///
626/// The `link` path will be a file symbolic link pointing to the `original`
627/// path.
628///
629/// The `original` path should not be a directory or a symlink to a directory,
630/// otherwise the symlink will be broken. Use [`symlink_dir`] for directories.
631///
632/// This function currently corresponds to [`CreateSymbolicLinkW`][CreateSymbolicLinkW].
633/// Note that this [may change in the future][changes].
634///
635/// [CreateSymbolicLinkW]: https://docs.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-createsymboliclinkw
636/// [changes]: io#platform-specific-behavior
637///
638/// # Examples
639///
640/// ```no_run
641/// use std::os::windows::fs;
642///
643/// fn main() -> std::io::Result<()> {
644/// fs::symlink_file("a.txt", "b.txt")?;
645/// Ok(())
646/// }
647/// ```
648///
649/// # Limitations
650///
651/// Windows treats symlink creation as a [privileged action][symlink-security],
652/// therefore this function is likely to fail unless the user makes changes to
653/// their system to permit symlink creation. Users can try enabling Developer
654/// Mode, granting the `SeCreateSymbolicLinkPrivilege` privilege, or running
655/// the process as an administrator.
656///
657/// [symlink-security]: https://docs.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/create-symbolic-links
658#[stable(feature = "symlink", since = "1.1.0")]
659pub fn symlink_file<P: AsRef<Path>, Q: AsRef<Path>>(original: P, link: Q) -> io::Result<()> {
660 sys::fs::symlink_inner(original.as_ref(), link.as_ref(), false)
661}
662
663/// Creates a new symlink to a directory on the filesystem.
664///
665/// The `link` path will be a directory symbolic link pointing to the `original`
666/// path.
667///
668/// The `original` path must be a directory or a symlink to a directory,
669/// otherwise the symlink will be broken. Use [`symlink_file`] for other files.
670///
671/// This function currently corresponds to [`CreateSymbolicLinkW`][CreateSymbolicLinkW].
672/// Note that this [may change in the future][changes].
673///
674/// [CreateSymbolicLinkW]: https://docs.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-createsymboliclinkw
675/// [changes]: io#platform-specific-behavior
676///
677/// # Examples
678///
679/// ```no_run
680/// use std::os::windows::fs;
681///
682/// fn main() -> std::io::Result<()> {
683/// fs::symlink_dir("a", "b")?;
684/// Ok(())
685/// }
686/// ```
687///
688/// # Limitations
689///
690/// Windows treats symlink creation as a [privileged action][symlink-security],
691/// therefore this function is likely to fail unless the user makes changes to
692/// their system to permit symlink creation. Users can try enabling Developer
693/// Mode, granting the `SeCreateSymbolicLinkPrivilege` privilege, or running
694/// the process as an administrator.
695///
696/// [symlink-security]: https://docs.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/create-symbolic-links
697#[stable(feature = "symlink", since = "1.1.0")]
698pub fn symlink_dir<P: AsRef<Path>, Q: AsRef<Path>>(original: P, link: Q) -> io::Result<()> {
699 sys::fs::symlink_inner(original.as_ref(), link.as_ref(), true)
700}
701
702/// Creates a junction point.
703///
704/// The `link` path will be a directory junction pointing to the original path.
705/// If `link` is a relative path then it will be made absolute prior to creating the junction point.
706/// The `original` path must be a directory or a link to a directory, otherwise the junction point will be broken.
707///
708/// If either path is not a local file path then this will fail.
709#[unstable(feature = "junction_point", issue = "121709")]
710pub fn junction_point<P: AsRef<Path>, Q: AsRef<Path>>(original: P, link: Q) -> io::Result<()> {
711 sys::fs::junction_point(original.as_ref(), link.as_ref())
712}