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);
void (*(set_errnullf)(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, ...)Outputs a message to the program's normal message destination. 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)Equivalent to msg(3) with the variable argument list specified directly as for vprintf(3).
void verbose(size_t level, const char *format, ...)Outputs a verbose message to the program's normal message destination if
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 preceded by the name, a colon and a space. The message is also
preceded 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)Equivalent to verbose(3) with the variable argument list specified directly as for vprintf(3).
void debugf(size_t level, const char *format, ...)Outputs a debug message to the program's debug message destination if
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 preceded by the name, a colon and a space. The message
is also preceded 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)Equivalent to debugf(3) with the variable argument list specified directly as for vprintf(3).
int error(const char *format, ...)Outputs an error message to the program's error message destination. If the
program's name has been supplied using prog_set_name(3), the message will
be preceded 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. Returns -1.
int verror(const char *format, va_list args)Equivalent to error(3) with the variable argument list specified directly as for vprintf(3).
void fatal(const char *format, ...)Outputs an error message to the program's error message destination and then
calls exit(3) with a return code of EXIT_FAILURE. If the program's
name was supplied using prog_set_name(3), the message will be preceded
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)Equivalent to fatal(3) with the variable argument list specified directly as for vprintf(3).
void dump(const char *format, ...)Outputs an error message to the program's error message destination and then
calls abort(3). If the program's name was supplied using
prog_set_name(3), the message will be preceded by the name, a colon and
a space. This is followed by the string "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)Equivalent to dump(3) with the variable argument list specified directly as for vprintf(3).
void alert(int priority, const char *format, ...)Outputs an alert message of the given 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 preceded 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)Equivalent to alert(3) with the variable argument list specified directly as for vprintf(3).
void debugsysf(size_t level, const char *format, ...)Equivalent to debugf(3) except that the message is followed by a colon, a
space, the string representation of errno and a newline (rather than just
a newline).
void vdebugsysf(size_t level, const char *format, va_list args)Equivalent to debugsysf(3) with the variable argument list specified directly as for vprintf(3).
int errorsys(const char *format, ...)Equivalent to error(3) except that the message is followed by a colon, a
space, the string representation of errno and a newline (rather than just
a newline).
int verrorsys(const char *format, va_list args)Equivalent to errorsys(3) with the variable argument list specified directly as for vprintf(3).
void fatalsys(const char *format, ...)Equivalent to fatal(3) except that the message is followed by a colon, a
space, the string representation of errno and a newline (rather than just
a newline).
void vfatalsys(const char *format, va_list args)Equivalent to fatalsys(3) with the variable argument list specified directly as for vprintf(3).
void dumpsys(const char *format, ...)Equivalent to dump(3) except that the message is followed by a colon, a
space, the string representation of errno and a newline (rather than just
a newline).
void vdumpsys(const char *format, va_list args)Equivalent to dumpsys(3) with the variable argument list specified directly as for vprintf(3).
void alertsys(int priority, const char *format, ...)Equivalent to alert(3) except that the message is followed by a colon, a
space, the string representation of errno and a newline (rather than just
a newline).
void valertsys(int priority, const char *format, va_list args)Equivalent to alertsys(3) with the variable argument list specified directly as for vprintf(3).
int set_errno(int errnum)Sets errno to errnum and returns -1.
void *set_errnull(int errnum)Sets errno to errnum and returns null.
void (*set_errnullf(int errnum))()Sets errno to errnum and returns null as a function pointer.
This is useful because ISO C doesn't like casting normal pointers
into function pointers.
#define debug(args)Calls debugf(3) unless NDEBUG is defined. args must be supplied
with extra parentheses. e.g.
debug((1, "rc=%d", rc))
#define vdebug(args)Calls vdebugf(3) unless NDEBUG is defined. args must be supplied
with extra parentheses. e.g.
vdebug((1, format, args))
#define debugsys(args)Calls debugsysf(3) unless NDEBUG is defined. args must be supplied
with extra parentheses. e.g.
debugsys((1, "fd=%d", fd))
#define vdebugsys(args)Calls vdebugsysf(3) unless NDEBUG is defined. args must be supplied
with extra parentheses. e.g.
vdebugsys((1, format, args))
#define check(cond, mesg)Like assert(3) but includes a string argument, 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
Send a range of messages to default locations:
#include <slack/std.h>
#include <slack/prog.h>
#include <slack/err.h>
int main(int ac, char **av)
{
prog_init();
prog_set_debug_level(1);
prog_set_verbosity_level(1);
msg("This is a %s\n", "message");
verbose(0, "This is a %s message (level %d)", "verbose", 0);
verbose(1, "This is a %s message (level %d)", "verbose", 1);
verbose(2, "This is a %s message (level %d)", "verbose", 2);
debug((0, "This is a %s message (level %d)", "debug", 0))
debug((1, "This is a %s message (level %d)", "debug", 1))
debug((2, "This is a %s message (level %d)", "debug", 2))
alert(LOG_ERR, "This is an %s message", "alert");
error("This is an %s message", "error");
fatal("This is a %s message", "fatal error");
return EXIT_SUCCESS;
}
libslack(3), msg(3), prog(3), printf(3)
20100612 raf <raf@raf.org>