2 * Copyright (c) 2009 Zmanda, Inc. All Rights Reserved.
4 * This program is free software; you can redistribute it and/or modify it
5 * under the terms of the GNU General Public License version 2 as published
6 * by the Free Software Foundation.
8 * This program is distributed in the hope that it will be useful, but
9 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
10 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13 * You should have received a copy of the GNU General Public License along
14 * with this program; if not, write to the Free Software Foundation, Inc.,
15 * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17 * Contact information: Zmanda Inc., 465 S. Mathilda Ave., Suite 300
18 * Sunnyvale, CA 94085, USA, or: http://www.zmanda.com
25 Amanda::Debug - support for debugging Amanda applications
29 use Amanda::Util qw( :constants );
31 Amanda::Util::setup_application("amcooltool", "server", $CONTEXT_CMDLINE);
33 debug("this is a debug message");
34 die("Unable to frobnicate the ergonator");
36 See C<debug.h> for a more in-depth description of the logging
37 functionality of this module.
41 Several debug logging functions, each taking a single string, are
46 =item C<error> - also aborts the program to produce a core dump
48 =item C<critical> - exits the program with C<$error_exit_status>
60 Perl's built-in C<die> and C<warn> functions are patched to call
61 C<critical> and C<warning>, respectively.
63 All of the debug logging functions are available via the export tag
66 Applications can adjust the handling of log messages with
67 C<add_amanda_log_handler($hdlr)> where C<$hdlr> is a predefined log
68 destination. The following destinations are available in this
69 package. See L<Amanda::Logfile> for C<$amanda_log_trace_log>.
77 Most applications should use L<Amanda::Util>'s C<setup_application> to
78 initialize the debug libraries. The initialization functions
79 available from this module are thus considered "advanced", and the
80 reader is advised to consult the C header, C<debug.h>, for details.
82 Briefly, the functions C<dbopen> and C<dbrename> are used to open a
83 debug file whose pathname includes all of the relevant
84 information. C<dbclose> and C<dbreopen> are used to close that debug
85 file before transferring control to another process.
87 C<$error_exit_status> is the exit status with which C<critical> will
90 All of the initialization functions and variables are available via
91 the export tag C<:init>.
93 The current debug file's integer file descriptor (I<not> a Perl
94 filehandle) is available from C<dbfd()>. Likewise, C<dbfn()> returns
95 the filename of the current debug file.
97 C<debug_dup_stderr_to_debug()> redirects, at the file-descriptor
98 level, C<STDERR> into the debug file. This is useful when running
99 external applications which may produce error output.