/*
* Copyright (c) 2009-2012 Zmanda, Inc. All Rights Reserved.
* Copyright (c) 2013-2016 Carbonite, Inc. All Rights Reserved.
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation; either version 2
* of the License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
* or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* for more details.
*
* You should have received a copy of the GNU General Public License along
* with this program; if not, write to the Free Software Foundation, Inc.,
* 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*
* Contact information: Carbonite Inc., 756 N Pastoria Ave
* Sunnyvale, CA 94085, or: http://www.zmanda.com
*/
%perlcode %{
=head1 NAME
Amanda::Debug - support for debugging Amanda applications
=head1 SYNOPSIS
use Amanda::Util qw( :constants );
Amanda::Util::setup_application("amcooltool", "server", $CONTEXT_CMDLINE);
debug("this is a debug message");
die("Unable to frobnicate the ergonator");
See C<debug.h> for a more in-depth description of the logging
functionality of this module.
=head1 DEBUG LOGGING
Several debug logging functions, each taking a single string, are
available:
=over
=item C<error> - also aborts the program to produce a core dump
=item C<critical> - exits the program with C<$error_exit_status>
=item C<warning>
=item C<message>
=item C<info>
=item C<debug>
=back
Perl's built-in C<die> and C<warn> functions are patched to call
C<critical> and C<warning>, respectively.
All of the debug logging functions are available via the export tag
C<:logging>.
Applications can adjust the handling of log messages with
C<add_amanda_log_handler($hdlr)> where C<$hdlr> is a predefined log
destination. The following destinations are available in this
package. See L<Amanda::Logfile> for C<$amanda_log_trace_log>.
$amanda_log_null
$amanda_log_stderr
$amanda_log_syslog
=head1 ADVANCED USAGE
Most applications should use L<Amanda::Util>'s C<setup_application> to
initialize the debug libraries. The initialization functions
available from this module are thus considered "advanced", and the
reader is advised to consult the C header, C<debug.h>, for details.
Briefly, the functions C<dbopen> and C<dbrename> are used to open a
debug file whose pathname includes all of the relevant
information. C<dbclose> and C<dbreopen> are used to close that debug
file before transferring control to another process.
C<$error_exit_status> is the exit status with which C<critical> will
exit.
All of the initialization functions and variables are available via
the export tag C<:init>.
The current debug file's integer file descriptor (I<not> a Perl
filehandle) is available from C<dbfd()>. Likewise, C<dbfn()> returns
the filename of the current debug file.
C<debug_dup_stderr_to_debug()> redirects, at the file-descriptor
level, C<STDERR> into the debug file. This is useful when running
external applications which may produce error output.
=cut
%}