CGI::Carp(3pm)

1CGI::Carp(3pm)         Perl Programmers Reference Guide         CGI::Carp(3pm)
2
3
4

NAME

6       CGI::Carp - CGI routines for writing to the HTTPD (or other) error log
7

SYNOPSIS

9           use CGI::Carp;
10
11           croak "We're outta here!";
12           confess "It was my fault: $!";
13           carp "It was your fault!";
14           warn "I'm confused";
15           die  "I'm dying.\n";
16
17           use CGI::Carp qw(cluck);
18           cluck "I wouldn't do that if I were you";
19
20           use CGI::Carp qw(fatalsToBrowser);
21           die "Fatal error messages are now sent to browser";
22

DESCRIPTION

24       CGI scripts have a nasty habit of leaving warning messages in the error
25       logs that are neither time stamped nor fully identified.  Tracking down
26       the script that caused the error is a pain.  This fixes that.  Replace
27       the usual
28
29           use Carp;
30
31       with
32
33           use CGI::Carp
34
35       And the standard warn(), die (), croak(), confess() and carp() calls
36       will automagically be replaced with functions that write out nicely
37       time-stamped messages to the HTTP server error log.
38
39       For example:
40
41          [Fri Nov 17 21:40:43 1995] test.pl: I'm confused at test.pl line 3.
42          [Fri Nov 17 21:40:43 1995] test.pl: Got an error message: Permission denied.
43          [Fri Nov 17 21:40:43 1995] test.pl: I'm dying.
44

REDIRECTING ERROR MESSAGES

