IRIX Base Documentation 2001 May/SGI IRIX Base Documentation 2001 May.iso/usr/share/catman/p_man/cat3/perl5/CGI::Carp.z/CGI::Carp

Text File | 1998-10-30 | 5.9 KB | 199 lines

CCCCGGGGIIII::::::::CCCCaaaarrrrpppp((((3333))))                                                      CCCCGGGGIIII::::::::CCCCaaaarrrrpppp((((3333))))



NNNNAAAAMMMMEEEE
     CCCCGGGGIIII::::::::CCCCaaaarrrrpppp - CGI routines for writing to the HTTPD (or other) error log

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
         use CGI::Carp;

         croak "We're outta here!";
         confess "It was my fault: $!";
         carp "It was your fault!";
         warn "I'm confused";
         die  "I'm dying.\n";


DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     CGI scripts have a nasty habit of leaving warning messages in the error
     logs that are neither time stamped nor fully identified.  Tracking down
     the script that caused the error is a pain.  This fixes that.  Replace
     the usual

         use Carp;

     with

         use CGI::Carp

     And the standard _w_a_r_n(), die (), _c_r_o_a_k(), _c_o_n_f_e_s_s() and _c_a_r_p() calls will
     automagically be replaced with functions that write out nicely time-
     stamped messages to the HTTP server error log.

     For example:

        [Fri Nov 17 21:40:43 1995] test.pl: I'm confused at test.pl line 3.
        [Fri Nov 17 21:40:43 1995] test.pl: Got an error message: Permission denied.
        [Fri Nov 17 21:40:43 1995] test.pl: I'm dying.


RRRREEEEDDDDIIIIRRRREEEECCCCTTTTIIIINNNNGGGG EEEERRRRRRRROOOORRRR MMMMEEEESSSSSSSSAAAAGGGGEEEESSSS
     By default, error messages are sent to STDERR.  Most HTTPD servers direct
     STDERR to the server's error log.  Some applications may wish to keep
     private error logs, distinct from the server's error log, or they may
     wish to direct error messages to STDOUT so that the browser will receive
     them.

     The carpout() function is provided for this purpose.  Since _c_a_r_p_o_u_t() is
     not exported by default, you must import it explicitly by saying

        use CGI::Carp qw(carpout);

     The _c_a_r_p_o_u_t() 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.  Example:



                                                                        PPPPaaaaggggeeee 1111






CCCCGGGGIIII::::::::CCCCaaaarrrrpppp((((3333))))                                                      CCCCGGGGIIII::::::::CCCCaaaarrrrpppp((((3333))))



        BEGIN {
          use CGI::Carp qw(carpout);
          open(LOG, ">>/usr/local/cgi-logs/mycgi-log") or
            die("Unable to open mycgi-log: $!\n");
          carpout(LOG);
        }

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

     The real STDERR is not closed -- it is moved to SAVEERR.  Some servers,
     when dealing with CGI scripts, close their connection to the browser when
     the script closes STDOUT and STDERR.  SAVEERR is used to prevent this
     from happening prematurely.

     You can pass filehandles to _c_a_r_p_o_u_t() in a variety of ways.  The
     "correct" way according to Tom Christiansen is to pass a reference to a
     filehandle GLOB:

         carpout(\*LOG);

     This looks weird to mere mortals however, so the following syntaxes are
     accepted as well:

         carpout(LOG);
         carpout(main::LOG);
         carpout(main'LOG);
         carpout(\LOG);
         carpout(\'main::LOG');

         ... and so on

     Use of _c_a_r_p_o_u_t() is not great for performance, so it is recommended for
     debugging purposes or for moderate-use applications.  A future version of
     this module may delay redirecting STDERR until one of the CGI::Carp
     methods is called to prevent the performance hit.

MMMMAAAAKKKKIIIINNNNGGGG PPPPEEEERRRRLLLL EEEERRRRRRRROOOORRRRSSSS AAAAPPPPPPPPEEEEAAAARRRR IIIINNNN TTTTHHHHEEEE BBBBRRRROOOOWWWWSSSSEEEERRRR WWWWIIIINNNNDDDDOOOOWWWW
     If you want to send fatal (die, confess) errors to the browser, ask to
     import the special "fatalsToBrowser" subroutine:

         use CGI::Carp qw(fatalsToBrowser);
         die "Bad error here";

     Fatal errors will now be echoed to the browser as well as to the log.
     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).







                                                                        PPPPaaaaggggeeee 2222






CCCCGGGGIIII::::::::CCCCaaaarrrrpppp((((3333))))                                                      CCCCGGGGIIII::::::::CCCCaaaarrrrpppp((((3333))))



CHANGE LOG
     1.05 _c_a_r_p_o_u_t() added and minor corrections by Marc Hedlund
          <[e-mail]> on 11/26/95.

     1.06 _f_a_t_a_l_s_T_o_B_r_o_w_s_e_r() no longer aborts for fatal errors within
          _e_v_a_l() statements.

AAAAUUUUTTTTHHHHOOOORRRRSSSS
     Lincoln D. Stein <[e-mail]>.  Feel free to redistribute
     this under the Perl Artistic License.

SSSSEEEEEEEE AAAALLLLSSSSOOOO
     Carp, CGI::Base, CGI::BasePlus, CGI::Request, CGI::MiniSvr, CGI::Form,
     CGI::Response









































                                                                        PPPPaaaaggggeeee 3333