Debugging Perl/CGI Scripts

Hosting servers are configured to store error logs for CGI/Perl scripts, encountered during the course of operation. By default, error messages are sent to STDERR.

Most HTTPD servers direct STDERR to the server's error log, which stores information for all the websites hosted on a shared hosting environment. As this, this file cannot be accessed by individual website owners. You may wish to keep private error logs, distinct from the server's error log, or may wish to direct error messages to to a web browser.

This can be accomplished by coding your scripts accordingly during the development phase.

Sending error messages to a private log file

The carpout() function can be used to achieve this. Since carpout() is not exported by default, you must import it explicitly as -

use CGI::Carp qw(carpout);

The carpout() function requires one argument, which should be a reference to an open filehandle for writing errors. It should be called in a BEGIN block at the top of the CGI application so that compiler errors will be caught.

carpout() does not handle file locking on the log for you at this point.

Sending error messages to a Web Browser

Fatal (die, confess) errors can be sent to a web browser by importing the special "fatalsToBrowser" subroutine:

use CGI::Carp qw(fatalsToBrowser);
die "Couldn't open log file";

Fatal errors will now be echoed to the browser as well as to the log file. CGI::Carp arranges to send a minimal HTTP header to the browser so that even errors that occur in the early compile phase will be seen. Nonfatal errors will still be directed to the log file only (unless redirected with carpout).

Sample Script

#!/usr/bin/perl -wT

# In the first line above, T causes Perl to check
# for "tainted" data, that is, data from outside the
# script (i.e. user input) that is going to be used
# to affect something else outside the script
# (i.e. writing to a log file)

# You can untaint data by parsing it for unwanted
# characters then saving it to another variable.

# If you are having trouble with a script, try removing
# the T switch to see if that is the problem.

# The w switch in the first line causes warnings about
# script syntax to be printed, if there are any.

# This script does 2 things:
#
#1. It directs fatal errors to the browser,
# so when the script is invoked via the Web,
# a meaningful error message is returned.
# This is useful when developing a script;
# but should be disabled when the script
# is made publicly available.
#
# 2. It will direct any error message the script
# generates to an error log that resides in
# the user's home directory. The file must
# already exist and be "other" writeable.

# Notice that the following is enclosed in a BEGIN { }
# block that causes it to execute before the rest of
# the script is read.

# This block should be placed in the main script,
# as near the top as practical. Do not place it in
# subroutines or libraries. Always test
# subroutines thoroughly before placing them
# in libraries.

BEGIN {

# define an error log in YOUR home directory
# this is an example where the
# home directory is /domains/domain.com/

my $error_log = "/domains/domain.com/logs/cgi-error.log";

# "my" in the line above makes the variable $error_log
# local so it only has meaning inside this block.
# See your text for more on variable scope.

# load the CGI::Carp module;
# fatalsToBrowser directs fatal errors to the browser
# carpout is for directing errors to the error log

# open(...) is used to open a file.
# >> means the new input will be appended what's
# already in the file.

# LOG is a nickname (properly called a "file handle")
# that is given to the file so it is easy to refer to
# it later, i.e. carpout(LOG) sends the error
# message to the file with the nickname LOG

# || means "or" (as in do this or that)
# die means stop executing the program. You can add
# a message in quotes after the die command.

# $! is a special variable that contains the current error info

}

# The following line will cause an error.
# It is a call to a sub-routine that does not exist.
# After you have tried this script and received the error message,
# comment out the following line so no error occurs
# and "Hello world!" is printed.