46       By default, error messages are sent to STDERR.  Most HTTPD servers
47       direct STDERR to the server's error log.  Some applications may wish to
48       keep private error logs, distinct from the server's error log, or they
49       may wish to direct error messages to STDOUT so that the browser will
50       receive them.
51
52       The "carpout()" function is provided for this purpose.  Since carpout()
53       is not exported by default, you must import it explicitly by saying
54
55          use CGI::Carp qw(carpout);
56
57       The carpout() function requires one argument, which should be a refer‐
58       ence to an open filehandle for writing errors.  It should be called in
59       a "BEGIN" block at the top of the CGI application so that compiler
60       errors will be caught.  Example:
61
62          BEGIN {
63            use CGI::Carp qw(carpout);
64            open(LOG, ">>/usr/local/cgi-logs/mycgi-log") or
65              die("Unable to open mycgi-log: $!\n");
66            carpout(LOG);
67          }
68
69       carpout() does not handle file locking on the log for you at this
70       point.
71
72       The real STDERR is not closed -- it is moved to CGI::Carp::SAVEERR.
73       Some servers, when dealing with CGI scripts, close their connection to
74       the browser when the script closes STDOUT and STDERR.
75       CGI::Carp::SAVEERR is there to prevent this from happening prematurely.
76
77       You can pass filehandles to carpout() in a variety of ways.  The "cor‐
78       rect" way according to Tom Christiansen is to pass a reference to a
79       filehandle GLOB:
80
81           carpout(\*LOG);
82
83       This looks weird to mere mortals however, so the following syntaxes are
84       accepted as well:
85
86           carpout(LOG);
87           carpout(main::LOG);
88           carpout(main'LOG);
89           carpout(\LOG);
90           carpout(\'main::LOG');
91
92           ... and so on
93
94       FileHandle and other objects work as well.
95
96       Use of carpout() is not great for performance, so it is recommended for
97       debugging purposes or for moderate-use applications.  A future version
98       of this module may delay redirecting STDERR until one of the CGI::Carp
99       methods is called to prevent the performance hit.
100

MAKING PERL ERRORS APPEAR IN THE BROWSER WINDOW

102       If you want to send fatal (die, confess) errors to the browser, ask to
103       import the special "fatalsToBrowser" subroutine:
104
105           use CGI::Carp qw(fatalsToBrowser);
106           die "Bad error here";
107
108       Fatal errors will now be echoed to the browser as well as to the log.
109       CGI::Carp arranges to send a minimal HTTP header to the browser so that
110       even errors that occur in the early compile phase will be seen.  Nonfa‐
111       tal errors will still be directed to the log file only (unless redi‐
112       rected with carpout).
113
114       Changing the default message
115
116       By default, the software error message is followed by a note to contact
117       the Webmaster by e-mail with the time and date of the error.  If this
118       message is not to your liking, you can change it using the set_mes‐
119       sage() routine.  This is not imported by default; you should import it
120       on the use() line:
121
122           use CGI::Carp qw(fatalsToBrowser set_message);
123           set_message("It's not a bug, it's a feature!");
124
125       You may also pass in a code reference in order to create a custom error
126       message.  At run time, your code will be called with the text of the
127       error message that caused the script to die.  Example:
128
129           use CGI::Carp qw(fatalsToBrowser set_message);
130           BEGIN {
131              sub handle_errors {
132                 my $msg = shift;
133                 print "<h1>Oh gosh</h1>";
134                 print "<p>Got an error: $msg</p>";
135             }
136             set_message(\&handle_errors);
137           }
138
139       In order to correctly intercept compile-time errors, you should call
140       set_message() from within a BEGIN{} block.
141

MAKING WARNINGS APPEAR AS HTML COMMENTS

143       It is now also possible to make non-fatal errors appear as HTML com‐
144       ments embedded in the output of your program.  To enable this feature,
145       export the new "warningsToBrowser" subroutine.  Since sending warnings
146       to the browser before the HTTP headers have been sent would cause an
147       error, any warnings are stored in an internal buffer until you call the
148       warningsToBrowser() subroutine with a true argument:
149
150           use CGI::Carp qw(fatalsToBrowser warningsToBrowser);
151           use CGI qw(:standard);
152           print header();
153           warningsToBrowser(1);
154
155       You may also give a false argument to warningsToBrowser() to prevent
156       warnings from being sent to the browser while you are printing some
157       content where HTML comments are not allowed:
158
159           warningsToBrowser(0);    # disable warnings
160           print "<script type=\"text/javascript\"><!--\n";
161           print_some_javascript_code();
162           print "//--></script>\n";
163           warningsToBrowser(1);    # re-enable warnings
164
165       Note: In this respect warningsToBrowser() differs fundamentally from
166       fatalsToBrowser(), which you should never call yourself!
167

OVERRIDING THE NAME OF THE PROGRAM

169       CGI::Carp includes the name of the program that generated the error or
170       warning in the messages written to the log and the browser window.
171       Sometimes, Perl can get confused about what the actual name of the exe‐
172       cuted program was.  In these cases, you can override the program name
173       that CGI::Carp will use for all messages.
174
175       The quick way to do that is to tell CGI::Carp the name of the program
176       in its use statement.  You can do that by adding
177       "name=cgi_carp_log_name" to your "use" statement.  For example:
178
179           use CGI::Carp qw(name=cgi_carp_log_name);
180
181       .  If you want to change the program name partway through the program,
182       you can use the "set_progname()" function instead.  It is not exported
183       by default, you must import it explicitly by saying
184
185           use CGI::Carp qw(set_progname);
186
187       Once you've done that, you can change the logged name of the program at
188       any time by calling
189
190           set_progname(new_program_name);
191
192       You can set the program back to the default by calling
193
194           set_progname(undef);
195
196       Note that this override doesn't happen until after the program has com‐
197       piled, so any compile-time errors will still show up with the non-over‐
198       ridden program name
199

CHANGE LOG

201       1.05 carpout() added and minor corrections by Marc Hedlund
202            <hedlund@best.com> on 11/26/95.
203
204       1.06 fatalsToBrowser() no longer aborts for fatal errors within
205            eval() statements.
206
207       1.08 set_message() added and carpout() expanded to allow for FileHandle
208            objects.
209
210       1.09 set_message() now allows users to pass a code REFERENCE for
211            really custom error messages.  croak and carp are now
212            exported by default.  Thanks to Gunther Birznieks for the
213            patches.
214
215       1.10 Patch from Chris Dean (ctdean@cogit.com) to allow
216            module to run correctly under mod_perl.
217
218       1.11 Changed order of &gt; and &lt; escapes.
219
220       1.12 Changed die() on line 217 to CORE::die to avoid -w warning.
221
222       1.13 Added cluck() to make the module orthogonal with Carp.
223            More mod_perl related fixes.
224
225       1.20 Patch from Ilmari Karonen (perl@itz.pp.sci.fi):  Added
226            warningsToBrowser().  Replaced <CODE> tags with <PRE> in
227            fatalsToBrowser() output.
228
229       1.23 ineval() now checks both $^S and inspects the message for the
230       "eval" pattern
231            (hack alert!) in order to accomodate various combinations of Perl
232       and
233            mod_perl.
234
235       1.24 Patch from Scott Gifford (sgifford@suspectclass.com): Add support
236            for overriding program name.
237
238       1.26 Replaced CORE::GLOBAL::die with the evil $SIG{__DIE__} because the
239            former isn't working in some people's hands.  There is no such
240       thing
241            as reliable exception handling in Perl.
242
243       1.27 Replaced tell STDOUT with bytes=tell STDOUT.
244

AUTHORS

246       Copyright 1995-2002, Lincoln D. Stein.  All rights reserved.
247
248       This library is free software; you can redistribute it and/or modify it
249       under the same terms as Perl itself.
250
251       Address bug reports and comments to: lstein@cshl.org
252