std::fs::Metadata - Rust
Description: API documentation for the Rust `Metadata` struct in crate `std`.
Keywords: rust, rustlang, rust-lang, Metadata

# 1.0.0[−][src]Struct std::fs::Metadata

    pub struct Metadata(_);

Metadata information about a file.

This structure is returned from the `metadata` or `symlink_metadata` function or method and represents known metadata about a file such as its permissions, size, modification times, etc.

## Implementations

### `impl Metadata`[src]

#### `pub fn file_type(&self) -> FileType`1.1.0[src]

Returns the file type for this metadata.

# Examples

    fn main() -> std::io::Result<()> {
        use std::fs;

        let metadata = fs::metadata("foo.txt")?;

        println!("{:?}", metadata.file_type());
        Ok(())
    }

Run

#### `pub fn is_dir(&self) -> bool`[src]

Returns `true` if this metadata is for a directory. The result is mutually exclusive to the result of `Metadata::is_file`, and will be false for symlink metadata obtained from `symlink_metadata`.

# Examples

    fn main() -> std::io::Result<()> {
        use std::fs;

        let metadata = fs::metadata("foo.txt")?;

        assert!(!metadata.is_dir());
        Ok(())
    }

Run

#### `pub fn is_file(&self) -> bool`[src]

Returns `true` if this metadata is for a regular file. The result is mutually exclusive to the result of `Metadata::is_dir`, and will be false for symlink metadata obtained from `symlink_metadata`.

When the goal is simply to read from (or write to) the source, the most reliable way to test the source can be read (or written to) is to open it. Only using `is_file` can break workflows like `diff <( prog_a )` on a Unix-like system for example. See `File::open` or `OpenOptions::open` for more information.

# Examples

    use std::fs;

    fn main() -> std::io::Result<()> {
        let metadata = fs::metadata("foo.txt")?;

        assert!(metadata.is_file());
        Ok(())
    }

Run

#### `pub fn len(&self) -> u64`[src]

Returns the size of the file, in bytes, this metadata is for.

# Examples

    use std::fs;

    fn main() -> std::io::Result<()> {
        let metadata = fs::metadata("foo.txt")?;

        assert_eq!(0, metadata.len());
        Ok(())
    }

Run

#### `pub fn permissions(&self) -> Permissions`[src]

Returns the permissions of the file this metadata is for.

# Examples

    use std::fs;

    fn main() -> std::io::Result<()> {
        let metadata = fs::metadata("foo.txt")?;

        assert!(!metadata.permissions().readonly());
        Ok(())
    }

Run

#### `pub fn modified(&self) -> Result<SystemTime>`1.10.0[src]

Returns the last modification time listed in this metadata.

The returned value corresponds to the `mtime` field of `stat` on Unix platforms and the `ftLastWriteTime` field on Windows platforms.

# Errors

This field may not be available on all platforms, and will return an `Err` on platforms where it is not available.

# Examples

    use std::fs;

    fn main() -> std::io::Result<()> {
        let metadata = fs::metadata("foo.txt")?;

        if let Ok(time) = metadata.modified() {
            println!("{:?}", time);
        } else {
            println!("Not supported on this platform");
        }
        Ok(())
    }

Run

#### `pub fn accessed(&self) -> Result<SystemTime>`1.10.0[src]

Returns the last access time of this metadata.

The returned value corresponds to the `atime` field of `stat` on Unix platforms and the `ftLastAccessTime` field on Windows platforms.

Note that not all platforms will keep this field update in a file's metadata, for example Windows has an option to disable updating this time when files are accessed and Linux similarly has `noatime`.

# Errors

This field may not be available on all platforms, and will return an `Err` on platforms where it is not available.

# Examples

    use std::fs;

    fn main() -> std::io::Result<()> {
        let metadata = fs::metadata("foo.txt")?;

        if let Ok(time) = metadata.accessed() {
            println!("{:?}", time);
        } else {
            println!("Not supported on this platform");
        }
        Ok(())
    }

Run

#### `pub fn created(&self) -> Result<SystemTime>`1.10.0[src]

Returns the creation time listed in this metadata.

The returned value corresponds to the `btime` field of `statx` on Linux kernel starting from to 4.11, the `birthtime` field of `stat` on other Unix platforms, and the `ftCreationTime` field on Windows platforms.

# Errors

This field may not be available on all platforms, and will return an `Err` on platforms or filesystems where it is not available.

# Examples

    use std::fs;

    fn main() -> std::io::Result<()> {
        let metadata = fs::metadata("foo.txt")?;

        if let Ok(time) = metadata.created() {
            println!("{:?}", time);
        } else {
            println!("Not supported on this platform or filesystem");
        }
        Ok(())
    }

Run

