1/* 2 * Copyright (c) 2009-2013 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 26Amanda::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 37See C<debug.h> for a more in-depth description of the logging 38functionality of this module. 39 40=head1 DEBUG LOGGING 41 42Several debug logging functions, each taking a single string, are 43available: 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 61Perl's built-in C<die> and C<warn> functions are patched to call 62C<critical> and C<warning>, respectively. 63 64All of the debug logging functions are available via the export tag 65C<:logging>. 66 67Applications can adjust the handling of log messages with 68C<add_amanda_log_handler($hdlr)> where C<$hdlr> is a predefined log 69destination. The following destinations are available in this 70package. 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 78Most applications should use L<Amanda::Util>'s C<setup_application> to 79initialize the debug libraries. The initialization functions 80available from this module are thus considered "advanced", and the 81reader is advised to consult the C header, C<debug.h>, for details. 82 83Briefly, the functions C<dbopen> and C<dbrename> are used to open a 84debug file whose pathname includes all of the relevant 85information. C<dbclose> and C<dbreopen> are used to close that debug 86file before transferring control to another process. 87 88C<$error_exit_status> is the exit status with which C<critical> will 89exit. 90 91All of the initialization functions and variables are available via 92the export tag C<:init>. 93 94The current debug file's integer file descriptor (I<not> a Perl 95filehandle) is available from C<dbfd()>. Likewise, C<dbfn()> returns 96the filename of the current debug file. 97 98C<debug_dup_stderr_to_debug()> redirects, at the file-descriptor 99level, C<STDERR> into the debug file. This is useful when running 100external applications which may produce error output. 101 102=cut 103 104 105%} 106