git.gag.com Git - debian/amanda/blob - common-src/debug.h

   1 /*
   2  * Amanda, The Advanced Maryland Automatic Network Disk Archiver
   3  * Copyright (c) 1991-1999 University of Maryland at College Park
   4  * Copyright (c) 2007-2012 Zmanda, Inc.  All Rights Reserved.
   5  * All Rights Reserved.
   6  *
   7  * Permission to use, copy, modify, distribute, and sell this software and its
   8  * documentation for any purpose is hereby granted without fee, provided that
   9  * the above copyright notice appear in all copies and that both that
  10  * copyright notice and this permission notice appear in supporting
  11  * documentation, and that the name of U.M. not be used in advertising or
  12  * publicity pertaining to distribution of the software without specific,
  13  * written prior permission.  U.M. makes no representations about the
  14  * suitability of this software for any purpose.  It is provided "as is"
  15  * without express or implied warranty.
  16  *
  17  * U.M. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL
  18  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL U.M.
  19  * BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  20  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
  21  * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
  22  * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  23  *
  24  * Authors: the Amanda Development Team.  Its members are listed in a
  25  * file named AUTHORS, in the root directory of this distribution.
  26  */
  27 /*
  28  * $Id: debug.h 6789 2007-06-18 20:18:52Z dustin $
  29  *
  30  * Logging support
  31  */
  32
  33 /* this file is included from amanda.h; there is no need to include
  34  * it explicitly in source files. */
  35
  36 #ifndef AMANDA_DEBUG_H
  37 #define AMANDA_DEBUG_H
  38
  39 /*
  40  * GENERAL LOGGING
  41  */
  42
  43 /* Amanda uses glib's logging facilities.  See
  44  *  http://developer.gnome.org/doc/API/2.2/glib/glib-Message-Logging.html
  45  *
  46  * Note that log output will go to stderr until debug_open is called.
  47  *
  48  * The error levels are assigned as follows:
  49  *  g_error -- errors that should dump core (will not return)
  50  *  g_critical -- fatal errors, exiting with exit status in
  51  *    error_exit_status() (will not return)
  52  *  g_warning -- non-fatal problems
  53  *  g_message -- normal status information
  54  *  g_info -- helpful extra details, but not verbose
  55  *  g_debug -- debug messages
  56  */
  57
  58 /* g_debug was introduced in glib 2.6, so define it here for systems where
  59  * it is lacking.  g_info doesn't exist even in glib 2.13, but maybe it will
  60  * be invented soon..
  61  */
  62
  63 #ifndef g_debug
  64 #define g_debug(...) g_log (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, __VA_ARGS__)
  65 #endif
  66
  67 #ifndef g_info
  68 #define g_info(...) g_log (G_LOG_DOMAIN, G_LOG_LEVEL_INFO, __VA_ARGS__)
  69 #endif
  70
  71 /* Initialize the debugging interface.  This is the "high-level"
  72  * initialization function; older and lower-level applications can call
  73  * dbopen() and friends directly.
  74  *
  75  * This function sets up debug logging and error-handling according to
  76  * the current process name, type, and context, as defined in util.
  77  */
  78 void debug_init(void);
  79
  80 /*
  81  * ADDITIONAL LOGGING
  82  */
  83
  84 /* Amanda implements a rudimentary method of distributing log information to
  85  * arbitrary consumers.  Some consumers are available here, and other modules
  86  * (e.g., server-src/logfile.c) may implement them, too.
  87  *
  88  * If amanda_log_handler has never been called, then the default disposition
  89  * depends on the application context: amanda_log_stderr is always used, and
  90  * amanda_log_syslog is used in the 'daemon' context.  The 'scriptutil' context
  91  * does not do any debug logging.
  92  */
  93
  94 /* prototype for log-handling functions; these will be called with only a single
  95  * bit set in the log_level. */
  96 typedef void (amanda_log_handler_t)(GLogLevelFlags log_level, const gchar *message);
  97
  98 /* add an amanda_log_handler_t to the list of handlers */
  99 void add_amanda_log_handler(amanda_log_handler_t *hdlr);
 100
 101 /* log ERROR, CRITICAL, and WARNING messages to syslog */
 102 void amanda_log_syslog(GLogLevelFlags log_level, const gchar *message);
 103
 104 /* log ERROR and CRITICAL to stderr */
 105 void amanda_log_stderr(GLogLevelFlags log_level, const gchar *message);
 106
 107 /* log nothing */
 108 void amanda_log_null(GLogLevelFlags log_level, const gchar *message);
 109
 110 /*
 111  * FATAL ERROR HANDLING
 112  */
 113
 114 /* for compatibility; these should eventually be substituted throughout
 115  * the codebase.  Extra calls to exit() and abort() should be optimized
 116  * away, and are there only for stupid compilers. */
 117 #define errordump(...) do { g_error(__VA_ARGS__); abort(); } while (0)
 118 #define error(...) do { g_critical(__VA_ARGS__); exit(error_exit_status); } while (0)
 119
 120 /* The process exit status that will be given when error()
 121  * or errordump() is called.
 122  */
 123 extern int error_exit_status;
 124
 125 /*
 126  * DEBUG LOGGING
 127  */
 128
 129 /* short names */
 130 #define dbopen(a)       debug_open(a)
 131 #define dbreopen(a,b)   debug_reopen(a,b)
 132 #define dbrename(a,b)   debug_rename(a,b)
 133 #define dbclose()       debug_close()
 134 #define dbprintf        debug_printf
 135 #define dbfd()          debug_fd()
 136 #define dbfp()          debug_fp()
 137 #define dbfn()          debug_fn()
 138
 139 /* constants for db(re)open */
 140 #define DBG_SUBDIR_SERVER  "server"
 141 #define DBG_SUBDIR_CLIENT  "client"
 142 #define DBG_SUBDIR_AMANDAD "amandad"
 143
 144 /* Open the debugging log in the given subdirectory.  Once
 145  * this function is called, debug logging is available.
 146  *
 147  * The debugging file is created in the given subdirectory of the
 148  * amanda debugging directory, with a filename based on the current
 149  * process name (from get_pname).
 150  *
 151  * @param subdir: subdirectory in which to create the debug file.
 152  * This is usually one of the DBG_SUBDIR_* constants.
 153  */
 154 void    debug_open(char *subdir);
 155
 156 /* Re-open a previously debug_close()d debug file, given by
 157  * filename, optionally adding a notation as to why it was
 158  * reopened.
 159  *
 160  * @param file: the filename of the debug file to reopen
 161  * @param notation: reason for re-opening the file
 162  */
 163 void    debug_reopen(char *file, char *notation);
 164
 165 /* Rename the debugging logfile into a configuration-specific subdirectory
 166  * of SUBDIR.  Any existing content of the file will be preserved.
 167  *
 168  * @param config: configuration name
 169  * @param subdir: subdirectory in which to create the debug file.
 170  */
 171 void    debug_rename(char *config, char *subdir);
 172
 173 /* Flush and close the debugging logfile.  Call this function at application
 174  * shutdown.
 175  */
 176 void    debug_close(void);
 177
 178 /* Add a message to the debugging logfile.  A newline is not automatically
 179  * added.
 180  *
 181  * This function is deprecated in favor of glib's g_debug().
 182  */
 183 void    debug_printf(const char *format, ...) G_GNUC_PRINTF(1,2);
 184
 185 /* Get the file descriptor for the debug file
 186  *
 187  * @returns: the file descriptor
 188  */
 189 int     debug_fd(void);
 190
 191 /* Get the stdio file handle for the debug file.
 192  *
 193  * @returns: the file handle
 194  */
 195 FILE *  debug_fp(void);
 196
 197 /* Get the pathname of the debug file.
 198  *
 199  * The result should not be freed by the caller.
 200  *
 201  * @returns: the pathname
 202  */
 203 char *  debug_fn(void);
 204
 205 /* Use 'dup2' to send stderr output to the debug file.  This is useful
 206  * when launching other applications, where the stderr of those applications
 207  * may be necessary for debugging.  It should be called in the child, after
 208  * the fork().
 209  */
 210 void debug_dup_stderr_to_debug(void);
 211
 212 /* error() and critical() will print a C stack trace if possible.  Set this to
 213  * TRUE to avoid this stack trace.  This is used by perl wrappers, for example */
 214 void suppress_error_traceback(void);
 215
 216 /*
 217  * PROCESS NAME
 218  */
 219
 220 /*
 221  * ASSERTIONS
 222  */
 223
 224 #ifndef SWIG
 225 #ifdef ASSERTIONS
 226
 227 /* Like the standard assert(), but call g_error() to log the result properly */
 228 #define assert(exp)     do {                                            \
 229     if (!(exp)) {                                                       \
 230         g_error(_("assert: %s is false: file %s, line %d"),             \
 231            stringize(exp), __FILE__, __LINE__);                         \
 232         g_assert_not_reached();                                         \
 233     }                                                                   \
 234 } while (0)
 235
 236 #else   /* ASSERTIONS */
 237
 238 #define assert(exp) ((void)0)
 239
 240 #endif  /* ASSERTIONS */
 241 #endif  /* SWIG */
 242
 243 #endif /* AMANDA_DEBUG_H */