## Trait Implementations

### `impl Clone for Metadata`[src]

#### `fn clone(&self) -> Metadata`[src]

Returns a copy of the value. Read more

#### `fn clone_from(&mut self, source: &Self)`[src]

Performs copy-assignment from `source`. Read more

### `impl Debug for Metadata` 1.16.0[src]

#### `fn fmt(&self, f: &mut Formatter<'_>) -> Result`[src]

Formats the value using the given formatter. Read more

### `impl MetadataExt for Metadata` 1.1.0[src]

#### `fn as_raw_stat(&self) -> &stat`[src]

👎 Deprecated since 1.8.0:

other methods of this trait are now preferred

This is supported on Linux only.

Gain a reference to the underlying `stat` structure which contains the raw information returned by the OS. Read more

#### `fn st_dev(&self) -> u64`[src]

This is supported on Linux only.

Returns the device ID on which this file resides. Read more

#### `fn st_ino(&self) -> u64`[src]

This is supported on Linux only.

Returns the inode number. Read more

#### `fn st_mode(&self) -> u32`[src]

This is supported on Linux only.

Returns the file type and mode. Read more

#### `fn st_nlink(&self) -> u64`[src]

This is supported on Linux only.

Returns the number of hard links to file. Read more

#### `fn st_uid(&self) -> u32`[src]

This is supported on Linux only.

Returns the user ID of the file owner. Read more

#### `fn st_gid(&self) -> u32`[src]

This is supported on Linux only.

Returns the group ID of the file owner. Read more

#### `fn st_rdev(&self) -> u64`[src]

This is supported on Linux only.

Returns the device ID that this file represents. Only relevant for special file. Read more

#### `fn st_size(&self) -> u64`[src]

This is supported on Linux only.

Returns the size of the file (if it is a regular file or a symbolic link) in bytes. Read more

#### `fn st_atime(&self) -> i64`[src]

This is supported on Linux only.

Returns the last access time of the file, in seconds since Unix Epoch. Read more

#### `fn st_atime_nsec(&self) -> i64`[src]

This is supported on Linux only.

Returns the last access time of the file, in nanoseconds since [`st_atime`]. Read more

#### `fn st_mtime(&self) -> i64`[src]

This is supported on Linux only.

Returns the last modification time of the file, in seconds since Unix Epoch. Read more

#### `fn st_mtime_nsec(&self) -> i64`[src]

This is supported on Linux only.

Returns the last modification time of the file, in nanoseconds since [`st_mtime`]. Read more

#### `fn st_ctime(&self) -> i64`[src]

This is supported on Linux only.

Returns the last status change time of the file, in seconds since Unix Epoch. Read more

#### `fn st_ctime_nsec(&self) -> i64`[src]

This is supported on Linux only.

Returns the last status change time of the file, in nanoseconds since [`st_ctime`]. Read more

#### `fn st_blksize(&self) -> u64`[src]

This is supported on Linux only.

Returns the "preferred" block size for efficient filesystem I/O. Read more

#### `fn st_blocks(&self) -> u64`[src]

This is supported on Linux only.

Returns the number of blocks allocated to the file, 512-byte units. Read more

### `impl MetadataExt for Metadata` 1.1.0[src]

#### `fn dev(&self) -> u64`[src]

This is supported on Unix only.

Returns the ID of the device containing the file. Read more

#### `fn ino(&self) -> u64`[src]

This is supported on Unix only.

Returns the inode number. Read more

#### `fn mode(&self) -> u32`[src]

This is supported on Unix only.

Returns the rights applied to this file. Read more

#### `fn nlink(&self) -> u64`[src]

This is supported on Unix only.

Returns the number of hard links pointing to this file. Read more

#### `fn uid(&self) -> u32`[src]

This is supported on Unix only.

Returns the user ID of the owner of this file. Read more

#### `fn gid(&self) -> u32`[src]

This is supported on Unix only.

Returns the group ID of the owner of this file. Read more

#### `fn rdev(&self) -> u64`[src]

This is supported on Unix only.

Returns the device ID of this file (if it is a special one). Read more

#### `fn size(&self) -> u64`[src]

This is supported on Unix only.

Returns the total size of this file in bytes. Read more

#### `fn atime(&self) -> i64`[src]

This is supported on Unix only.

Returns the last access time of the file, in seconds since Unix Epoch. Read more

#### `fn atime_nsec(&self) -> i64`[src]

This is supported on Unix only.

Returns the last access time of the file, in nanoseconds since [`atime`]. Read more

#### `fn mtime(&self) -> i64`[src]

This is supported on Unix only.

Returns the last modification time of the file, in seconds since Unix Epoch. Read more

#### `fn mtime_nsec(&self) -> i64`[src]

