File Test Operators

Perl has a set of file test operators that let you get particular information about files. They all take the form of -X, where the X represents the particular test (and there is a literal -X file test operator too, to confuse things a bit). In most cases, these operators return true or false. Although we call these things operators, you’ll find their documentation in perlfunc.

Before you start a program that creates a new file, you might want to ensure that the file doesn’t already exist so that you don’t accidentally overwrite a vital spreadsheet datafile or that important birthday calendar. For this, you can use the -e file test, testing a filename for existence:

die "Oops! A file called '$filename' already exists.
"
  if -e $filename;

Notice that you don’t include $! in this die message, since you’re not reporting that the system refused a request in this case. Here’s an example of checking whether a file is being kept up-to-date. In this case, you’re testing an already-opened filehandle instead of a string filename. Let’s say that your program’s configuration file should be updated every week or two. (Maybe it’s checking for computer viruses.) If the file hasn’t been modified in the past 28 days, something is wrong. The -M file test returns the file modification time in days before the start of the program, which seems like a mouthful until you see how convenient the code is:

warn "Config file is looking pretty old!
"
  if -M CONFIG > 28;

The third example is more complex. Here, say that disk space is filling up, and rather than buy more disks, you decide to move any large, useless files to a backup. So let’s go through our list of files to see which of them are larger than 100 K. But even if a file is large, you shouldn’t warehouse it unless it hasn’t been accessed in the last 90 days (so we know that it’s not used too often). The -s file test operator, instead of returning true or false, returns the file size in bytes (and an existing file might have 0 bytes):

my @original_files = qw/ fred barney betty wilma pebbles dino bamm-bamm /;
my @big_old_files;  # The ones we want to put on backup tapes
foreach my $filename (@original_files) {
  push @big_old_files, $filename
    if -s $filename > 100_000 and -A $filename > 90;
}

There’s a way to make this example more efficient, as you’ll see by the end of the chapter.

The file tests all look like a hyphen and a letter, which is the name of the test, followed by either a filename or a filehandle to test. Many of them return a true/false value, but several give something more interesting. See Table 12-1 for the complete list, and read the following explanation to learn more about the special cases.

The tests -r, -w, -x, and -o tell whether the given attribute is true for the effective user or group ID, which essentially refers to the person who is “in charge of” running the program.

These tests look at the “permission bits” on the file to see what is permitted. If your system uses access control lists (ACLs), the tests will use those as well. These tests generally tell whether the system would try to permit something, but it doesn’t mean that it really would be possible. For example, -w may be true for a file on a CD-ROM, even though you can’t write to it, or -x may be true on an empty file, which can’t truly be executed.

The -s test does return true if the file is nonempty, but it’s a special kind of true. It’s the length of the file, measured in bytes, which evaluates as true for a nonzero number.

On a Unix filesystem there are seven types of items, represented by the seven file tests -f, -d, -l, -S, -p, -b, and -c. Any item should be one of those. But if you have a symbolic link pointing to a file, that will report true for both -f and -l. So, if you want to know whether something is a symbolic link, you should generally test that first. (You’ll learn more about symbolic links in “Links and Files”.)

The age tests, -M, -A, and -C (yes, they’re uppercase), return the number of days since the file was last modified, accessed, or had its inode changed. (The inode contains all the information about the file except for its contents—see the stat system call documentation or a good book on Unix internals for details.) This age value is a full floating-point number, so you might get a value of 2.00001 if a file had been modified two days and one second ago. (These “days” aren’t necessarily the same as a human would count; for example, if it’s 1:30 in the morning when you check a file modified about an hour before midnight, the value of -M for this file would be around 0.1, even though it was modified “yesterday.”)

When checking the age of a file, you might even get a negative value like –1.2, which means that the file’s last-access timestamp is set at about 30 hours in the future! The zero point on this timescale is the moment your program started running, so that value might mean that a long-running program was looking at a file that had just been accessed. Or a timestamp could be set (accidentally or intentionally) to a time in the future.

The tests -T and -B take a try at telling whether a file is text or binary. But people who know a lot about filesystems know that there’s no bit (at least in Unix-like operating systems) to indicate that a file is a binary or text file—so how can Perl tell? The answer is that Perl cheats: it opens the file, looks at the first few thousand bytes, and makes an educated guess. If it sees a lot of null bytes, unusual control characters, and bytes with the high bit set, then that looks like a binary file. If there’s not much weird stuff then it looks like text. As you might guess, it sometimes guesses wrong. It’s not perfect, but if you just need to separate your source code from compiled files or HTML files from PNGs, these tests should do the trick.

