Linux <span>stat</span> Command

<span>stat</span> is a powerful command-line tool in Linux systems used to display detailed information about files or file systems. It provides metadata about files, such as file size, permissions, timestamps, etc., making it an essential tool for system administrators, developers, and advanced users.

What is the <span>stat</span> Command?

<span>stat</span> is part of the GNU coreutils package and is typically pre-installed in most Linux distributions. It is used to retrieve and display metadata stored in the file inode, such as file owner, permissions, timestamps, and file type. Unlike commands like <span>ls</span> that provide summary information about file attributes, <span>stat</span> offers more granular information, making it ideal for scripting, debugging, and system analysis.

Why Use <span>stat</span>?

• Detailed Metadata: Access inode-level details, including access, modification, and metadata change times.
• Customizable Output: Supports formatted output to extract specific fields, making it easier for script processing.
• File System Information: Displays file system type and device information.
• Versatility: Suitable for various file types, including files, directories, symbolic links, etc.

Availability

<span>stat</span> command is available on Linux, macOS (with slight variations), and other Unix-like systems. This article mainly focuses on the common GNU version of <span>stat</span> on Linux systems.

Syntax and Basic Usage

<span>stat</span> command’s basic syntax is as follows:

stat [options]... file...

• Options: Flags used to modify the command’s behavior or output.
• File: One or more files or directories to check.

Basic Example

Assuming there is a file named <span>example.txt</span>, run the following command:

stat example.txt

Example output:

  File: example.txt  Size: 1024            Blocks: 8          IO Block: 4096   regular file Device: 803h/2051d        Inode: 123456      Links: 1Permissions: (0644/-rw-r--r--)  Uid: ( 1000/   user)   Gid: ( 1000/   user)Access: 2025-04-28 10:15:30.123456789 +0800Modify: 2025-04-27 15:20:45.987654321 +0800Change: 2025-04-27 15:20:45.987654321 +0800Birth: 2025-04-27 15:20:45.987654321 +0800

Output content analysis:

• File: File name.
• Size: File size (in bytes).
• Blocks: Number of allocated disk blocks.
• IO Block: File system block size.
• Device: Device number (in hexadecimal and decimal).
• Inode: Inode number.
• Links: Number of hard links.
• Permissions: File permissions (in octal and symbolic representation).
• Uid/Gid: User and group ID (including username and group name).
• Access/Modify/Change/Birth Time: Timestamps for last access, modification, metadata change, and file creation (if supported by the file system).
• Timezone: Timezone offset of the timestamps.

Main Options and Flags

<span>stat</span> command supports various options to control its behavior and output. Below are detailed descriptions of the main options:

General Options

• <span>-f</span>, <span>--file-system</span>: Display file system information instead of file metadata.
• <span>-L</span>, <span>--dereference</span>: Follow symbolic links and display metadata of the target file.
• <span>-c</span>, <span>--format=FORMAT</span>: Specify a custom output format (see Custom Output Format).
• <span>--printf=FORMAT</span>: Similar to <span>--format</span>, but supports parsing backslash escape characters (e.g., <span>\n</span> for newline).
• <span>-t</span>, <span>--terse</span>: Output in a concise single-line format, suitable for scripting.

Output Control

• <span>--cached=MODE</span>: Control the file attribute caching method (Linux specific). Possible values:<span>always</span>, <span>never</span>, <span>default</span>.
• <span>-Z</span>: Display SELinux security context (requires SELinux to be enabled).

Help and Version

• <span>-h</span>, <span>--help</span>: Display help information.
• <span>-V</span>, <span>--version</span>: Display command version.

Option Examples

1. View File System Information:

   stat -f /home

   Output:

     File: "/home"  ID: 803h Name Length: 255     Type: ext4Block Size: 4096       Fundamental Block Size: 4096Blocks: Total: 5242880    Free: 1234567    Available: 987654Inodes: Total: 1310720    Free: 987654

1. Concise Output:

   stat -t example.txt

   Output:

   example.txt 1024 8 81a4 1000 1000 803 123456 1 0 0 1619777730 1619695245 1619695245 1619695245

Custom Output Format

<span>stat</span> command’s <span>--format</span> and <span>--printf</span> options allow users to customize the output content and extract specific fields. This feature is particularly useful in scripts. Below are commonly used formatting placeholders:

Common Format Placeholders

• <span>%a</span>: Octal permissions (e.g., <span>0644</span>).
• <span>%A</span>: Symbolic permissions (e.g., <span>-rw-r--r--</span>).
• <span>%s</span>: File size (in bytes).
• <span>%u</span>: User ID.
• <span>%U</span>: Username.
• <span>%g</span>: Group ID.
• <span>%G</span>: Group name.
• <span>%y</span>: Modification time (human-readable format).
• <span>%Y</span>: Modification time (Unix timestamp).
• <span>%n</span>: File name.
• <span>%F</span>: File type (e.g., <span>regular file</span>, <span>directory</span>).

Examples

1. Output Only File Name and Size:

   stat --format="%n %s" example.txt

   Output:

   example.txt 1024

2. Format Timestamp:

   stat --format="File: %n, Modified: %y" example.txt

   Output:

   File: example.txt, Modified: 2025-04-27 15:20:45.987654321 +0800

3. Use <span>--printf</span> to Add Newline:

   stat --printf="Name: %n\nSize: %s bytes\n" example.txt

   Output:

   Name: example.txtSize: 1024 bytes

Practical Examples

Here are some common <span>stat</span> use cases, covering tasks from basic to complex.

Example 1: Check File Permissions

stat --format="Permissions: %A (%a)" example.txt

