log.h File Reference

#include "bool.h"
#include "msgpack.h"
#include <stdio.h>

Go to the source code of this file.

Data Structures
struct	backend_list_t
	an entry in the list of logging backends More...

Macros
#define	LOG_ORIGIN   __FILE__
	default origin. More...
Creating messages with specific log level
#define	attach_log_extra(attach, origin, ...)   attach_log_level_fmt(attach, LOG_LEVEL_EXTRADEBUG, origin, __VA_ARGS__)
#define	attach_log_debug(attach, origin, ...)   attach_log_level_fmt(attach, LOG_LEVEL_DEBUG, origin, __VA_ARGS__)
#define	attach_log_verbose(attach, origin, ...)   attach_log_level_fmt(attach, LOG_LEVEL_VERBOSE, origin, __VA_ARGS__)
#define	attach_log_info(attach, origin, ...)   attach_log_level_fmt(attach, LOG_LEVEL_INFO, origin, __VA_ARGS__)
#define	attach_log_warn(attach, origin, ...)   attach_log_level_fmt(attach, LOG_LEVEL_WARNING, origin, __VA_ARGS__)
#define	attach_log_error(attach, origin, ...)   attach_log_level_fmt(attach, LOG_LEVEL_ERROR, origin, __VA_ARGS__)
#define	attach_log_fatal(attach, origin, ...)   attach_log_level_fmt(attach, LOG_LEVEL_FATAL, origin, __VA_ARGS__)
#define	attach_log_enter(attach, origin, ...)   attach_log_level_fmt(attach, LOG_LEVEL_ENTER, origin, __VA_ARGS__)
#define	attach_log_leave(attach, origin, ...)   attach_log_level_fmt(attach, LOG_LEVEL_LEAVE, origin, __VA_ARGS__)
#define	log_extra(origin, ...)   log_level_fmt(LOG_LEVEL_EXTRADEBUG, origin, __VA_ARGS__)
#define	log_debug(origin, ...)   log_level_fmt(LOG_LEVEL_DEBUG, origin, __VA_ARGS__)
#define	log_verbose(origin, ...)   log_level_fmt(LOG_LEVEL_VERBOSE, origin, __VA_ARGS__)
#define	log_info(origin, ...)   log_level_fmt(LOG_LEVEL_INFO, origin, __VA_ARGS__)
#define	log_warn(origin, ...)   log_level_fmt(LOG_LEVEL_WARNING, origin, __VA_ARGS__)
#define	log_error(origin, ...)   log_level_fmt(LOG_LEVEL_ERROR, origin, __VA_ARGS__)
#define	log_fatal(origin, ...)   log_level_fmt(LOG_LEVEL_FATAL, origin, __VA_ARGS__)
#define	log_enter(origin, ...)   log_level_fmt(LOG_LEVEL_ENTER, origin, __VA_ARGS__)
#define	log_leave(origin, ...)   log_level_fmt(LOG_LEVEL_LEAVE, origin, __VA_ARGS__)
#define	log_separator(origin)   log_level(LOG_LEVEL_SEPARATOR, origin, NULL)
#define	log_check(origin, id)   log_level(LOG_LEVEL_CHECKPOINT, origin, id)
Logging shortcuts that auto-insert LOG_ORIGIN into the "origin" field
#define	attach_extra(attach, ...)   attach_log_extra(attach, LOG_ORIGIN, __VA_ARGS__)
#define	attach_debug(attach, ...)   attach_log_debug(attach, LOG_ORIGIN, __VA_ARGS__)
#define	attach_verbose(attach, ...)   attach_log_verbose(attach, LOG_ORIGIN, __VA_ARGS__)
#define	attach_info(attach, ...)   attach_log_info(attach, LOG_ORIGIN, __VA_ARGS__)
#define	attach_warn(attach, ...)   attach_log_warn(attach, LOG_ORIGIN, __VA_ARGS__)
#define	attach_error(attach, ...)   attach_log_error(attach, LOG_ORIGIN, __VA_ARGS__)
#define	attach_fatal(attach, ...)   attach_log_fatal(attach, LOG_ORIGIN, __VA_ARGS__)
#define	attach_enter(attach, ...)   attach_log_enter(attach, LOG_ORIGIN, __VA_ARGS__)
#define	attach_leave(attach, ...)   attach_log_leave(attach, LOG_ORIGIN, __VA_ARGS__)
#define	attach_check(attach, id)   attach_log_check(attach, LOG_ORIGIN, id)
#define	extra(...)   log_extra(LOG_ORIGIN, __VA_ARGS__)
#define	debug(...)   log_debug(LOG_ORIGIN, __VA_ARGS__)
#define	verbose(...)   log_verbose(LOG_ORIGIN, __VA_ARGS__)
#define	info(...)   log_info(LOG_ORIGIN, __VA_ARGS__)
#define	warn(...)   log_warn(LOG_ORIGIN, __VA_ARGS__)
#define	error(...)   log_error(LOG_ORIGIN, __VA_ARGS__)
#define	fatal(...)   log_fatal(LOG_ORIGIN, __VA_ARGS__)
#define	enter(...)   log_enter(LOG_ORIGIN, __VA_ARGS__)
#define	leave(...)   log_leave(LOG_ORIGIN, __VA_ARGS__)
#define	separator()   log_separator(LOG_ORIGIN)
#define	check(id)   log_check(LOG_ORIGIN, id)
#define	scratch(key, value)   log_scratch(LOG_ORIGIN, key, value)