This is supported on Unix only.

Returns the last modification time of the file, in nanoseconds since [`mtime`]. Read more

#### `fn ctime(&self) -> i64`[src]

This is supported on Unix only.

Returns the last status change time of the file, in seconds since Unix Epoch. Read more

#### `fn ctime_nsec(&self) -> i64`[src]

This is supported on Unix only.

Returns the last status change time of the file, in nanoseconds since [`ctime`]. Read more

#### `fn blksize(&self) -> u64`[src]

This is supported on Unix only.

Returns the block size for filesystem I/O. Read more

#### `fn blocks(&self) -> u64`[src]

This is supported on Unix only.

Returns the number of blocks allocated to the file, in 512-byte units. Read more

### `impl MetadataExt for Metadata` 1.1.0[src]

#### `fn file_attributes(&self) -> u32`[src]

This is supported on Windows only.

Returns the value of the `dwFileAttributes` field of this metadata. Read more

#### `fn creation_time(&self) -> u64`[src]

This is supported on Windows only.

Returns the value of the `ftCreationTime` field of this metadata. Read more

#### `fn last_access_time(&self) -> u64`[src]

This is supported on Windows only.

Returns the value of the `ftLastAccessTime` field of this metadata. Read more

#### `fn last_write_time(&self) -> u64`[src]

This is supported on Windows only.

Returns the value of the `ftLastWriteTime` field of this metadata. Read more

#### `fn file_size(&self) -> u64`[src]

This is supported on Windows only.

Returns the value of the `nFileSize{High,Low}` fields of this metadata. Read more

#### `fn volume_serial_number(&self) -> Option<u32>`[src]

🔬 This is a nightly-only experimental API. (`windows_by_handle` #63010)
This is supported on Windows only.

Returns the value of the `dwVolumeSerialNumber` field of this metadata. Read more

#### `fn number_of_links(&self) -> Option<u32>`[src]

🔬 This is a nightly-only experimental API. (`windows_by_handle` #63010)
This is supported on Windows only.

Returns the value of the `nNumberOfLinks` field of this metadata. Read more

#### `fn file_index(&self) -> Option<u64>`[src]

🔬 This is a nightly-only experimental API. (`windows_by_handle` #63010)
This is supported on Windows only.

Returns the value of the `nFileIndex{Low,High}` fields of this metadata. Read more

## Auto Trait Implementations

### `impl RefUnwindSafe for Metadata`

### `impl Send for Metadata`

### `impl Sync for Metadata`

### `impl Unpin for Metadata`

### `impl UnwindSafe for Metadata`

## Blanket Implementations

### `impl<T> Any for T where
T: 'static + ?Sized,` [src]

#### `fn type_id(&self) -> TypeId`[src]

Gets the `TypeId` of `self`. Read more

### `impl<T> Borrow<T> for T where
T: ?Sized,` [src]

#### `fn borrow(&self) -> &Tⓘ

### Notable traits for &'_ mut I

`impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;impl<R: Read + ?Sized, '_> Read for &'_ mut Rimpl<W: Write + ?Sized, '_> Write for &'_ mut W`
`[src]

Immutably borrows from an owned value. Read more

### `impl<T> BorrowMut<T> for T where
T: ?Sized,` [src]

#### `fn borrow_mut(&mut self) -> &mut Tⓘ

### Notable traits for &'_ mut I

`impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;impl<R: Read + ?Sized, '_> Read for &'_ mut Rimpl<W: Write + ?Sized, '_> Write for &'_ mut W`
`[src]

Mutably borrows from an owned value. Read more

### `impl<T> From<T> for T`[src]

#### `fn from(t: T) -> T`[src]

Performs the conversion.

### `impl<T, U> Into<U> for T where
U: From<T>,` [src]

#### `fn into(self) -> U`[src]

Performs the conversion.

### `impl<T> ToOwned for T where
T: Clone,` [src]

#### `type Owned = T`

The resulting type after obtaining ownership.

#### `fn to_owned(&self) -> T`[src]

Creates owned data from borrowed data, usually by cloning. Read more

#### `fn clone_into(&self, target: &mut T)`[src]

🔬 This is a nightly-only experimental API. (`toowned_clone_into` #41263)

recently added

Uses borrowed data to replace owned data, usually by cloning. Read more

### `impl<T, U> TryFrom<U> for T where
U: Into<T>,` [src]

#### `type Error = Infallible`

The type returned in the event of a conversion error.

#### `fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>`[src]

Performs the conversion.

### `impl<T, U> TryInto<U> for T where
U: TryFrom<T>,` [src]

#### `type Error = <U as TryFrom<T>>::Error`

The type returned in the event of a conversion error.

#### `fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>`[src]

Performs the conversion.