2 * Copyright (c) Zmanda, Inc. All Rights Reserved.
4 * This library is free software; you can redistribute it and/or modify it
5 * under the terms of the GNU Lesser General Public License version 2.1
6 * as published by the Free Software Foundation.
8 * This library 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 Lesser General Public
11 * License for more details.
13 * You should have received a copy of the GNU Lesser General Public License
14 * along with this library; if not, write to the Free Software Foundation,
15 * Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
17 * Contact information: Zmanda Inc., 465 S Mathlida Ave, Suite 300
18 * Sunnyvale, CA 94086, USA, or: http://www.zmanda.com
21 %module "Amanda::Debug"
22 %include "amglue/amglue.swg"
23 %include "exception.i"
33 Amanda::Debug - support for debugging Amanda applications
37 use Amanda::Util qw( :constants );
39 Amanda::Util::setup_application("amcooltool", "server", $CONTEXT_CMDLINE);
41 debug("this is a debug message");
42 die("Unable to frobnicate the ergonator");
44 See C<debug.h> for a more in-depth description of the logging functionality of
53 Several debug logging functions, each taking a single string, are
58 =item C<error> - also aborts the program to produce a core dump
60 =item C<critical> - exits the program with C<$error_exit_status>
72 Perl's built-in C<die> and C<warn> functions are patched to call C<critical>
73 and C<warning>, respectively.
75 All of the debug logging functions are available via the export tag
80 Most applications should use L<Amanda::Util>'s C<setup_application>
81 to initialize the debug libraries. The initialization functions
82 available from this module are thus considered "advanced", and the
83 reader is advised to consult the C header, C<debug.h>, for details.
85 Briefly, the functions C<dbopen> and C<dbrename> are used to
86 open a debug file whose pathname includes all of the relevant
87 information. C<dbclose> and C<dbreopen> are used to close that debug
88 file before transferring control to another process.
90 The variable C<$erroutput_type> can take on any combination
91 of the flags C<$ERROUTPUT_INTERACTIVE>, C<$ERROUTPUT_SYSLOG>
92 and C<$ERROUTPUT_AMANDALOG>. C<$ERROUTPUT_INTERACTIVE>
93 causes messages from C<error> and C<critical> to be sent
94 to stderr. C<$ERROUTPUT_SYSLOG> sends it to syslog, and
95 C<$ERROUTPUT_AMANDALOG> sends it to the current trace log (see
98 C<$error_exit_status> is the exit status with which C<critical>
101 All of the initialization functions and variables are available via
102 the export tag C<:init>.
104 The current debug file's integer file descriptor (I<not> a Perl
105 filehandle) is available from C<dbfd()>. Likewise, C<dbfn()> returns
106 the filename of the current debug file.
108 C<debug_dup_stderr_to_debug()> redirects, at the file-descriptor level,
109 C<STDERR> into the debug file. This is useful when running external
110 applications which may produce error output.
119 amglue_export_tag(init,
120 debug_init dbopen dbreopen dbrename dbclose
121 $erroutput_type $error_exit_status
124 void debug_init(void);
125 void dbopen(char *subdir);
126 void dbreopen(char *file, char *notation);
127 void dbrename(char *config, char *subdir);
130 amglue_add_flag_tag_fns(erroutput_type_t);
131 amglue_add_constant_short(ERR_INTERACTIVE, INTERACTIVE, erroutput_type_t);
132 amglue_add_constant_short(ERR_SYSLOG, SYSLOG, erroutput_type_t);
133 amglue_add_constant_short(ERR_AMANDALOG, AMANDALOG, erroutput_type_t);
134 amglue_copy_tag_to(erroutput_type_t, init);
136 erroutput_type_t erroutput_type;
137 int error_exit_status;
140 * Override die() and warn()
144 # $^S is set if we're in an eval { .. }, in which case we want
145 # to use the default Perl semantics.
154 $SIG{__DIE__} = \&my_die;
161 $SIG{__WARN__} = \&my_warn;
163 # utility function for test scripts, which want to use the regular
165 sub disable_die_override {
166 delete $SIG{__DIE__};
167 delete $SIG{__WARN__};
175 amglue_export_tag(logging,
176 error critical warning message info debug
179 %rename(error) error__; /* error() is a macro defined in debug.h .. just avoid that */
181 void error__(char *msg) { g_error("%s", msg); }
182 void critical(char *msg) { g_critical("%s", msg); }
183 void warning(char *msg) { g_warning("%s", msg); }
184 void message(char *msg) { g_message("%s", msg); }
185 void info(char *msg) { g_info("%s", msg); }
186 void debug(char *msg) { g_debug("%s", msg); }
195 void debug_dup_stderr_to_debug(void);