1use crate::io;
2use crate::path::Path;
3use crate::task::spawn_blocking;
4
5/// Reads metadata for a path.
6///
7/// This function will traverse symbolic links to read metadata for the target file or directory.
8/// If you want to read metadata without following symbolic links, use [`symlink_metadata`]
9/// instead.
10///
11/// This function is an async version of [`std::fs::metadata`].
12///
13/// [`symlink_metadata`]: fn.symlink_metadata.html
14/// [`std::fs::metadata`]: https://doc.rust-lang.org/std/fs/fn.metadata.html
15///
16/// # Errors
17///
18/// An error will be returned in the following situations:
19///
20/// * `path` does not point to an existing file or directory.
21/// * The current process lacks permissions to read metadata for the path.
22/// * Some other I/O error occurred.
23///
24/// # Examples
25///
26/// ```no_run
27/// # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
28/// #
29/// use async_std::fs;
30///
31/// let perm = fs::metadata("a.txt").await?.permissions();
32/// #
33/// # Ok(()) }) }
34/// ```
35pub async fn metadata<P: AsRef<Path>>(path: P) -> io::Result<Metadata> {
36 let path: PathBuf = path.as_ref().to_owned();
37 spawn_blocking(move || std::fs::metadata(path)).await
38}
39
40cfg_not_docs! {
41 pub use std::fs::Metadata;
42}
43
44cfg_docs! {
45 use std::time::SystemTime;
46
47 use crate::fs::{FileType, Permissions};
48
49 /// Metadata for a file or directory.
50 ///
51 /// Metadata is returned by [`metadata`] and [`symlink_metadata`].
52 ///
53 /// This type is a re-export of [`std::fs::Metadata`].
54 ///
55 /// [`metadata`]: fn.metadata.html
56 /// [`symlink_metadata`]: fn.symlink_metadata.html
57 /// [`is_dir`]: #method.is_dir
58 /// [`is_file`]: #method.is_file
59 /// [`std::fs::Metadata`]: https://doc.rust-lang.org/std/fs/struct.Metadata.html
60 #[derive(Clone, Debug)]
61 pub struct Metadata {
62 _private: (),
63 }
64
65 impl Metadata {
66 /// Returns the file type from this metadata.
67 ///
68 /// # Examples
69 ///
70 /// ```no_run
71 /// # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
72 /// #
73 /// use async_std::fs;
74 ///
75 /// let metadata = fs::metadata("a.txt").await?;
76 /// println!("{:?}", metadata.file_type());
77 /// #
78 /// # Ok(()) }) }
79 /// ```
80 pub fn file_type(&self) -> FileType {
81 unreachable!("this impl only appears in the rendered docs")
82 }
83
84 /// Returns `true` if this metadata is for a regular directory.
85 ///
86 /// If this metadata is for a symbolic link, this method returns `false`.
87 ///
88 /// # Examples
89 ///
90 /// ```no_run
91 /// # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
92 /// #
93 /// use async_std::fs;
94 ///
95 /// let metadata = fs::metadata(".").await?;
96 /// println!("{:?}", metadata.is_dir());
97 /// #
98 /// # Ok(()) }) }
99 /// ```
100 pub fn is_dir(&self) -> bool {
101 unreachable!("this impl only appears in the rendered docs")
102 }
103
104 /// Returns `true` if this metadata is for a regular file.
105 ///
106 /// If this metadata is for a symbolic link, this method returns `false`.
107 ///
108 /// # Examples
109 ///
110 /// ```no_run
111 /// # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
112 /// #
113 /// use async_std::fs;
114 ///
115 /// let metadata = fs::metadata("a.txt").await?;
116 /// println!("{:?}", metadata.is_file());
117 /// #
118 /// # Ok(()) }) }
119 /// ```
120 pub fn is_file(&self) -> bool {
121 unreachable!("this impl only appears in the rendered docs")
122 }
123
124 /// Returns the file size in bytes.
125 ///
126 /// # Examples
127 ///
128 /// ```no_run
129 /// # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
130 /// #
131 /// use async_std::fs;
132 ///
133 /// let metadata = fs::metadata("a.txt").await?;
134 /// println!("{}", metadata.len());
135 /// #
136 /// # Ok(()) }) }
137 /// ```
138 pub fn len(&self) -> u64 {
139 unreachable!("this impl only appears in the rendered docs")
140 }
141
142 /// Returns the permissions from this metadata.
143 ///
144 /// # Examples
145 ///
146 /// ```no_run
147 /// # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
148 /// #
149 /// use async_std::fs;
150 ///
151 /// let metadata = fs::metadata("a.txt").await?;
152 /// println!("{:?}", metadata.permissions());
153 /// #
154 /// # Ok(()) }) }
155 /// ```
156 pub fn permissions(&self) -> Permissions {
157 unreachable!("this impl only appears in the rendered docs")
158 }
159
160 /// Returns the last modification time.
161 ///
162 /// # Errors
163 ///
164 /// This data may not be available on all platforms, in which case an error will be
165 /// returned.
166 ///
167 /// # Examples
168 ///
169 /// ```no_run
170 /// # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
171 /// #
172 /// use async_std::fs;
173 ///
174 /// let metadata = fs::metadata("a.txt").await?;
175 /// println!("{:?}", metadata.modified());
176 /// #
177 /// # Ok(()) }) }
178 /// ```
179 pub fn modified(&self) -> io::Result<SystemTime> {
180 unreachable!("this impl only appears in the rendered docs")
181 }
182
183 /// Returns the last access time.
184 ///
185 /// # Errors
186 ///
187 /// This data may not be available on all platforms, in which case an error will be
188 /// returned.
189 ///
190 /// # Examples
191 ///
192 /// ```no_run
193 /// # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
194 /// #
195 /// use async_std::fs;
196 ///
197 /// let metadata = fs::metadata("a.txt").await?;
198 /// println!("{:?}", metadata.accessed());
199 /// #
200 /// # Ok(()) }) }
201 /// ```
202 pub fn accessed(&self) -> io::Result<SystemTime> {
203 unreachable!("this impl only appears in the rendered docs")
204 }
205
206 /// Returns the creation time.
207 ///
208 /// # Errors
209 ///
210 /// This data may not be available on all platforms, in which case an error will be
211 /// returned.
212 ///
213 /// # Examples
214 ///
215 /// ```no_run
216 /// # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
217 /// #
218 /// use async_std::fs;
219 ///
220 /// let metadata = fs::metadata("a.txt").await?;
221 /// println!("{:?}", metadata.created());
222 /// #
223 /// # Ok(()) }) }
224 /// ```
225 pub fn created(&self) -> io::Result<SystemTime> {
226 unreachable!("this impl only appears in the rendered docs")
227 }
228 }
229}
230