libslack(err) - message/error/debug/verbosity/alert messaging module
#include <slack/std.h> #include <slack/err.h>
void msg(const char *format, ...); void vmsg(const char *format, va_list args); void verbose(size_t level, const char *format, ...); void vverbose(size_t level, const char *format, va_list args); void debugf(size_t level, const char *format, ...); void vdebugf(size_t level, const char *format, va_list args); int error(const char *format, ...); int verror(const char *format, va_list args); void fatal(const char *format, ...); void vfatal(const char *format, va_list args); void dump(const char *format, ...); void vdump(const char *format, va_list args); void alert(int priority, const char *format, ...); void valert(int priority, const char *format, va_list args); void debugsysf(size_t level, const char *format, ...); void vdebugsysf(size_t level, const char *format, va_list args); int errorsys(const char *format, ...); int verrorsys(const char *format, va_list args); void fatalsys(const char *format, ...); void vfatalsys(const char *format, va_list args); void dumpsys(const char *format, ...); void vdumpsys(const char *format, va_list args); void alertsys(int priority, const char *format, ...); void valertsys(int priority, const char *format, va_list args); int set_errno(int errnum); void *set_errnull(int errnum);
#define debug(args) #define vdebug(args) #define debugsys(args) #define vdebugsys(args) #define check(test, mesg)
This module works with the prog(3) and msg(3) modules to provide functions for emitting various types of message with simple call syntax and flexible behaviour. The message types catered for are: normal, verbose, debug, error, fatal error, dump and alert messages. All messages are created and sent with printf(3)-like syntax. The destinations for these messages are configurable by the client. Calling prog_init(3) causes normal and verbose messages to be sent to standard output; debug, error, fatal error, dump and alert messages to be sent to standard error.
Calls to prog_set_out(3), prog_out_fd(3), prog_out_stdout(3), prog_out_file(3), prog_out_syslog(3) and prog_out_none(3) cause normal and verbose messages to be sent to the specified destination.
Calls to prog_set_err(3), prog_err_fd(3), prog_err_stderr(3), prog_err_file(3), prog_err_syslog(3) and prog_err_none(3) cause error, fatal error and dump messages to be sent to the specified destination.
Calls to prog_set_dbg(3), prog_dbg_fd(3), prog_dbg_stdout(3), prog_dbg_stderr(3), prog_dbg_file(3), prog_dbg_syslog(3), prog_dbg_none(3) cause debug messages to be sent to the specified destination.
Calls to prog_set_alert(3), prog_alert_fd(3), prog_alert_stdout(3), prog_alert_stderr(3), prog_alert_file(3), prog_alert_syslog(3), prog_alert_none(3) cause alert messages to be sent to the specified destination.
Calls to the generic functions prog_set_out(3), prog_set_err(3), prog_set_dbg(3) and prog_set_alert(3) cause their respective message types to be sent to the specified destination or destinations (multiplexing messages is only possible via these functions). See msg(3) for more details.
void msg(const char *format, ...)
format
is
a printf(3)-like format string and processes any remaining arguments in
the same way as printf(3).
Warning: Do not under any circumstances ever pass a non-literal string as the format argument unless you know exactly how many conversions will take place. Being careless with this is a very good way to build potential security holes into your programs. The same is true for all functions that take a printf()-like format string as an argument.
msg(buf); // EVIL msg("%s", buf); // GOOD
void vmsg(const char *format, va_list args)
void verbose(size_t level, const char *format, ...)
level
is less than or equal to the program's current verbosity level. If
the program's name has been supplied using prog_set_name(3), the message
will be preceeded by the name, a colon and a space. The message is also
preceeded by as many spaces as the message level. This indents messages
according to their verbosity. format
is a printf(3)-like format string
and processes any remaining arguments in the same way as printf(3). The
message is followed by a newline.
void vverbose(size_t level, const char *format, va_list args)
void debugf(size_t level, const char *format, ...)
level
satisfies the program's current debug level. The debug level is
broken into two components. The low byte specifies the level. The next three
bytes specify a section within which the level applies. Debug messages with
a section value whose bits overlap those of the program's current debug
section and with a level that is less than or equal to the program's current
debug level are emitted. As a convenience, if the program's current debug
section is zero, debug messages with a sufficiently small level are emitted
regardless of the message section. See prog_set_debug_level(3) for
examples. If the program's name has been supplied using prog_set_name(3),
the message will be preceeded by the name, a colon and a space. The message
is also preceeded by as many spaces as the debug level. This indents debug
messages according to their debug level. format
is a printf(3)-like
format string and processes any remaining arguments in the same way as
printf(3). The message is followed by a newline.
void vdebugf(size_t level, const char *format, va_list args)
int error(const char *format, ...)
format
is a
printf(3)-like format string and processes any remaining arguments in the
same way as printf(3). The message is followed by a newline. Returns -1.
int verror(const char *format, va_list args)
void fatal(const char *format, ...)
EXIT_FAILURE
. If the program's
name was supplied using prog_set_name(3), the message will be preceeded
by the name, a colon and a space. This is followed by the string "fatal:
"
. format
is a printf(3)-like format string and processes any
remaining arguments in the same way as printf(3). The message is followed
by a newline. Note: Never use this in a library. Only an application can
decide which errors are fatal.
void vfatal(const char *format, va_list args)
void dump(const char *format, ...)
"dump: "
. format
is a
printf(3)-like format string and processes any remaining arguments in the
same way as printf(3). The message is followed by a newline. Note:
Never use this in a library. Only an application can decide which errors are
fatal.
void vdump(const char *format, va_list args)
void alert(int priority, const char *format, ...)
priority
to the program's alert
message destination. If the program's name has been supplied using
prog_set_name(3), the message will be preceeded by the name, a colon and
a space. format
is a printf(3)-like format string and processes any
remaining arguments in the same way as printf(3). The message is followed
by a newline. Note that this only works when the program's alert message
destination is a simple syslog destination. If the alert message destination
is anything else (including a multiplexing message destination containing
syslog destinations), priority
is ignored.
void valert(int priority, const char *format, va_list args)
void debugsysf(size_t level, const char *format, ...)
errno
and a newline (rather than just
a newline).
void vdebugsysf(size_t level, const char *format, va_list args)
int errorsys(const char *format, ...)
errno
and a newline (rather than just
a newline).
int verrorsys(const char *format, va_list args)
void fatalsys(const char *format, ...)
errno
and a newline (rather than just
a newline).
void vfatalsys(const char *format, va_list args)
void dumpsys(const char *format, ...)
errno
and a newline (rather than just
a newline).
void vdumpsys(const char *format, va_list args)
void alertsys(int priority, const char *format, ...)
errno
and a newline (rather than just
a newline).
void valertsys(int priority, const char *format, va_list args)
int set_errno(int errnum)
errno
to errnum
and returns -1.
void *set_errnull(int errnum)
errno
to errnum
and returns null
.
#define debug(args)
NDEBUG
is defined. args
must be supplied
with extra parentheses. e.g.
debug((1, "rc=%d", rc))
#define vdebug(args)
NDEBUG
is defined. args
must be supplied
with extra parentheses. e.g.
vdebug((1, format, args))
#define debugsys(args)
NDEBUG
is defined. args
must be supplied
with extra parentheses. e.g.
debugsys((1, "fd=%d", fd))
#define vdebugsys(args)
NDEBUG
is defined. args
must be supplied
with extra parentheses. e.g.
vdebugsys((1, format, args))
#define check(cond, mesg)
mesg
, for including an
explanation of the condition tested and then calls dump(3) to terminate
the program. This means the message will be sent to the right place(s)
rather than just to stderr
. Note: Like assert(3), this function is
largely useless. It should never be left in production code (because it's
rude) so you need to write code to handle error conditions properly anyway.
You might as well not bother using assert(3) or check(3) in the first
place.
MT-Safe
libslack(3), msg(3), prog(3), printf(3)
20020916 raf <raf@raf.org>