Log

Overview

Levelled messages for people reading a terminal or a log file.

• Each call writes one line, LEVEL file:line: message, with the level coloured when the output supports it.
• Calls below the runtime level, set with log_set_level(), return before evaluating their arguments. Calls below LOG_LEVEL_MIN compile to nothing.
• Each line goes out in one fwrite, so lines from different threads do not interleave. Set the level and output before starting threads.
• log_fatal() and log_assert() write, flush and abort, whatever the level.

log_set_level(LOG_TRACE);
log_info("loaded %d records", 3);
log_debug("cache hit rate %.2f", 0.75);
log_trace("compiled out here, by LOG_LEVEL_MIN");

Colour

log_color_enabled() follows the conventions other command-line tools use:

• NO_COLOR set to anything non-empty turns colour off. It wins over everything else (https://no-color.org).
• CLICOLOR_FORCE or FORCE_COLOR set to anything but empty or 0 turns colour on, even when the output is a pipe or a file.
• Otherwise colour is on when the stream is a terminal and TERM is set and is not dumb.

bool color = log_color_enabled(stderr);
const char *ok = color ? LOG_GREEN "ok" LOG_RESET : "ok";

Levels and output
What gets written, and where.
enum	LogLevel {   LOG_TRACE , LOG_DEBUG , LOG_INFO , LOG_WARN ,   LOG_ERROR , LOG_FATAL }
	How much a message matters, from chattiest to most severe. More...
void	log_set_level (LogLevel level)
	Drop messages below level from now on.
void	log_set_output (FILE *f)
	Write messages to f from now on.
#define	LOG_LEVEL_MIN   LOG_TRACE
	Calls below this level compile to nothing.

Colour
Decide whether to colour output, and the escapes to do it with.
bool	log_color_enabled (FILE *f)
	True when colour escapes written to f will render as colour.
#define	LOG_RED   "\x1b[31m"
	Red text.
#define	LOG_GREEN   "\x1b[32m"
	Green text.
#define	LOG_YELLOW   "\x1b[33m"
	Yellow text.
#define	LOG_RESET   "\x1b[0m"
	Back to the terminal's default style.

Logging
Each macro takes a printf format and its arguments, which the compiler checks.
#define	log_trace(...)
	Log a printf-style message at LOG_TRACE.
#define	log_debug(...)
	Log a printf-style message at LOG_DEBUG.
#define	log_info(...)
	Log a printf-style message at LOG_INFO.
#define	log_warn(...)
	Log a printf-style message at LOG_WARN.
#define	log_error(...)
	Log a printf-style message at LOG_ERROR.
#define	log_fatal(...)
	Log a printf-style message at LOG_FATAL, flush, and abort.
#define	log_assert(cond)
	Abort through log_fatal() when cond is false.

Macro Definition Documentation

LOG_LEVEL_MIN

#define LOG_LEVEL_MIN   LOG_TRACE

Calls below this level compile to nothing.

Define it before the first include of log.h, for example -DLOG_LEVEL_MIN=LOG_INFO.

Definition at line 52 of file log.h.

log_trace

#define log_trace

(

...

)

Value:

LOG_AT_(LOG_TRACE, __VA_ARGS__)

Log a printf-style message at LOG_TRACE.

Definition at line 68 of file log.h.

log_debug

#define log_debug

(

...

)

Value:

LOG_AT_(LOG_DEBUG, __VA_ARGS__)

Log a printf-style message at LOG_DEBUG.

Definition at line 70 of file log.h.

log_info

#define log_info

(

...

)

Value:

LOG_AT_(LOG_INFO, __VA_ARGS__)

Log a printf-style message at LOG_INFO.

Definition at line 72 of file log.h.

log_warn

#define log_warn

(

...

)

Value:

LOG_AT_(LOG_WARN, __VA_ARGS__)

Log a printf-style message at LOG_WARN.

Definition at line 74 of file log.h.

log_error

#define log_error

(

...

)

Value:

LOG_AT_(LOG_ERROR, __VA_ARGS__)

Log a printf-style message at LOG_ERROR.

Definition at line 76 of file log.h.

log_fatal

#define log_fatal

(

...

)

Value:

log_fatal_(__FILE__, __LINE__, __VA_ARGS__)

Log a printf-style message at LOG_FATAL, flush, and abort.

Definition at line 78 of file log.h.

log_assert

#define log_assert

(

cond

)

Value:

((cond) ? (void)0                                                          \
        : log_fatal_(__FILE__, __LINE__, "assertion failed: %s", #cond))

Abort through log_fatal() when cond is false.

Unlike assert(), it stays in release builds.

Definition at line 81 of file log.h.

LOG_RED

#define LOG_RED   "\x1b[31m"

Red text.

Definition at line 97 of file log.h.

LOG_GREEN

#define LOG_GREEN   "\x1b[32m"

Green text.

Examples

main.c.

Definition at line 98 of file log.h.

LOG_YELLOW

#define LOG_YELLOW   "\x1b[33m"

Yellow text.

Definition at line 99 of file log.h.

LOG_RESET

#define LOG_RESET   "\x1b[0m"

Back to the terminal's default style.

Examples

main.c.

Definition at line 100 of file log.h.

Enumeration Type Documentation

LogLevel

enum LogLevel

How much a message matters, from chattiest to most severe.

Enumerator
LOG_TRACE	Step-by-step detail, usually off.
LOG_DEBUG	Detail for whoever is debugging.
LOG_INFO	Normal progress worth recording. The default level.
LOG_WARN	Something odd that the program survived.
LOG_ERROR	An operation failed.
LOG_FATAL	The program cannot continue.

Definition at line 40 of file log.h.

Function Documentation

log_set_level()

void log_set_level

(

LogLevel

level

)

Drop messages below level from now on.

Definition at line 22 of file log.c.

log_set_output()

void log_set_output

(

FILE *

f

)

Write messages to f from now on.

Null means stderr, the default.

Definition at line 26 of file log.c.

log_color_enabled()

bool log_color_enabled

(

FILE *

f

)

True when colour escapes written to f will render as colour.

Reads the environment on every call, so call it once and keep the answer.

Definition at line 37 of file log.c.