cap_primitives/fs/
dir_entry.rs

1use crate::fs::{
2    dir_options, DirEntryInner, FileType, FollowSymlinks, Metadata, OpenOptions, ReadDir,
3};
4#[cfg(not(windows))]
5use rustix::fs::DirEntryExt;
6use std::ffi::OsString;
7use std::{fmt, fs, io};
8
9/// Entries returned by the `ReadDir` iterator.
10///
11/// This corresponds to [`std::fs::DirEntry`].
12///
13/// Unlike `std::fs::DirEntry`, this API has no `DirEntry::path`, because
14/// absolute paths don't interoperate well with the capability model.
15///
16/// There is a `file_name` function, however there are also `open`,
17/// `open_with`, `open_dir`, `remove_file`, and `remove_dir` functions for
18/// opening or removing the entry directly, which can be more efficient and
19/// convenient.
20///
21/// There is no `from_std` method, as `std::fs::DirEntry` doesn't provide a way
22/// to construct a `DirEntry` without opening directories by ambient paths.
23pub struct DirEntry {
24    pub(crate) inner: DirEntryInner,
25}
26
27impl DirEntry {
28    /// Open the file for reading.
29    #[inline]
30    pub fn open(&self) -> io::Result<fs::File> {
31        self.open_with(OpenOptions::new().read(true))
32    }
33
34    /// Open the file with the given options.
35    #[inline]
36    pub fn open_with(&self, options: &OpenOptions) -> io::Result<fs::File> {
37        self.inner.open(options)
38    }
39
40    /// Open the entry as a directory.
41    #[inline]
42    pub fn open_dir(&self) -> io::Result<fs::File> {
43        self.open_with(&dir_options())
44    }
45
46    /// Removes the file from its filesystem.
47    #[inline]
48    pub fn remove_file(&self) -> io::Result<()> {
49        self.inner.remove_file()
50    }
51
52    /// Removes the directory from its filesystem.
53    #[inline]
54    pub fn remove_dir(&self) -> io::Result<()> {
55        self.inner.remove_dir()
56    }
57
58    /// Returns an iterator over the entries within the subdirectory.
59    #[inline]
60    pub fn read_dir(&self) -> io::Result<ReadDir> {
61        self.inner.read_dir(FollowSymlinks::Yes)
62    }
63
64    /// Returns the metadata for the file that this entry points at.
65    ///
66    /// This corresponds to [`std::fs::DirEntry::metadata`].
67    ///
68    /// # Platform-specific behavior
69    ///
70    /// On Windows, this produces a `Metadata` object which does not contain
71    /// the optional values returned by [`MetadataExt`]. Use
72    /// [`cap_fs_ext::DirEntryExt::full_metadata`] to obtain a `Metadata` with
73    /// the values filled in.
74    ///
75    /// [`MetadataExt`]: https://doc.rust-lang.org/std/os/windows/fs/trait.MetadataExt.html
76    /// [`cap_fs_ext::DirEntryExt::full_metadata`]: https://docs.rs/cap-fs-ext/latest/cap_fs_ext/trait.DirEntryExt.html#tymethod.full_metadata
77    #[inline]
78    pub fn metadata(&self) -> io::Result<Metadata> {
79        self.inner.metadata()
80    }
81
82    /// Returns the file type for the file that this entry points at.
83    ///
84    /// This corresponds to [`std::fs::DirEntry::file_type`].
85    ///
86    /// # Platform-specific behavior
87    ///
88    /// On Windows and most Unix platforms this function is free (no extra system calls needed), but
89    /// some Unix platforms may require the equivalent call to `metadata` to learn about the target
90    /// file type.
91    #[inline]
92    pub fn file_type(&self) -> io::Result<FileType> {
93        self.inner.file_type()
94    }
95
96    /// Returns the bare file name of this directory entry without any other
97    /// leading path component.
98    ///
99    /// This corresponds to [`std::fs::DirEntry::file_name`].
100    #[inline]
101    pub fn file_name(&self) -> OsString {
102        self.inner.file_name()
103    }
104
105    #[cfg(any(not(windows), windows_by_handle))]
106    #[cfg_attr(windows, allow(dead_code))]
107    #[inline]
108    pub(crate) fn is_same_file(&self, metadata: &Metadata) -> io::Result<bool> {
109        self.inner.is_same_file(metadata)
110    }
111}
112
113#[cfg(not(windows))]
114impl DirEntryExt for DirEntry {
115    #[inline]
116    fn ino(&self) -> u64 {
117        self.inner.ino()
118    }
119}
120
121impl fmt::Debug for DirEntry {
122    // Like libstd's version, but doesn't print the path.
123    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
124        self.inner.fmt(f)
125    }
126}
127
128/// Extension trait to allow `full_metadata` etc. to be exposed by
129/// the `cap-fs-ext` crate.
130///
131/// This is hidden from the main API since this functionality isn't present in
132/// `std`. Use `cap_fs_ext::DirEntryExt` instead of calling this directly.
133#[cfg(windows)]
134#[doc(hidden)]
135pub trait _WindowsDirEntryExt {
136    fn full_metadata(&self) -> io::Result<Metadata>;
137}
cap_primitives/fs/dir_entry.rs

cap_primitives/fs/
dir_entry.rs
