Section 5.8. Fatal Errors with die

5.8. Fatal Errors with die

Let's step aside for a moment. We need some stuff that isn't directly related to (or limited to) I/O 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.^[§] This functionality is available to us with the die function, so we can make our own fatal errors.

^[§] Well, it does this by default, but errors may be trapped with an eval block, as we'll see in Chapter 16.

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

You may not know it, but every program that runs on Unix (and many other modern operating systems) has an exit status, telling if it was successful. Programs that run other programs (like the make utility program) look at that exit status to see that everything happened correctly. The exit status is 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, 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.

We could rewrite the previous example, perhaps with something like this:

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

If the open fails, die will terminate the program and tell you 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), $! will give you 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 $!.^[*] 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.

^[*] On some non-Unix operating systems, $! may say something like error number 7, which leaves 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^[] 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:

] 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 helpful because we always seem to want more information in our error messages than we included 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 with a trailing newline on the message:

     if (@ARGV < 2) {       die "Not enough arguments\n";     }

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 the error might be something you want to track down during debugging.^[*]

^[*] 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 want to look into the special _ _FILE_ _ and _ _LINE_ _ tokens (or the caller function) to get the information that is being omitted by adding the newline, so you can print it in your own choice of format.

You should always check the return value of open since the rest of the program is relying upon its success.

5.8.1. Warning Messages with warn

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

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

] Warnings cant 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 I/O instructional material. Read on.