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