Everything You Ever Wanted to Know About THAT File

To find out, in excruciating detail, everything you might want to know about a file, you can use Perl's stat function. The stat function originated in Unix, and the return values differ slightly between Unix and non-Unix systems. The syntax for stat is as follows :

 stat  filehandle  ; stat  filename  ; 

The stat function can retrieve information either about an open filehandle or about a particular file. Under any operating system, stat returns a 13-element list describing the attributes of the file. The actual values in the list differ slightly depending on which operating system you're running because some operating systems include features that others do not implement. Table 10.3 shows what each element in stat 's return value stands for.

Table 10.3. Return Values from stat

Index	Name	Unix	Windows
	dev	Device number	Drive number (C: is usually 2, D: is usually 3, and so on)
1	ino	Inode number	Zero, always
2	mode	File's mode (permissions)	Not relevant
3	nlink	Number of links	Usually 0; Windows NT; file system might allow links
4	uid	User ID (UID) of the owner	Zero, always
5	gid	Group ID (GID) of the owner	Zero, always
6	rdev	Special file info	Drive number (again)
7	size	Size of file in bytes	Size of file in bytes
8	atime	Time of last access	Time of last access
9	mtime	Time of last modification	Time of last modification
10	ctime	Inode change time	File creation time
11	blksz	Disk block size	Zero, always
12	blocks	Number of blocks in file	Zero, always

Many of the values in Table 10.3 you will probably never use, but they are presented for completeness. For the more obscure values ” especially in the Unix return values ”you might want to consult your operating system's reference manual.

The following is an example of using stat on a file:

 @stuff=stat "myfile"; 

Normally, the returned values from stat are copied into an assignable list of scalars for clarity:

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

To print the permissions for a file in the three-digit form described in the section "A Crash Course in File Permissions," you use this bit of code, where @stuff contains the permissions:

 printf "%04o\n", $mode&0777; 

The preceding snippet contains elements you might not understand. That's okay; some of it has not been presented to you yet. The permissions as they're retrieved by stat ”in $mode in this case ”contain lots of "extra" information. The &0777 strips out just the portion of the information you're interested in here. Finally, %o is a printf format that prints numbers in octal ”the 0 “7 form in which Unix expects permissions to be formatted.

By the Way

Octal is a base-8 representation of numbers. It's used in Unix for largely historical reasons, but it came along with Perl anyway. If you're still lost, don't panic. Just use the printf shown previously if you ever need to display a file's permissions. It doesn't happen that often; don't worry if you don't quite get that part.

The three time stamps mentioned in Table 10.3 ”access, modification, and change (or create) time ”are stored in a peculiar format. The time stamps are stored as the number of seconds from midnight, January 1, 1970, Greenwich mean time. To print them in a usable format, you use the localtime function, as follows:

 print scalar localtime($mtime); 

This function prints the modification time of the file in a format similar to Sat Jul 3 23:35:11 EDT 1999 . The access time is the time that the file was last read (or opened for reading). The modification time is the time when the file was last written to. Under Unix, the "change" time is the time when the information about the file ”the ownership, number of links, permissions, and so on ”was changed; it is not the creation time of the file but often happens to be by coincidence . Under Microsoft Windows, the ctime field actually stores the time the file was created.

Sometimes you might be interested in retrieving just one value from the list returned by stat . To do so, you can wrap the entire stat function in parentheses and use subscripts to slice out the values you want from it:

 print "The file has", (stat("file"))[7], " bytes of data";