You’d think that -T and -B would always disagree, since a text file isn’t a binary and vice versa, but there are two special cases where they’re in complete agreement. If the file doesn’t exist or can’t be read, both are false, since it’s neither a text file nor a binary. Alternatively, if the file is empty, it’s an empty text file and an empty binary file at the same time, so they’re both true.

The -t file test returns true if the given filehandle is a TTY—in short, if it’s interactive because it’s not a simple file or pipe. When -t STDIN returns true, it generally means that you can interactively ask the user questions. If it’s false, your program is probably getting input from a file or pipe rather than a keyboard.

Don’t worry if you don’t know what some of the other file tests mean—if you’ve never heard of them, you won’t be needing them. But if you’re curious, get a good book about programming for Unix. On non-Unix systems, these tests all try to give results analogous to what they do on Unix, or undef for an unavailable feature. Usually you’ll be able to guess correctly what they’ll do.

If you omit the filename or filehandle parameter to a file test (that is, if you have just -r or just -s, say), the default operand is the file named in $_. The -t file test is an exception, because that test isn’t useful with filenames (they’re never TTYs). By default, it tests STDIN. So, to test a list of filenames to see which ones are readable, you simply type:

foreach (@lots_of_filenames) {
  print "$_ is readable
" if -r;  # same as -r $_
}

But if you omit the parameter, be careful that whatever follows the file test doesn’t look like it could be a parameter. For example, if you wanted to find out the size of a file in kilobytes rather than in bytes, you might be tempted to divide the result of -s by 1000 (or 1024), like this:

# The filename is in $_
my $size_in_K = -s / 1000;  # Oops!

When the Perl parser sees the slash, it doesn’t think about division; since it’s looking for the optional operand for -s, it sees what looks like the start of a regular expression in the forward slash. One simple way to prevent this kind of confusion is to put parentheses around the file test:

my $size_in_k = (-s) / 1024;  # Uses $_ by default

Of course, it’s always safe to explicitly give a file test a parameter:

my $size_in_k = (-s $filename) / 1024;

if (-r $filename and -w $filename) {
  ... }

if (-r $filename and -w _) {
    ... }

if (-r $filename) {
  print "The file is readable!
";
}

if (-w _) {
  print "The file is writable!
";
}

if (-r $filename) {
  print "The file is readable!
";
}

lookup( $other_filename );

if (-w _) {
  print "The file is writable!
";
}

sub lookup {
  return -w $_[0];
}

if (-r $filename and -w _) {
  print "The file is both readable and writable!
";
}

use v5.10;

if (-w -r $filename) {
  print "The file is both readable and writable!
";
}

use v5.10;

if (-r -w -x -o -d $filename) {
  print "My directory is readable, writable, and executable!
";
}

use v5.10;

if (-s -d $filename < 512) {    # WRONG! DON'T DO THIS
  say 'The directory is less than 512 bytes!';
}

if (( -d $filename and -s _ ) < 512) {
  print "The directory is less than 512 bytes!
";
}

if (-d $filename and -s _ < 512) {
  print "The directory is less than 512 bytes!
";
}

The stat and lstat Functions

While these file tests are fine for testing various attributes regarding a particular file or filehandle, they don’t tell you 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, merely call the stat function, which returns pretty much everything that the stat Unix system call returns (hopefully more than you want to know).

