Fatal Errors with die (Learning Perl, 3rd Edition)

11.3. Fatal Errors with die

Let's step aside for a moment. We need some stuff that isn't directly related to (or limited to) filehandles, but is more about getting out of a program earlier than normal.

When a fatal error happens inside Perl (for example, if you divide by zero, use an invalid regular expression, or call a subroutine that hasn't been declared) your program stops with an error message telling why.[253] But this functionality is available to us with the die function, so we can make our own fatal errors.

[253]Well, it does this by default, but errors may be trapped with an eval block, as we'll see in Chapter 17, "Some Advanced Perl Techniques".

The die function prints out the message you give it (to the standard error stream, where such messages should go) and makes sure that your program exits with a nonzero exit status.

You may not have known it, but every program that runs on Unix (and many other modern operating systems) has an exit status, telling whether it was successful or not. Programs that run other programs (like the make utility program) look at that exit status to see that everything is running correctly. The exit status is just a single byte, so it can't say much; traditionally, it is zero for success and a nonzero value for failure. Perhaps one means a syntax error in the command arguments, while two means that something went wrong during processing and three means the configuration file couldn't be found; the details differ from one command to the next. But zero always means that everything worked. When the exit status shows failure, a program like make knows not to go on to the next step.

So we could rewrite the previous example, perhaps something like this:

unless (open LOG, ">>logfile") {
  die "Cannot create logfile: $!";
}

If the open fails, die will terminate the program and tell us that it cannot create the logfile. But what's that $! in the message? That's the human-readable complaint from the system. In general, when the system refuses to do something we've requested (like opening a file), it will give us a reason (perhaps "permission denied" or "file not found," in this case). This is the string that you may have obtained with perror in C or a similar language. This human-readable complaint message will be available in Perl's special variable $!.[254] It's a good idea to include $! in the message when it could help the user to figure out what he or she did wrong. But if you use die to indicate an error that is not the failure of a system request, don't include $!, since it will generally hold an unrelated message left over from something Perl did internally. It will hold a useful value only immediately after a failed system request. A successful request won't leave anything useful there.

[254]On some non-Unix operating systems, $!may say something like error number 7, leaving it up to the user to look that one up in the documentation. On Windows and VMS, the variable $^E may have additional diagnostic information.

There's one more thing that die will do for you: it will automatically append the Perl program name and line number [255] to the end of the message, so you can easily identify which die in your program is responsible for the untimely exit. The error message from the previous code might look like this, if $! contained the message permission denied:

[255]If the error happened while reading from a file, the error message will include the "chunk number" (usually the line number) from the file and the name of the filehandle as well, since those are often useful in tracking down a bug.

Cannot create logfile: permission denied at your_program line 1234.

That's pretty helpful -- in fact, we always seem to want more information in our error messages than we put in the first time around. If you don't want the line number and file revealed, make sure that the dying words have a newline on the end. That is, another way you could use die is in a line like this, with a trailing newline:

die "Not enough arguments\n" if @ARGV < 2;

If there aren't at least two command-line arguments, that program will say so and quit. It won't include the program name and line number, since the line number is of no use to the user; this is the user's error, after all. As a rule of thumb, put the newline on messages that indicate a usage error and leave it off when it the error might be something you want to track down during debugging.[256]

[256]The program's name is in Perl's special variable $0, so you may wish to include that in the string: "$0:Not enough arguments\n". This is useful if the program may be used in a pipeline or shell script, for example, where it's not obvious which command is complaining. $0 can be changed during the execution of the program, however. You might also want to look into the special _ _FILE_ _ and _ _LINE_ _tokens (or the caller function) to get the information that is being left out by adding the newline, so you can print it in your own choice of format.

When opening a file fails, though, there's an easier and more common way instead of the unless block:

open LOG, ">>logfile"
  or die "Cannot create logfile: $!";

This uses the low-precedence short-circuit or operator that we saw in Chapter 10, "More Control Structures". If the open succeeds, it returns true, and the or is done. If the open fails, it returns false, and the short-circuit or goes on to the right side and dies with the message. You can read this as if it were English: "Open this file, or die!" It may not be the battle cry that will win a war, but it's a good way to write code.

You should always check the return value of open, since the rest of the program is relying upon its success. That's why we say that this is really the only way to write open -- with or die after it.[257] Until you're ready to be extra tricky, you should simply think of this as the syntax for open. Typing or die and a message takes only a moment when you're writing the program, but it can save hours, or possibly days of debugging time when something goes wrong.

[257]Older code may use the higher-precedence || operator instead. The only difference is the precedence, but it's a big one! If the open is written without parentheses, the higher-precedence operator will bind to the filename argument, not to the return value -- so the return value of open isn't being checked after all. If you use the ||, be sure to use the parentheses. Better yet, just use the low-precedence or as we've shown here whenever you're writing or die.

11.3.1. Warning Messages with warn

Just as die can indicate a fatal error that acts like one of Perl's builtin errors (like dividing by zero), you can use the warn function to cause a warning that acts like one of Perl's builtin warnings (like using an undef value as if it were defined, when warnings are enabled).

The warn function works just like die does, except for that last step -- it doesn't actually quit the program. But it adds the program name and line number if needed, and it prints the message to standard error, just as die would.[258]

[258]Warnings can't be trapped with an eval block, like fatal errors can. But see the documentation for the _ _WARN_ _ pseudo-signal (in the perlvar manpage) if you need to trap a warning.

And having talked about death and dire warnings, we now return you to your regularly scheduled filehandle instructional material. Read on.