git.gag.com Git - debian/amanda/blob - perl/Amanda/Debug.pod

   1 /*
   2  * Copyright (c) 2009-2012 Zmanda, Inc.  All Rights Reserved.
   3  *
   4  * This program is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU General Public License
   6  * as published by the Free Software Foundation; either version 2
   7  * of the License, or (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful, but
  10  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  11  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  12  * for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License along
  15  * with this program; if not, write to the Free Software Foundation, Inc.,
  16  * 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  17  *
  18  * Contact information: Zmanda Inc., 465 S. Mathilda Ave., Suite 300
  19  * Sunnyvale, CA 94085, USA, or: http://www.zmanda.com
  20  */
  21
  22 %perlcode %{
  23
  24 =head1 NAME
  25
  26 Amanda::Debug - support for debugging Amanda applications
  27
  28 =head1 SYNOPSIS
  29
  30   use Amanda::Util qw( :constants );
  31
  32   Amanda::Util::setup_application("amcooltool", "server", $CONTEXT_CMDLINE);
  33
  34   debug("this is a debug message");
  35   die("Unable to frobnicate the ergonator");
  36
  37 See C<debug.h> for a more in-depth description of the logging
  38 functionality of this module.
  39
  40 =head1 DEBUG LOGGING
  41
  42 Several debug logging functions, each taking a single string, are
  43 available:
  44
  45 =over
  46
  47 =item C<error> - also aborts the program to produce a core dump
  48
  49 =item C<critical> - exits the program with C<$error_exit_status>
  50
  51 =item C<warning>
  52
  53 =item C<message>
  54
  55 =item C<info>
  56
  57 =item C<debug>
  58
  59 =back
  60
  61 Perl's built-in C<die> and C<warn> functions are patched to call
  62 C<critical> and C<warning>, respectively.
  63
  64 All of the debug logging functions are available via the export tag
  65 C<:logging>.
  66
  67 Applications can adjust the handling of log messages with
  68 C<add_amanda_log_handler($hdlr)> where C<$hdlr> is a predefined log
  69 destination.  The following destinations are available in this
  70 package.  See L<Amanda::Logfile> for C<$amanda_log_trace_log>.
  71
  72   $amanda_log_null
  73   $amanda_log_stderr
  74   $amanda_log_syslog
  75
  76 =head1 ADVANCED USAGE
  77
  78 Most applications should use L<Amanda::Util>'s C<setup_application> to
  79 initialize the debug libraries.  The initialization functions
  80 available from this module are thus considered "advanced", and the
  81 reader is advised to consult the C header, C<debug.h>, for details.
  82
  83 Briefly, the functions C<dbopen> and C<dbrename> are used to open a
  84 debug file whose pathname includes all of the relevant
  85 information. C<dbclose> and C<dbreopen> are used to close that debug
  86 file before transferring control to another process.
  87
  88 C<$error_exit_status> is the exit status with which C<critical> will
  89 exit.
  90
  91 All of the initialization functions and variables are available via
  92 the export tag C<:init>.
  93
  94 The current debug file's integer file descriptor (I<not> a Perl
  95 filehandle) is available from C<dbfd()>.  Likewise, C<dbfn()> returns
  96 the filename of the current debug file.
  97
  98 C<debug_dup_stderr_to_debug()> redirects, at the file-descriptor
  99 level, C<STDERR> into the debug file.  This is useful when running
 100 external applications which may produce error output.
 101
 102 =cut
 103
 104
 105 %}