Merge branch 'master' into squeeze

[debian/amanda] / perl / Amanda / Debug.pod

diff --git a/perl/Amanda/Debug.pod b/perl/Amanda/Debug.pod
new file mode 100644 (file)
index 0000000..f6ba2f5
--- /dev/null
+++ b/perl/Amanda/Debug.pod
@@ -0,0 +1,104 @@
+/*
+ * Copyright (c) 2009 Zmanda, 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 version 2 as published
+ * by the Free Software Foundation.
+ *
+ * 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: Zmanda Inc., 465 S. Mathilda Ave., Suite 300
+ * Sunnyvale, CA 94085, USA, 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
+
+
+%}