Output:

Permissions: -rw-r--r-- (0644)

Example 2: Batch Check Multiple Files

stat --format="%n: %s bytes" *.txt

Output:

file1.txt: 1024 bytesfile2.txt: 2048 bytes

Example 3: Check Symbolic Links

For symbolic links, by default, <span>stat</span> displays metadata of the link itself:

stat link_to_example.txt

Use <span>-L</span> to follow the link:

stat -L link_to_example.txt

Example 4: Monitor File Timestamps

Check the access and modification times of a file:

stat --format="Access: %x\nModify: %y" example.txt

Output:

Access: 2025-04-28 10:15:30.123456789 +0800Modify: 2025-04-27 15:20:45.987654321 +0800

Example 5: File System Capacity Check

View file system information for the mount point <span>/</span>:

stat -f /

Output:

  File: "/"  ID: 802h Name Length: 255     Type: ext4Block Size: 4096       Fundamental Block Size: 4096Blocks: Total: 10485760    Free: 5432109    Available: 5123456Inodes: Total: 2621440    Free: 1987654

Advanced Usage

<span>stat</span> command excels in advanced scenarios, especially in script automation, system monitoring, and debugging. Here are some advanced use cases.

Advanced Example 1: Extract Specific Fields in Scripts

In a Bash script, extract the modification time of a file and compare it:

#!/bin/bashfile="example.txt"mod_time=$(stat --format="%Y" "$file")current_time=$(date +%s)if [ $((current_time - mod_time)) -gt 86400 ]; then  echo "$file was modified more than 24 hours ago."else  echo "$file was modified recently."fi

Advanced Example 2: Monitor File Changes

Use <span>stat</span> to check if a file has been modified (by comparing Inode or modification time):

#!/bin/bashfile="example.txt"last_inode=$(stat --format="%i" "$file")last_mtime=$(stat --format="%Y" "$file")while true; do  current_inode=$(stat --format="%i" "$file")  current_mtime=$(stat --format="%Y" "$file")  if [ "$current_inode" != "$last_inode" ] || [ "$current_mtime" != "$last_mtime" ]; then    echo "$file has changed!"    last_inode="$current_inode"    last_mtime="$current_mtime"  fi  sleep 5done

Advanced Example 3: Batch Process Files

Find all <span>.log</span> files and extract their sizes and modification times:

find /var/log -type f -name "*.log" -exec stat --format="%n %s %y" {} \;

Output:

/var/log/syslog 524288 2025-04-28 09:00:00.000000000 +0800/var/log/auth.log 1048576 2025-04-28 08:45:00.000000000 +0800

Advanced Example 4: SELinux Context

On systems with SELinux enabled, view the SELinux context of a file:

stat -Z example.txt

Output:

  File: example.txt  Size: 1024            Blocks: 8          IO Block: 4096   regular file Device: 803h/2051d        Inode: 123456      Links: 1Permissions: (0644/-rw-r--r--)  Uid: ( 1000/   user)   Gid: ( 1000/   user)Context: unconfined_u:object_r:user_home_t:s0Access: 2025-04-28 10:15:30.123456789 +0800Modify: 2025-04-27 15:20:45.987654321 +0800Change: 2025-04-27 15:20:45.987654321 +0800Birth: 2025-04-27 15:20:45.987654321 +0800

Comparison with Other Commands

<span>stat</span> command overlaps in functionality with other tools (like <span>ls</span>, <span>find</span>, and <span>getfacl</span>), but also has unique advantages.

Comparison with <span>ls</span>

• <span>ls</span>: Provides a list of files and basic attributes (like permissions, size, modification time), suitable for quick viewing.

• <span>stat</span>: Provides more detailed metadata (like Inode, device number, creation time), supports custom output, suitable for scripting and in-depth analysis.

• Example:

  ls -l example.txtstat example.txt

  <span>ls</span> output is concise, while <span>stat</span> provides more fields.

Comparison with <span>find</span>

• <span>find</span>: Used to search for files and perform actions, supports filtering based on time, permissions, etc.

• <span>stat</span>: Focuses on detailed metadata viewing of a single file.

• Example:

  find . -name "*.txt" -exec stat --format="%n %s" {} \;

  Combining both can achieve complex tasks.

Comparison with <span>getfacl</span>

• <span>getfacl</span>: Displays the access control list (ACL) of a file.

• <span>stat</span>: Displays basic permissions and SELinux context but does not deeply support ACL.

• Example:

  getfacl example.txtstat -Z example.txt

Common Issues and Troubleshooting

Issue 1:<span>stat</span> Output Missing Creation Time

Reason: Some file systems (like ext3) do not support creation time (<span>Birth</span> field). Solution: Check the file system type (<span>stat -f</span>), or use a file system that supports creation time (like ext4, XFS).

Issue 2: Symbolic Links Not Resolved Correctly

Reason: By default, <span>stat</span> displays metadata of the symbolic link itself. Solution: Use the <span>-L</span> option to follow the link:

stat -L link_to_example.txt

Issue 3: Formatting Output Error

Reason: An invalid placeholder was used in the formatting string. Solution: Check the list of formatting placeholders in <span>man stat</span> to ensure correct usage.

Issue 4: Insufficient Permissions

Reason: The user does not have permission to access the target file or directory. Solution: Run the command with <span>sudo</span> or appropriate permissions:

sudo stat /root/secret.txt

Conclusion

<span>stat</span> command is a powerful and flexible tool in Linux systems that provides detailed metadata and file system information. With its rich options and customizable output features, <span>stat</span> plays a significant role in file management, scripting, and system debugging.