Rust Standard Library (std::fs): Getting File Metadata With Code Examples

In Rust, the standard library (std::fs) provides the Metadata structure, which gives programmers Metadata about a file, such as its permissions, size, times, file type, block information, etc. In addition, the Metadata structure contains a plethora of implementations for platform-specific behavior and fields that include functions for Linux, Unix, MacOS, and Windows. In this blog post, I will highlight Rust examples of the various functions and implementations provided by the Rust standard library.

You can find the complete code examples across MacOs, Linux, Unix, and Windows on GitHub.

Importing the Rust Standard Library (std::fs)

To start interacting with the Rust Metadata structure and return information about a file, we must first import the Rust standard library with the following declaration.

Importing Platform-Specific Behaviour for Metadata

To access platform-specific behaviors, we must also import the MetadataExt implementations for the Metadata struct.

Importing fs::MetadataExt for Linux 

We can import the MetadataExt implementations for the Metadata struct using a Linux machine.

Importing fs::MetadataExt for Mac 

Using a MacOS machine, we can import the MetadataExt implementations for the Metadata struct.

Importing fs::MetadataExt for Unix 

If we are using a Unix machine, we can import the MetadataExt implementations for the Metadata struct.

Importing fs::MetadataExt for Windows 

We can import the MetadataExt implementations for the Metadata struct using a Microsoft Windows machine.

Setting an Example File Variable

Next, assign a file to a Rust variable using the const keyword and a local file.

Exploring the Rust Metadata Structure

In the following section, we will look deeper into the Metadata structure and the implementations and functions available to the programmer. First, let's query the file system to get information about our file using the std::fs::metadata() function.

Defining a Variable to Hold Our Metadata Struct Object

After we have a local file variable, let's pass this variable to the std::fs::metadata() function, which will store the file Metadata result object. The std::fs::metadata() function will get information about a file given a path and query the file system for us.

Rust File Metadata: Platform Agnostic Implementations

These implementations are platform agnostic and can be used freely across linux, unix, windows, and macos platforms.

Rust Metadata: How do I get the file type?

If we want to get a file object's file type, we can pass the file_type() function to the Metadata object. This method returns a FileType object.

Rust Metadata: How do I check if a file is a directory?

If you want to check if the file object is a directory, we can pass the is_dir() method to the Metadata object, which returns a boolean value on whether this file is a directory.

Rust Metadata: How do I check if a file is a file?

If you want to check if the file object is a regular file, we can pass the is_file() method to the Metadata object, which returns a boolean value on whether this file is a standard file.

Rust Metadata: How do I check if a file is a symbolic link?

If you want to check if the file object is a symbolic link, we can pass the is_symlink() method to the Metadata object, which returns a boolean value on whether this file is a symlink.

Rust Metadata: How do I get the byte length of a file?

If you want to get the length of a file in bytes, we can pass the len() function to the Metadata object, which returns a 64-bit unsigned integer (u64) type.

Rust Metadata: How do I get the permissions of a file?

If you want to get the permissions of a file, you can pass the permissions() function to the Metadata object. This function returns a Permissions structure object representing the file permissions.

Rust Metadata: How do I get the last modification time of a file?

If you want to get the last modification time of a file, you can pass the modified() function to the Metadata object. This function returns a Result object containing the SystemTime of last modification.

On Unix systems, the return value will be that of mtime vs. the ftLastWriteTime on Windows systems.

Rust Metadata: How do I get the last accessed time of a file?

If you want to get the last access time of a file, you can pass the accessed() function to the Metadata object. This function returns a Result object containing the SystemTime of last access.

On Unix systems, the return value will be that of atime vs. the ftLastAccessTime on Windows systems.

Rust Metadata: How do I get the creation time of a file?

You can pass the created() function to the Metadata object to get the file creation time. This function returns a Result object containing the SystemTime of creation.

On Unix systems, the returned value will be that of btime on the Linux kernel from 4.11, the birthtime field on other Unix systems, and the ftCreationTime field on Windows systems.

Rust Metadata: How do I clone a Metadata object?

We can use the clone() trait implementation to clone a Metadata structure.

Rust Metadata: How do I clone from a Metadata object?

Sometimes, cloning from an existing Metadata object may be a more memory-efficient operation. To clone from a current Metadata object, we can use the clone_from() trait implementation by passing a reference to an object we want to clone from.

Rust File MetadataExt: Linux Functions & Trait Implementations Code Examples

In the following examples, we will explore the Linux implementations and methods the Rust Metadata object provides to see what helpful information the file system queries for us. 

Rust Linux MetadataExt: How do I get the device ID where a file resides?

