include/inn/messages.h

   1 /*  $Id: messages.h 5496 2002-06-07 13:59:06Z alexk $
   2 **
   3 **  Logging, debugging, and error reporting functions.
   4 **
   5 **  This collection of functions facilitate logging, debugging, and error
   6 **  reporting in a flexible manner that can be used by libraries as well as by
   7 **  programs.  The functions are based around the idea of handlers, which take
   8 **  a message and do something appropriate with it.  The program can set the
   9 **  appropriate handlers for all the message reporting functions, and then
  10 **  library code can use them with impunity and know the right thing will
  11 **  happen with the messages.
  12 */
  13
  14 #ifndef INN_MESSAGES_H
  15 #define INN_MESSAGES_H 1
  16
  17 #include <inn/defines.h>
  18 #include <stdarg.h>
  19
  20 BEGIN_DECLS
  21
  22 /* These are the currently-supported types of traces. */
  23 enum message_trace {
  24     TRACE_NETWORK,              /* Network traffic. */
  25     TRACE_PROGRAM,              /* Stages of program execution. */
  26     TRACE_ALL                   /* All traces; this must be last. */
  27 };
  28
  29 /* The reporting functions.  The ones prefaced by "sys" add a colon, a space,
  30    and the results of strerror(errno) to the output and are intended for
  31    reporting failures of system calls. */
  32 extern void trace(enum message_trace, const char *, ...)
  33     __attribute__((__format__(printf, 2, 3)));
  34 extern void notice(const char *, ...)
  35     __attribute__((__format__(printf, 1, 2)));
  36 extern void sysnotice(const char *, ...)
  37     __attribute__((__format__(printf, 1, 2)));
  38 extern void warn(const char *, ...)
  39     __attribute__((__format__(printf, 1, 2)));
  40 extern void syswarn(const char *, ...)
  41     __attribute__((__format__(printf, 1, 2)));
  42 extern void die(const char *, ...)
  43     __attribute__((__noreturn__, __format__(printf, 1, 2)));
  44 extern void sysdie(const char *, ...)
  45     __attribute__((__noreturn__, __format__(printf, 1, 2)));
  46
  47 /* Debug is handled specially, since we want to make the code disappear
  48    completely unless we're built with -DDEBUG.  We can only do that with
  49    support for variadic macros, though; otherwise, the function just won't do
  50    anything. */
  51 #if !defined(DEBUG) && (INN_HAVE_C99_VAMACROS || INN_HAVE_GNU_VAMACROS)
  52 # if INN_HAVE_C99_VAMACROS
  53 #  define debug(format, ...)            /* empty */
  54 # elif INN_HAVE_GNU_VAMACROS
  55 #  define debug(format, args...)        /* empty */
  56 # endif
  57 #else
  58 extern void debug(const char *, ...)
  59     __attribute__((__format__(printf, 1, 2)));
  60 #endif
  61
  62 /* Set the handlers for various message functions.  All of these functions
  63    take a count of the number of handlers and then function pointers for each
  64    of those handlers.  These functions are not thread-safe; they set global
  65    variables. */
  66 extern void message_handlers_debug(int count, ...);
  67 extern void message_handlers_trace(int count, ...);
  68 extern void message_handlers_notice(int count, ...);
  69 extern void message_handlers_warn(int count, ...);
  70 extern void message_handlers_die(int count, ...);
  71
  72 /* Enable or disable tracing for particular classes of messages. */
  73 extern void message_trace_enable(enum message_trace, bool);
  74
  75 /* Some useful handlers, intended to be passed to message_handlers_*.  All
  76    handlers take the length of the formatted message, the format, a variadic
  77    argument list, and the errno setting if any. */
  78 extern void message_log_stdout(int, const char *, va_list, int);
  79 extern void message_log_stderr(int, const char *, va_list, int);
  80 extern void message_log_syslog_debug(int, const char *, va_list, int);
  81 extern void message_log_syslog_info(int, const char *, va_list, int);
  82 extern void message_log_syslog_notice(int, const char *, va_list, int);
  83 extern void message_log_syslog_warning(int, const char *, va_list, int);
  84 extern void message_log_syslog_err(int, const char *, va_list, int);
  85 extern void message_log_syslog_crit(int, const char *, va_list, int);
  86
  87 /* The type of a message handler. */
  88 typedef void (*message_handler_func)(int, const char *, va_list, int);
  89
  90 /* If non-NULL, called before exit and its return value passed to exit. */
  91 extern int (*message_fatal_cleanup)(void);
  92
  93 /* If non-NULL, prepended (followed by ": ") to all messages printed by either
  94    message_log_stdout or message_log_stderr. */
  95 extern const char *message_program_name;
  96
  97 END_DECLS
  98
  99 #endif /* INN_MESSAGE_H */