1 | use crate::fs::asyncify; |
2 | |
3 | use std::fs::Metadata; |
4 | use std::io; |
5 | use std::path::Path; |
6 | |
7 | /// Given a path, queries the file system to get information about a file, |
8 | /// directory, etc. |
9 | /// |
10 | /// This is an async version of [`std::fs::metadata`]. |
11 | /// |
12 | /// This function will traverse symbolic links to query information about the |
13 | /// destination file. |
14 | /// |
15 | /// # Platform-specific behavior |
16 | /// |
17 | /// This function currently corresponds to the `stat` function on Unix and the |
18 | /// `GetFileAttributesEx` function on Windows. Note that, this [may change in |
19 | /// the future][changes]. |
20 | /// |
21 | /// [changes]: https://doc.rust-lang.org/std/io/index.html#platform-specific-behavior |
22 | /// |
23 | /// # Errors |
24 | /// |
25 | /// This function will return an error in the following situations, but is not |
26 | /// limited to just these cases: |
27 | /// |
28 | /// * The user lacks permissions to perform `metadata` call on `path`. |
29 | /// * `path` does not exist. |
30 | /// |
31 | /// # Examples |
32 | /// |
33 | /// ```rust,no_run |
34 | /// use tokio::fs; |
35 | /// |
36 | /// #[tokio::main] |
37 | /// async fn main() -> std::io::Result<()> { |
38 | /// let attr = fs::metadata("/some/file/path.txt" ).await?; |
39 | /// // inspect attr ... |
40 | /// Ok(()) |
41 | /// } |
42 | /// ``` |
43 | pub async fn metadata(path: impl AsRef<Path>) -> io::Result<Metadata> { |
44 | let path = path.as_ref().to_owned(); |
45 | asyncify(|| std::fs::metadata(path)).await |
46 | } |
47 | |