git.gag.com Git - debian/amanda/blob - perl/Amanda/Debug.swg

   1 /*
   2  * Copyright (c) Zmanda, Inc.  All Rights Reserved.
   3  *
   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.
   7  *
   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.
  12  *
  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.
  16  *
  17  * Contact information: Zmanda Inc., 465 S Mathlida Ave, Suite 300
  18  * Sunnyvale, CA 94086, USA, or: http://www.zmanda.com
  19  */
  20
  21 %module "Amanda::Debug"
  22 %include "amglue/amglue.swg"
  23 %include "exception.i"
  24
  25 %{
  26 #include <glib.h>
  27 #include "debug.h"
  28 %}
  29
  30 %perlcode %{
  31 =head1 NAME
  32
  33 Amanda::Debug - support for debugging Amanda applications
  34
  35 =head1 SYNOPSIS
  36
  37   use Amanda::Util qw( :constants );
  38
  39   Amanda::Util::setup_application("amcooltool", "server", $CONTEXT_CMDLINE);
  40
  41   debug("this is a debug message");
  42   die("Unable to frobnicate the ergonator");
  43
  44 See C<debug.h> for a more in-depth description of the logging functionality of
  45 this module.
  46
  47 =head1 API STATUS
  48
  49 Stable
  50
  51 =head1 DEBUG LOGGING
  52
  53 Several debug logging functions, each taking a single string, are
  54 available:
  55
  56 =over
  57
  58 =item C<error> - also aborts the program to produce a core dump
  59
  60 =item C<critical> - exits the program with C<$error_exit_status>
  61
  62 =item C<warning>
  63
  64 =item C<message>
  65
  66 =item C<info>
  67
  68 =item C<debug>
  69
  70 =back
  71
  72 Perl's built-in C<die> and C<warn> functions are patched to call C<critical>
  73 and C<warning>, respectively.
  74
  75 All of the debug logging functions are available via the export tag
  76 C<:logging>.
  77
  78 =head1 ADVANCED USAGE
  79
  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.
  84
  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.
  89
  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
  96 L<Amanda::Logfile>).
  97
  98 C<$error_exit_status> is the exit status with which C<critical>
  99 will exit.
 100
 101 All of the initialization functions and variables are available via
 102 the export tag C<:init>.
 103
 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.
 107
 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.
 111
 112 =cut
 113 %}
 114
 115 /*
 116  * Initialization
 117  */
 118
 119 amglue_export_tag(init,
 120     debug_init dbopen dbreopen dbrename dbclose
 121     $erroutput_type $error_exit_status
 122 );
 123
 124 void    debug_init(void);
 125 void    dbopen(char *subdir);
 126 void    dbreopen(char *file, char *notation);
 127 void    dbrename(char *config, char *subdir);
 128 void    dbclose(void);
 129
 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);
 135
 136 erroutput_type_t erroutput_type;
 137 int error_exit_status;
 138
 139 /*
 140  * Override die() and warn()
 141  */
 142 %perlcode %{
 143 sub _my_die {
 144     # $^S is set if we're in an eval { .. }, in which case we want
 145     # to use the default Perl semantics.
 146     if ($^S) {
 147         die(@_);
 148     } else {
 149         my ($msg) = @_;
 150         chomp $msg;
 151         critical(@_);
 152     }
 153 };
 154 $SIG{__DIE__} = \&my_die;
 155
 156 sub _my_warn {
 157     my ($msg) = @_;
 158     chomp $msg;
 159     warning(@_);
 160 };
 161 $SIG{__WARN__} = \&my_warn;
 162
 163 # utility function for test scripts, which want to use the regular
 164 # perl mechanisms
 165 sub disable_die_override {
 166     delete $SIG{__DIE__};
 167     delete $SIG{__WARN__};
 168 }
 169 %}
 170
 171 /*
 172  * Logging
 173  */
 174
 175 amglue_export_tag(logging,
 176     error critical warning message info debug
 177 );
 178
 179 %rename(error) error__; /* error() is a macro defined in debug.h .. just avoid that */
 180 %inline %{
 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); }
 187 %}
 188
 189 /*
 190  * Advanced
 191  */
 192
 193 int     dbfd(void);
 194 char *  dbfn(void);
 195 void debug_dup_stderr_to_debug(void);