11.2. The stat and lstat Functions 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 the stat failed (usually because the file doesnt exist), or a 13-element list of numbers, most easily described using the following list of scalar variables: [] On a non-Unix system, stat and lstat, as well as the file tests, should return "the closest thing available." For example, a system that doesnt have user IDs (that is, a system that has just one "user," in the Unix sense) might return zero for the user and group IDs as if the only user is the system administrator. If stat or lstat fails, it will return an empty list. If the system call underlying a file test fails (or isn't available on the given system), that test will generally return undef. See the perlport manpage for the latest about what to expect on different systems.
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 the stat(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 command ls -l to 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 number 0755 in 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. [*] The first character in that string isn't a permission bit. It indicates the type of entry: a hyphen for an ordinary file, d for directory, or l for symbolic link, among others. The ls command determines this from the other bits past the least significant nine.
- $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 always 2 or more for directories and (usually) 1 for files. You'll see more about this when we talk about creating links to files in Chapter 12. In the listing from ls -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 -s file 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 than stat (which returns the same information in the same order). If the operand isn't a symbolic link, lstat returns the same things that stat would. Like the file tests, the operand of stat or lstat defaults to $_, meaning the underlying stat system call will be performed on the file named by the scalar variable $_. |