To get the device ID on which the file object resides, we can pass the st_dev() function, which will return a u64 ID value.

Rust File MetadataExt: How do I get the inode number of a file?

What is an inode number? An inode number is a Linux and Unix-like data structure that keeps track of all the files and directories on the system. To get the inode value of a file object, we can pass the st_ino() function, which will return a u64 inode number.

Rust File MetadataExt: How do I get a file's file type and mode?

To return a file object's file type and mode, we can pass the st_mode() function to the Metadata object, which returns a u32 value.

Rust File MetadataExt: How do I get the hard links to a file?

To get the number of hard links to a file in Rust, we can pass the st_nlink() to the Metadata object, which returns the number of hard links as a u64 value. 

Rust File MetadataExt: How do I get the user ID of the file owner?

To return the user ID of the file owner, we can pass the st_uid() function to the file, which returns a u32 user ID value.

Rust File MetadataExt: How do I get the group ID of the file owner?

To return the group ID of the file owner, we can pass the st_gid() function to the file, which returns a u32 group ID value.

Rust File MetadataExt: How do I get the device ID of a special file?

To return the device ID of a special file object, we can pass the st_rdev() function to the Metadata object, which returns a u64 ID value.

Rust File MetadataExt: How do I get the size of a file in bytes?

To get the size of a file in bytes, we can pass the st_size() function to the Metadata object, which returns a u64 byte size value.

Rust File MetadataExt: How do I get the last access time of a file since Unix Epoch?

To get the last access time since the Unix Epoch of a file, we can pass the st_atime() function to the Metadata object, which returns a 64-bit signed integer type (i64) value.

Rust File MetadataExt: How do I get the last access time of a file in nanoseconds since Unix Epoch?

To get the last access time in nanoseconds since the Unix Epoch of a file, we can pass the st_atime_nsec() function to the Metadata object, which returns a 64-bit signed integer type (i64) value representing the last access time in nanoseconds since Unix Epoch (st_atime).

Rust File MetadataExt: How do I get the last modified time of a file since Unix Epoch?

To get the last modified time since the Unix Epoch of a file, we can pass the st_mtime() function to the Metadata object, which returns a 64-bit signed integer type (i64) value.

Rust File MetadataExt: How do I get the last modified time of a file in nanoseconds since Unix Epoch?

To get the last modified time in nanoseconds since the Unix Epoch of a file, we can pass the st_mtime_nsec() function to the Metadata object, which returns a 64-bit signed integer type (i64) value representing the last modified time in nanoseconds since Unix Epoch (st_atime).

Rust File MetadataExt: How do I get a file's last status change time since Unix Epoch?

To get the last status change time of a file in seconds, we can pass the st_ctime() function to the Metadata object, which will return an i64 value of seconds since the Unix Epoch.

Rust File MetadataExt: How do I get a file's last status change time since Unix Epoch in nanoseconds?

To get the last status change time of a file in nanoseconds, we can pass the st_ctime_nsec() function to the Metadata object, which will return an i64 value of nanoseconds since Unix Epoch (st_ctime).

Rust File MetadataExt: How to get the preferred block size for efficient IO operations?

To return the preferred block size for efficient IO operation, we can pass the st_blksize() function, which returns a u64 value.

Rust File MetadataExt: How do you get the number of blocks allocated to a file?

To get the number of blocks allocated to a file in 512-byte units, we can pass the st_block() function to the Metadata object, which returns a u64 number of blocks value.

Rust File MetadataExt: Windows Functions & Trait Implementations Code Examples

We will explore Microsoft Windows platform-specific functions and trait implementations in these examples. 

Rust Windows MetadataExt: How to get the file attributes field?

To get the dwFileAttributes field of a file, we can use the Windows-specific extension file_attributes() function, which returns a u32 value.

Rust Windows MetadataExt: How to get the creation time field of a file?

To get the ftCreationTime field of a file, we can use the Windows-specific extension creation_time() function, which returns a u64 value denoting the creation time.

Rust Windows MetadataExt: How to get a file's last access time field?

To get the ftLastAccessTime field, we can use the last_access_time() method, which returns a u64 value denoting the last access time.

Rust Windows MetadataExt: How to get a file's last write time field?

To get the ftLastWriteTime field, we can use the last_write_time() method, which returns a u64 value denoting the last write time.

Rust Windows MetadataExt: How to get the file size field of a file?

To get the nFileSize{High, Low} fields, we can use the file_size() method, which returns a u64 value denoting the file size.

Rust Windows MetadataExt: How to get the volume's serial number field containing a file?

