CLOG(3)

NAME
clog - Copious Logger

SYNOPSIS
#include <clog.h>
void
clog_init(int no_syslog);
int
clog_set_flags(uint32_t flags);
uint32_t
clog_get_flags(void);
int
clog_set_logfile(const char *logfile);
const char *
clog_get_logfile(void);
void
clog_set_log_callback(void (*cb)(void *, int, int, const char *, va_list), void *state);
void
clog_set_mask(uint64_t mask);
uint64_t
clog_get_mask(void);
int
clog_mask_is_set(uint64_t bit);
void
clog_version(int *major, int *minor, int *patch);
void
CABORT(const char *format, ...);
void
CABORTX(const char *format, ...);
void
CALERT(const char *format, ...);
void
CALERTX(const char *format, ...);
void
CCRIT(const char *format, ...);
void
CCRITX(const char *format, ...);
void
CEMERG(const char *format, ...);
void
CEMERGX(const char *format, ...);
void
CERR(const char *format, ...);
void
CERRX(const char *format, ...);
void
CFATAL(const char *format, ...);
void
CFATALX(const char *format, ...);
void
CINFO(const char *format, ...);
void
CNINFO(uint64_t mask, const char *format, ...);
void
CDBG(const char *format, ...);
void
CNDBG(uint64_t mask, const char *format, ...);
void
CNOTICE(const char *format, ...);
void
CNNOTICE(uint64_t mask, const char *format, ...);
void
CWARN(const char *format, ...);
void
CNWARN(uint64_t mask, const char *format, ...);
void
CWARNX(const char *format, ...);
void
CNWARNX(uint64_t mask, const char *format, ...);

DESCRIPTION
clog_init() prepares the library for first use. This function should be called before any other function is called.

clog_set_flags() sets the operational flags for clog. Possible values are:
CLOG_F_FILE
    Log source file name.
CLOG_F_FUNC
    Log source function name.
CLOG_F_LINE
    Log source file line number.
CLOG_F_PID
    Log program name and PID.
CLOG_F_DATE
    Log date in ctime(3) format.
CLOG_F_DTIME
    Log delta time from previous log function invocation. This time delta has micro second resolution.
CLOG_F_FILOG
    Log to logfile which is given as an argument to clog_set_logfile(). The clog_set_logfile() function must be called before setting this flag.
CLOG_F_STDERR
    Log to stderr.
CLOG_F_SYSLOG
    Log to syslog(3). Note that syslog(3) always prepends the ctime(3) date. Currently all clog output goes to LOG_DAEMON.
CLOG_F_ENABLE
    Enable logging.
CLOG_F_DBGENABLE
    Enable debug logging.

Only supported flags can be set and this function will return 0 on success and 1 on failure. The currently set flags may be fetched with clog_get_flags().

clog_set_logfile() sets the log file to log to when CLOG_F_FILOG is set. This function must be called before setting CLOG_F_FILOG. The returned value is 0 on success and 1 on failure.

clog_set_mask() sets external debug mask. The debug mask must be a bitfield and must be defined by the caller. It is used to control what to log and what to skip. The current debug mask may be fetched with clog_get_mask(), alternatively whether a bit is set may be tested with clog_mask_is_set().

clog_set_log_callback() sets an optional logging callback and state pointer that will be used instead of internal logging functions to display the message. The callback takes as arguments the state pointer, current clog flags, message priority (as a syslog(3) priority), message and va_list of message parameters. To restore the default behaviour this function may be called with clog_default_log_callback() and NULL as the parameter.

clog_version() gets the current version of the library at run time.

All logging functions use the format as defined by printf(3). The N in the name of the logging functions designates the use of a mask. The functions for logging important messages ( CABORT() CALERT(), CCRIT(), CEMERG(), CERR() and CFATAL() ) do not have masked variants since they are intended only for important messages which should require no masking.

CALERT(), CCRIT(), CDBG(), CEMERG() CERR(), CINFO(), CNOTICE(), CWARN(), (and their masked counterparts where present) will log informational messages with severities corresponding to the well known syslog(3) levels if the CLOG_F_ENABLE flag is present and they are unmasked. The CDBG() family of functions additionally require the CLOG_F_DBGENABLE flag to be set.

CFATAL() and CFATALX() terminate the program using exit(3) with a non-zero return value.

CABORT() and CABORTX() terminate the program using abort(3)

The functions with an X in their name suppress strerror(3) output, and are functionally equivalent to the err(3) and warn(3) family of functions.

SEE ALSO
printf(3) ctime(3) syslog(3) err(3) warn(3)

HISTORY
-nosplit clog was written by Marco Peereboom <marco@peereboom.us>