1use crate::fs::asyncify;
2
3use std::fs::Metadata;
4use std::io;
5use 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/// ```
43pub async fn metadata(path: impl AsRef<Path>) -> io::Result<Metadata> {
44 let path: PathBuf = path.as_ref().to_owned();
45 asyncify(|| std::fs::metadata(path)).await
46}
47