To get the dwVolumeSerialNumber field, we can use the volume_serial_number() method, which returns an Option<u32> type containing a u32 value.

Rust Windows MetadataExt: How to get the number of links field to a file?

To get the nNumberOfLinks field, we can use the number_of_links() method, which returns an Option<u32> type containing a u32 value.

Rust Windows MetadataExt: How to get the file index identifiers field?

To get the nFileIndex{Low, High} fields, we can use the file_index() method, which returns an Option<u64> type containing a u64 value.

Rust File MetadataExt: Unix Functions & Trait Implementations Code Examples

In the following examples, we will explore the Unix implementations and methods that the Rust Metadata object provides to see what helpful information the file system queries for us. 

Rust Unix MetadataExt: How do I get the ID of the device that contains the file?

To get the ID of the device, we can pass the dev() method to the Metadata object, which will return a u64 device ID number.

Rust Unix MetadataExt: How do I get the inode number of a file?

To get the inode number of a file, we can pass the ino() method to the Metadata object, which will return a u64 inode number.

Rust Unix MetadataExt: How do I get the mode of a file?

To get a file's mode (permissions), we can pass the mode() method to the Metadata object, which will return a u64 mode number.

Rust Unix MetadataExt: How do I get the number of hard links pointing to a file?

To get the number of hard links to a file, we can pass the nlink() method to the Metadata object, which will return a u64 number of links.

Rust Unix MetadataExt: How do I get the user ID of the file owner?

To get the user ID of the owner of a file, we can pass the uid() method to the Metadata object, which will return a u64 ID number of the file owner.

Rust Unix MetadataExt: How do I get the group ID of the file owner?

To get the group ID of the owner of a file, we can pass the gid() method to the Metadata object, which will return a u64 ID number of the file owner.

Rust Unix MetadataExt: How do I get the byte size of a file?

To get the size of a file in bytes, we can pass the size() method to the Metadata object, which will return a u64 number representing the file's total size in bytes.

Rust Unix MetadataExt: How do I get the last access time of a file?

To get the last access time of a file, we can pass the time () method to the Metadata object, which will return a u64 number of the access time in seconds since the Unix Epoch.

Rust Unix MetadataExt: How do I get the last access time in nanoseconds of a file?

To get the last access time of a file in nanoseconds, we can pass the atime_nsec() method to the Metadata object, which will return a u64 number representing access time in nanoseconds since Unix Epoch.

Rust Unix MetadataExt: How do I get the modified time of a file?

To get the last modified time of a file, we can pass the mtime() method to the Metadata object, which will return a u64 number of the modified time in seconds since the Unix Epoch.

Rust Unix MetadataExt: How do I get the modified time in nanoseconds of a file?

To get the last modified time of a file in nanoseconds, we can pass the mtime_nsec() method to the Metadata object, which will return a u64 number representing the last modified value in nanoseconds since Unix Epoch.

Rust Unix MetadataExt: How do I get a file's last status change time?

To get a file's last status change time, we can pass the ctime() method to the Metadata object, which will return a u64 number, the previous status change time in seconds since the Unix Epoch.

Rust Unix MetadataExt: How do I get the last status change time in nanoseconds of a file?

To get a file's last status change time in nanoseconds, we can pass the ctime_nsec() method to the Metadata object, which will return a u64 number representing the change time value in nanoseconds since Unix Epoch.

Rust Unix MetadataExt: How do I get a file's block size for filesystem I/O?

To get the block size of a file for efficient filesystem IO, we can pass the blksize() method to the Metadata object, which will return a u64 value representing the block size.

Rust Unix MetadataExt: How do I get the number of blocks allocated to a file?

To get the number of blocks allocated to a file (512-byte units), we can pass the block() method to the Metadata object, which will return a u64 value representing the number of blocks.

Rust Metadata Structure Conclusion

To summarize, programmers can access detailed file metadata information by exploring Rust's standard library (std::fs) and its Metadata structure. Rust provides various functions and implementations tailored for different platforms, such as Microsoft Windows, macOS, Unix, and Linux, enabling developers to create powerful, platform-independent applications. This blog post has highlighted the wealth of information and functionalities the Metadata structure offers, including permissions, file size, and other platform-specific details.

If you like a full list of these examples covered here you can find code examples for MacOs, Linux, Unix, and Windows on GitHub.

If you have any questions or comments feel free to reach out!

Previous
Previous

Rust Metadata Extensions (std::os::linux::fs::MetadataExt) Trait for the Linux OS

Next
Next

CISA & NSA - Identity & Access Management (IAM) Vendor Challenges