The stat and lstat Functions - Perl

Though these file tests are fine for testing various attributes regarding a particular file or filehandle, they don’t tell the whole story. For example, there’s no file test that returns the number of links to a file or the owner’s user ID (uid). To get at the remaining information about a file, call the stat function, which returns pretty much everything that the stat Unix system call returns (and more than you want to know).† The operand to stat is a filehandle or an expression that evaluates to a filename. The return value is either the empty list indicating that thestatfailed (usually because the file doesn’t exist), or a 13-element list of numbers, most easily described using the following list of scalar variables:

  my($dev, $ino, $mode, $nlink, $uid, $gid, $rdev,
    $size, $atime, $mtime, $ctime, $blksize, $blocks)
      = stat($filename);

The names here refer to the parts of the stat structure, described in detail in thestat(2)manpage. You should look there for the detailed descriptions. Here’s a quick summary of the important ones:

$dev and $ino

The device number and inode number of the file. Together, they make up a “license plate” for the file. Even if it has more than one name (hard link), the combination of device and inode numbers will be unique.

$mode

The set of permission bits for the file and some other bits. If you’ve ever used the Unix commandls -lto get a detailed (long) file listing, you’ll see that each line of output starts with something like-rwxr-xr-x. The nine letters and hyphens of file permissions* correspond to the nine least significant bits of$mode, which would give the octal number0755in this case. The other bits, beyond the lowest nine, indicate other details about the file. If you need to work with the mode, you’ll want to use the bitwise operators covered later in this chapter.

$nlink

The number of (hard) links to the file or directory. This is the number of true names that the item has. This number is always2or more for directories and (usually)1for files. You’ll see more about this when we talk about creating links to files in Chapter 12. In the listing fromls -l, this is the number just after the permission bits string.

$uid and $gid

The numeric user ID and group ID showing the file’s ownership.

$size

The size in bytes, as returned by the-sfile test.

$atime, $mtime, and $ctime

The three timestamps, but here they’re represented in the system’s timestamp format: a 32-bit number telling how many seconds have passed since the Epoch, which is an arbitrary starting point for measuring system time. On Unix systems and some others, the Epoch is the beginning of 1970 at midnight Universal Time, but the Epoch is different on some machines. There’s more information later in this chapter on turning that timestamp number into something useful.

Invoking stat on the name of a symbolic link returns information on what the symbolic link points at and not information about the symbolic link itself unless the link happens to be pointing at nothing currently accessible. If you need the (mostly useless) information about the symbolic link itself, use lstat rather thanstat(which returns the same information in the same order). If the operand isn’t a symbolic link,lstatreturns the same things thatstat would.

Like the file tests, the operand ofstatorlstatdefaults to$_, meaning the underlying stat system call will be performed on the file named by the scalar variable$_.