The operand to stat is a filehandle (including the _ virtual 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 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 the stat(2) documentation. You should probably look there for the detailed descriptions. But in short, 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 should always 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 contains something like -rwxr-xr-x. That information is wrapped up in $mode.

$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 13. 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 telling how many seconds have passed since the epoch, an arbitrary starting point for measuring system time. Some filesystems, such as ext2, may disable atime as a performance measure.

Invoking stat on the name of a symbolic link returns information on what the symbolic link points at, not information about the symbolic link itself (unless the link just 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 $_.

The localtime Function

When you have a timestamp number (such as the ones from stat), it will typically look something like 1454133253. That’s not very useful for most humans, unless you need to compare two timestamps by subtracting. You may need to convert it to something human-readable, such as a string like “Sat Jan 30 00:54:13 2016.” Perl can do that with the localtime function in a scalar context:

my $timestamp = 1454133253;
my $date = localtime $timestamp;

In a list context, localtime returns a list of numbers, several of which may not be quite what you’d expect:

my($sec, $min, $hour, $mday, $mon, $year, $wday, $yday, $isdst)
  = localtime $timestamp;

The $mon is a month number, ranging from 0 to 11, which is handy as an index into an array of month names. The $year is the number of years since 1900, oddly enough, so add 1900 to get the real year number. The $wday ranges from 0 (for Sunday) through 6 (for Saturday), and the $yday is the day of the year (ranging from 0 for January 1, through 364—or in the case of leap years, 365—for December 31).

There are two related functions that you’ll also find useful. The gmtime function is just the same as localtime, except that it returns the time in Universal Time. If you need the current timestamp number from the system clock, just use the time function. Both localtime and gmtime default to using the current time value if you don’t supply a parameter:

my $now = gmtime;  # Get the current universal timestamp as a string

For more on manipulating dates and times, see Appendix B for information about some useful modules.

Bitwise Operators

When you need to work with numbers bit-by-bit, as when working with the mode bits returned by stat, you’ll need to use the bitwise operators. These are the operators that perform binary math operations on values. The bitwise-and operator (&) reports which bits are set in the left argument and in the right argument. For example, the expression 10 & 12 has the value 8. The bitwise-and needs to have a one-bit in both operands to produce a one-bit in the result. That means the bitwise-and operation on 10 (which is 1010 in binary) and 12 (which is 1100) gives 8 (which is 1000, with a one-bit only where the left operand has a one-bit and the right operand also has a one-bit). See Figure 12-1.

Figure 12-1. Bitwise-and addition

The different bitwise operators and their meanings are shown in Table 12-2.

So, here’s an example of some things you could do with the $mode returned by stat. The results of these bit manipulations could be useful with chmod, which you’ll see in Chapter 13:

# $mode is the mode value returned from a stat of CONFIG
warn "Hey, the configuration file is world-writable!
"
  if $mode & 0002;                             # configuration security problem
my $classical_mode = 0777 & $mode;             # mask off extra high-bits
my $u_plus_x = $classical_mode | 0100;         # turn one bit on
my $go_minus_r = $classical_mode & (~ 0044);   # turn two bits off

use v5.10;

my $number     = 137;
my $number_str = '137';
my $string     = 'Amelia';

say "number_str & string:  ", $number_str & $string;
say "number & string:      ", $number & $string;
say "number & number_str:  ", $number & $number_str;
say "number_str & string:  ", $number_str & $string;

number_str & string:  ¿!%
number & string:      0
number & number_str:  137
number_str & string:  0

use v5.22.0;
use feature qw(bitwise);
no warnings qw(experimental::bitwise);

my $number     = 137;
my $number_str = '137';
my $string     = 'Amelia';

say "number_str & string:  ", $number_str & $string;
say "number & string:      ", $number     & $string;
say "number & number_str:  ", $number     & $number_str;
say "number_str & string:  ", $number_str & $string;

number_str & string:  0
number & string:      0
number & number_str:  137
number_str & string:  0

use v5.22.0;
use feature qw(bitwise);
no warnings qw(experimental::bitwise);

my $number     = 137;
my $number_str = '137';
my $string     = 'Amelia';

say "number_str &. string:  ", $number_str &. $string;
say "number &. string:      ", $number     &. $string;
say "number &. number_str:  ", $number     &. $number_str;
say "number_str &. string:  ", $number_str &. $string;

number_str &. string:  ¿!%
number &. string:      ¿!%
number &. number_str:  137
number_str &. string:  ¿!%

Exercises

See “Answers to Chapter 12 Exercises” for answers to these exercises:

1. [15] Make a program that takes a list of files named on the command line and reports for each one whether it’s readable, writable, executable, or doesn’t exist. (Hint: it may be helpful to have a function that will do all the file tests for one file at a time.) What does it report about a file that has been chmod’ed to 0? (That is, if you’re on a Unix system, use the command chmod 0 some_file to mark that file as being neither readable, writable, nor executable.) In most shells, use a star as the argument to mean all the normal files in the current directory. That is, you could type something like ./ex12-1 * to ask the program for the attributes of many files at once.

2. [10] Make a program to identify the oldest file named on the command line and report its age in days. What does it do if the list is empty (that is, if no files are mentioned on the command line)?

3. [10] Make a program that uses stacked file test operators to list all files named on the command line that are readable, writable, and owned by you.