How to get file modification time in Perl?

To get the modification time of a file in Perl, you typically use the stat function. This built-in function returns a list of status information about a file, such as device number, inode number, permission mode, number of links, user ID, group ID, file size, and importantly, various timestamps including access time, modification time, and inode change time.

Understanding stat and File Modification Time

stat returns a 13-element list. The file modification time (mtime) is the 9th element in this list, corresponding to index 9 when counting from zero:

• $mtime = (stat($filename))[9];

The value of $mtime is the epoch timestamp representing when the file was last modified. You can convert this to a readable format with localtime or gmtime.

Perl Sigils and Context

Perl scalars use $ sigils, so even though stat returns a list, to access the modification time you assign it to a scalar variable. This works because you're extracting one element from the list.

Runnable Example

use strict;
use warnings;

# Filename to check
my $filename = 'example.txt';

# Check if file exists
if (-e $filename) {
    # Get modification time (epoch seconds)
    my $mtime = (stat($filename))[9];
    
    # Convert epoch to human-readable time
    my $readable_mtime = localtime($mtime);
    
    print "File: $filename\n";
    print "Last modified: $readable_mtime\n";
} else {
    print "File '$filename' does not exist.\n";
}

This script does the following:

• Checks if the file exists with the -e file test operator.
• Uses stat to get the modification time.
• Converts the epoch modification time to a local human-readable string using localtime.

Common Pitfalls and Gotchas

• File existence: Always check if the file exists before calling stat, as calling stat on a non-existent file returns an empty list and can cause warnings.
• Context matters: stat returns a list, so be sure to use list context (e.g., (stat($filename))[9]) to get the modification time correctly.
• Time zones: The numeric timestamp from stat is in epoch seconds UTC. Functions like localtime and gmtime convert to local or GMT time respectively.
• Portability: stat is cross-platform, but the timestamp accuracy might vary between filesystems and operating systems.

Additional Notes

From Perl 5.10 onwards, you can also use the -M file test operator to get the age of a file (time since last modification) in days. For example:

my $age_days = -M $filename;
print "File is $age_days days old\n";

However, -M gives you age, not the absolute modification time, so stat remains the method of choice when the exact modification time is needed.

In summary, stat is the idiomatic and flexible way to retrieve file modification times in Perl.