NAME

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

SYNOPSIS

#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)

DESCRIPTION

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; and 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 which 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 vulnerabilities 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 which 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. This is followed by the string "debug:". If level specifies a non-zero section, it is included in the debug message, after a space and surrounded by square brackets. This is followed 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 which 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 which 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 which 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 which 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 which 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))

Note that the debug() macro always generates its own semicolon. This used to only be the case when NDEBUG was not defined, but it is now consistent.

#define vdebug(args)

Calls vdebugf(3) unless NDEBUG is defined. args must be supplied with extra parentheses. e.g.

vdebug((1, format, args))

Note that the vdebug() macro always generates its own semicolon. This used to only be the case when NDEBUG was not defined, but it is now consistent.

#define debugsys(args)

Calls debugsysf(3) unless NDEBUG is defined. args must be supplied with extra parentheses. e.g.

debugsys((1, "fd=%d", fd))

Note that the debugsys() macro always generates its own semicolon. This used to only be the case when NDEBUG was not defined, but it is now consistent.

#define vdebugsys(args)

Calls vdebugsysf(3) unless NDEBUG is defined. args must be supplied with extra parentheses. e.g.

vdebugsys((1, format, args))

Note that the vdebugsys() macro always generates its own semicolon. This used to only be the case when NDEBUG was not defined, but it is now consistent.

#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-Level

MT-Safe

EXAMPLES

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;
}

SEE ALSO

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

AUTHOR

20230824 raf <raf@raf.org>