chiark / gitweb /
wip new states
[innduct.git] / 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 */