Typedefs
typedef void	backend_callback_t(msgpack_sbuffer *logmsg, LOG_LEVEL level, void *userptr)
	prototype for a logging backend callback function
typedef void	backend_command_t(LOG_NOTIFY reason, void *userptr)
	prototype for a logging backend "command"/notification function

Enumerations
enum	LOG_LEVEL {   LOG_LEVEL_EXTRADEBUG, LOG_LEVEL_DEBUG, LOG_LEVEL_VERBOSE, LOG_LEVEL_INFO,   LOG_LEVEL_WARNING, LOG_LEVEL_ERROR, LOG_LEVEL_FATAL, LOG_LEVEL_ENTER,   LOG_LEVEL_LEAVE, LOG_LEVEL_PAUSE, LOG_LEVEL_RESUME, LOG_LEVEL_SEPARATOR,   LOG_LEVEL_CLEAR, LOG_LEVEL_CHECKPOINT, LOG_LEVEL_SCRATCHPAD }
	logging levels ("verbosity") More...
enum	LOG_NOTIFY { LOG_NOTIFY_SETLEVEL, LOG_NOTIFY_SHUTDOWN }
	(internal) logging backend notifications More...

Functions
void	log_register_backend (backend_callback_t *callback, backend_command_t *notify, void *userptr)
	Add a callback function to the list of logging backends. More...
void	log_unregister_backend (backend_callback_t *callback, void *userptr)
	Remove a callback function from the list of logging backends.
void	log_shutdown (void)
	Notify all the logging backends of impending shutdown. More...
void	log_reset (bool with_checkpoints)
	Reset (internal) log system variables. More...
const char *	log_level_string (LOG_LEVEL level)
	return string representation of a LOG_LEVEL
'Core' logging that all other functions/macros use
void	attach_log_level (msgpack_object *attachment, LOG_LEVEL level, const char *origin, const char *msg, int len)
	Create a simple log message with an attachment. More...
void	attach_log_level_ap (msgpack_object *attachment, LOG_LEVEL level, const char *origin, const char *fmt, va_list ap)
	printf-style creation of a log message with attachment, using format string and a vararg list. More...
void	attach_log_level_fmt (msgpack_object *attachment, LOG_LEVEL level, const char *origin, const char *fmt,...)
	vararg wrapper for attach_log_level_ap()

