NAME

libslack(err) - message/error/debug/verbosity messaging module


SYNOPSIS

    #include <slack/err.h>

    void msg(const char *fmt, ...);
    void vmsg(const char *fmt, va_list args);
    void verbose(size_t level, const char *fmt, ...);
    void vverbose(size_t level, const char *fmt, va_list args);
    void debugf(size_t level, const char *fmt, ...);
    void vdebugf(size_t level, const char *fmt, va_list args);
    int error(const char *fmt, ...);
    int verror(const char *fmt, va_list args);
    void fatal(const char *fmt, ...);
    void vfatal(const char *fmt, va_list args);
    void dump(const char *fmt, ...);
    void vdump(const char *fmt, va_list args);
    void debugsysf(size_t level, const char *fmt, ...);
    void vdebugsysf(size_t level, const char *fmt, va_list args);
    int errorsys(const char *fmt, ...);
    int verrorsys(const char *fmt, va_list args);
    void fatalsys(const char *fmt, ...);
    void vfatalsys(const char *fmt, va_list args);
    void dumpsys(const char *fmt, ...);
    void vdumpsys(const char *fmt, va_list args);
    int set_errno(int errnum);

    #define debug(args)
    #define vdebug(args)
    #define debugsys(args)
    #define vdebugsys(args)
    #define check(test, msg)


DESCRIPTION

This module works with the prog and msg 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 and dump messages. All messages are created and sent with printf-like syntax. The destinations for these messages are configurable by the client. Calling prog_init() causes normal and verbose messages to be sent to standard output; debug, error, fatal error and dump messages to be sent to standard error.

Calls to prog_out_fd(), prog_out_stdout(), prog_out_file(), prog_out_syslog(), prog_out_none() cause normal and verbose messages to be sent to the specified destination. Calls to prog_err_fd(), prog_err_stderr(), prog_err_file(), prog_err_syslog(), prog_err_none() cause error, fatal error and dump messages to be sent to the specified destination. Calls to prog_dbg_fd(), prog_dbg_stdout(), prog_dbg_stderr(), prog_dbg_file(), prog_dbg_syslog(), prog_dbg_none() cause debug messages to be sent to the specified destination. Calls to the generic functions prog_set_out(), prog_set_err() and prog_set_dbg() 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 *fmt, ...)

Outputs a message to the program's normal message destination. fmt is a printf-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 fmt 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 *fmt, va_list args)

Equivalent to msg() with the variable argument list specified directly as for vprintf(3).

void verbose(size_t level, const char *fmt, ...)

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(), 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. fmt is a printf-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 *fmt, va_list args)

Equivalent to verbose() with the variable argument list specified directly as for vprintf(3).

void debugf(size_t level, const char *fmt, ...)

Outputs a debug message to the program's debug message destination if level is less than or equal to the current program debug level. If the program's name has been supplied using prog_set_name(), 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 debug messages according to their debug level. fmt is a printf-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 *fmt, va_list args)

Equivalent to debugf() with the variable argument list specified directly as for vprintf(3).

int error(const char *fmt, ...)

Outputs an error message to the program's error message destination. If the program's name has been supplied using prog_set_name(), the message will be preceeded by the name, a colon and a space. fmt is a printf-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 *fmt, va_list args)

Equivalent to error() with the variable argument list specified directly as for vprintf(3).

void fatal(const char *fmt, ...)

Outputs an error message to the program's error message destination and then calls exit(3) with a return code of 1. If the program's name was supplied using prog_set_name(), the message will be preceeded by the name, a colon and a space. This is followed by the string "fatal: ". fmt is a printf-like format string and processes any remaining arguments in the same way as printf(3). The message is followed by a newline.

void vfatal(const char *fmt, va_list args)

Equivalent to fatal() with the variable argument list specified directly as for vprintf(3).

void dump(const char *fmt, ...)

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(), the message will be preceeded by the name, a colon and a space. This is followed by the string "dump: ". fmt is a printf-like format string and processes any remaining arguments in the same way as printf(3). The message is followed by a newline.

void vdump(const char *fmt, va_list args)

Equivalent to dump() with the variable argument list specified directly as for vprintf(3).

void debugsysf(size_t level, const char *fmt, ...)

Outputs a debug message to the program's debug message destination if level is less than or equal to the current program debug level. If the program's name has been supplied using prog_set_name(), 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 debug messages according to their debug level. fmt is a printf-like format string and processes any remaining arguments in the same way as printf(3). The message is followed by a colon, a space, the string representation of errno and a newline.

void vdebugsysf(size_t level, const char *fmt, value args)

Equivalent to debugsysf() with the variable argument list specified directly as for vprintf(3).

int errorsys(const char *fmt, ...)

Outputs an error message to the program's error message destination. If the program's name has been supplied using prog_set_name(), the message will be preceeded by the name, a colon and a space. fmt is a printf-like format string and processes any remaining arguments in the same way as printf(3). The message is followed by a colon, a space, the string representation of errno and a newline. Returns -1.

int verrorsys(const char *fmt, va_list args)

Equivalent to errorsys() with the variable argument list specified directly as for vprintf(3).

void fatalsys(const char *fmt, ...)

Outputs an error message to the program's error message destination and then calls exit(3) with a return code of 1. If the program's name was supplied using prog_set_name(), the message will be preceeded by the name, a colon and a space. This is followed by the string "fatal: ". fmt is a printf-like format string and processes any remaining arguments in the same way as printf(3). The message is followed by a colon, a space, the string representation of errno and a newline.

void vfatalsys(const char *fmt, va_list args)

Equivalent to fatalsys() with the variable argument list specified directly as for vprintf(3).

void dumpsys(const char *fmt, ...)

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(), the message will be preceeded by the name, a colon and a space. This is followed by the string "dump: ". fmt is a printf-like format string and processes any remaining arguments in the same way as printf(3). The message is followed by a colon, a space, the string representation of errno and a newline.

void vdumpsys(const char *fmt, va_list args)

Equivalent to dumpsys() with the variable argument list specified directly as for vprintf(3).

int set_errno(int errnum)

Sets errno to errnum and returns -1.

#define debug(args)

Calls debugf() unless NDEBUG is defined. args must be supplied with extra parentheses. (e.g. debug((1, "rc=%d", rc))).

#define vdebug(args)

Calls vdebugf() unless NDEBUG is defined. args must be supplied with extra parentheses. (e.g. vdebug((1, fmt, args))).

#define debugsys(args)

Calls debugsysf() unless NDEBUG is defined. args must be supplied with extra parentheses. (e.g. debugsys((1, "fd=%d", fd))).

#define vdebugsys(args)

Calls vdebugsysf() unless NDEBUG is defined. args must be supplied with extra parentheses. (e.g. vdebugsys((1, fmt, args))).

#define check(test, msg)

Like assert() but includes a msg argument for including an explanation of the test and it calls dump() to terminate the program so that the output of the assertion failure message will be sent to the right place.


MT-Level

MT-Safe


SEE ALSO

libslack(3), msg(3), prog(3), printf(3)


AUTHOR

20010215 raf <raf@raf.org>