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., 505 N Mathlida Ave, Suite 120
  18  * Sunnyvale, CA 94085, 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::Debug qw( :init :logging );
  38
  39   # (note: dbopen and such are usually handled by
  40   #  Amanda::Util::setup_applicaton)
  41   dbopen("server");
  42
  43   debug("this is a debug message");
  44
  45 See C<debug.h> for a more in-depth description of the functionality of
  46 this module.
  47
  48 =head1 API STATUS
  49
  50 Stable
  51
  52 =head1 DEBUG LOGGING
  53
  54 Several debug logging messages, each taking a single string, are
  55 available:
  56
  57 =over
  58
  59 =item C<error> - also aborts the program to produce a core dump
  60
  61 =item C<critical> - exits the program with C<$error_exit_status>
  62
  63 =item C<warning>
  64
  65 =item C<message>
  66
  67 =item C<info>
  68
  69 =item C<debug>
  70
  71 =back
  72
  73 ALl of the debug logging functions are available via the export tag
  74 C<:logging>.
  75
  76 =head1 ADVANCED USAGE
  77
  78 Most applications should use L<Amanda::Util>'s C<setup_application>
  79 to initialize the debug libraries.  The initialization functions
  80 available from this module are thus considered "advanced", and the
  81 reader is advised to consult the C header, C<debug.h>, for details.
  82
  83 Briefly, the functions C<dbopen> and C<dbrename> are used to
  84 open a debug file whose pathname includes all of the relevant
  85 information. C<dbclose> and C<dbreopen> are used to close that debug
  86 file before transferring control to another process.
  87
  88 The variable C<$erroutput_type> can take on any combination
  89 of the flags C<$ERROUTPUT_INTERACTIVE>, C<$ERROUTPUT_SYSLOG>
  90 and C<$ERROUTPUT_AMANDALOG>.  C<$ERROUTPUT_INTERACTIVE>
  91 causes messages from C<error> and C<critical> to be sent
  92 to stderr. C<$ERROUTPUT_SYSLOG> sends it to syslog, and
  93 C<$ERROUTPUT_AMANDALOG> sends it to the current trace log (see
  94 L<Amanda::Logfile>).
  95
  96 C<$error_exit_status> is the exit status with which C<critical>
  97 will exit.
  98
  99 All of the initialization functions and variables are available via
 100 the export tag C<:init>.
 101
 102 The current debug file's integer file descriptor (I<not> a Perl
 103 filehandle) is available from C<dbfd()>.  Likewise, C<dbfn()> returns
 104 the filename of the current debug file.
 105
 106 C<debug_dup_stderr_to_debug()> redirects, at the file-descriptor level,
 107 C<STDERR> into the debug file.  This is useful when running external
 108 applications which may produce error output.
 109
 110 =cut
 111 %}
 112
 113 /*
 114  * Initialization
 115  */
 116
 117 amglue_export_tag(init,
 118     dbopen dbreopen dbrename dbclose
 119     $erroutput_type $error_exit_status
 120 );
 121
 122 void    dbopen(char *subdir);
 123 void    dbreopen(char *file, char *notation);
 124 void    dbrename(char *config, char *subdir);
 125 void    dbclose(void);
 126
 127 amglue_add_flag_tag_fns(erroutput_type_t);
 128 amglue_add_constant_short(ERR_INTERACTIVE, INTERACTIVE, erroutput_type_t);
 129 amglue_add_constant_short(ERR_SYSLOG, SYSLOG, erroutput_type_t);
 130 amglue_add_constant_short(ERR_AMANDALOG, AMANDALOG, erroutput_type_t);
 131 amglue_copy_tag_to(erroutput_type_t, init);
 132
 133 erroutput_type_t erroutput_type;
 134 int error_exit_status;
 135
 136 /*
 137  * Logging
 138  */
 139
 140 amglue_export_tag(logging,
 141     error critical warning message info debug
 142 );
 143
 144 %rename(error) error__; /* error() is a macro defined in debug.h .. just avoid that */
 145 %inline %{
 146 void error__(char *msg) { g_error("%s", msg); }
 147 void critical(char *msg) { g_critical("%s", msg); }
 148 void warning(char *msg) { g_warning("%s", msg); }
 149 void message(char *msg) { g_message("%s", msg); }
 150 void info(char *msg) { g_info("%s", msg); }
 151 void debug(char *msg) { g_debug("%s", msg); }
 152 %}
 153
 154 /*
 155  * Advanced
 156  */
 157
 158 int     dbfd(void);
 159 char *  dbfn(void);
 160 void debug_dup_stderr_to_debug(void);