Log functions not using an attachment
#define	log_level(level, origin, msg)   attach_log_level(NULL, level, origin, msg, -1)
#define	log_level_ap(level, origin, fmt, ap)   attach_log_level_ap(NULL, level, origin, fmt, ap)
#define	log_level_fmt(level, origin, ...)   attach_log_level_fmt(NULL, level, origin, __VA_ARGS__)
void	log_scratch (const char *origin, const char *key, const char *value)
	"scratchpad" message logging a key-value pair

Macro Definition Documentation

#define LOG_ORIGIN   __FILE__

default origin.

You may (pre)define LOG_ORIGIN to a string that describes the log message source (e.g. the module). It's also possible to define this to NULL. If you don't pass a value yourself, it will default to the current filename.

#define LOG_ORIGIN "foobar"
#include "log.h"

Enumeration Type Documentation

enum LOG_LEVEL

logging levels ("verbosity")

Enumerator
LOG_LEVEL_EXTRADEBUG	"extra" debugging (more verbose than LOG_LEVEL_DEBUG)
LOG_LEVEL_DEBUG	debugging log level
LOG_LEVEL_VERBOSE	verbose, more output than LOG_LEVEL_INFO
LOG_LEVEL_INFO	"standard" (informational) log messages
LOG_LEVEL_WARNING	warning
LOG_LEVEL_ERROR	error
LOG_LEVEL_FATAL	fatal error (might terminate execution)
LOG_LEVEL_ENTER	enter scope (e.g. function) / increase nesting level
LOG_LEVEL_LEAVE	leave scope (e.g. function) / decrease nesting level
LOG_LEVEL_PAUSE	may be used (if implemented) to pause logging output
LOG_LEVEL_RESUME	may be used (if implemented) to resume logging output
LOG_LEVEL_SEPARATOR	may be used (if implemented) to show a separator
LOG_LEVEL_CLEAR	may be used (if implemented) to clear a backlog / console
LOG_LEVEL_CHECKPOINT	check point, shows ID and an automatic pass count
LOG_LEVEL_SCRATCHPAD	arbitrary key-value pairs, presented in a viewer-specific way

enum LOG_NOTIFY

(internal) logging backend notifications

Enumerator
LOG_NOTIFY_SETLEVEL	notify backends to apply new logging/verbosity level
LOG_NOTIFY_SHUTDOWN	inform backends on removal, or log system shutdown

Function Documentation

void attach_log_level	(	msgpack_object *	attachment,
		LOG_LEVEL	level,
		const char *	origin,
		const char *	msg,
		int	len
	)

Create a simple log message with an attachment.

Parameters

attachment	pointer to an arbitrary MessagePack object to 'attach'. The object gets serialized and transferred along with the log message. optional, may be NULL
level	the LOG_LEVEL to use for the message
origin	a string indicating the message source (e.g. module name). optional, may be NULL
msg	the actual message string
len	length of the message string (excluding terminating NUL). You can pass len < 0, to use strlen(msg) instead.

void attach_log_level_ap	(	msgpack_object *	attachment,
		LOG_LEVEL	level,
		const char *	origin,
		const char *	fmt,
		va_list	ap
	)

printf-style creation of a log message with attachment, using format string and a vararg list.

Parameters

attachment	pointer to an arbitrary MessagePack object to 'attach'. The object gets serialized and transferred along with the log message. optional, may be NULL
level	the LOG_LEVEL to use for the message
origin	a string indicating the message source (e.g. module name). optional, may be NULL
fmt	printf-style format string
ap	variable argument list, see <stdarg.h>

void log_register_backend	(	backend_callback_t *	callback,
		backend_command_t *	notify,
		void *	userptr
	)

Add a callback function to the list of logging backends.

Parameters

callback	function for actual logging
notify	(internal) notification function. optional, may be NULL
userptr	arbitrary "user" data (pointer) that will be passed to the callbacks. optional, may be NULL

void log_reset

(

bool

with_checkpoints

)

Reset (internal) log system variables.

This restores a zero indentation level, and optionally clears the checkpoint pass counters (if with_checkpoints is set).

void log_shutdown

(

void

)

Notify all the logging backends of impending shutdown.

This is to give backends the opportunity to flush any outstanding messages, and to free up resources before the log system terminates.