A minimal and flexible logging framework written in C99. More...

#include <stdarg.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdio.h>

Include dependency graph for pico_log.h:

Macros
#define	log_trace(...) log_write(LOG_LEVEL_TRACE, __FILE__, __LINE__, __func__, __VA_ARGS__)
	Logs a TRACE an INFO message.

#define	log_debug(...) log_write(LOG_LEVEL_DEBUG, __FILE__, __LINE__, __func__, __VA_ARGS__)
	Logs a DEBUG message.

#define	log_info(...) log_write(LOG_LEVEL_INFO, __FILE__, __LINE__, __func__, __VA_ARGS__)
	Logs an INFO message.

#define	log_warn(...) log_write(LOG_LEVEL_WARN, __FILE__, __LINE__, __func__, __VA_ARGS__)
	Logs a WARN message.

#define	log_error(...) log_write(LOG_LEVEL_ERROR, __FILE__, __LINE__, __func__, __VA_ARGS__)
	Logs an ERROR message.

#define	log_fatal(...) log_write(LOG_LEVEL_FATAL, __FILE__, __LINE__, __func__, __VA_ARGS__)
	Logs a FATAL message.

Typedefs
typedef void(*	log_appender_fn) (const char entry, void udata)
	Appender function definition. An appender writes a log entry to an output stream. This could be the console, a file, a network connection, etc...

typedef void(*	log_appender_lock_fn) (bool lock, void *udata)
	Lock function definition. This is called during log_write.

typedef int	log_appender_t
	Identifies a registered appender.

Enumerations
enum	log_level_t { LOG_LEVEL_TRACE = 0 , LOG_LEVEL_DEBUG , LOG_LEVEL_INFO , LOG_LEVEL_WARN , LOG_LEVEL_ERROR , LOG_LEVEL_FATAL , LOG_LEVEL_COUNT }
	These codes allow different layers of granularity when logging. See the documentation of the `log_set_level` function for more information. More...

Functions
bool	log_str_to_level (const char str, log_level_t level)
	Converts a string to the corresponding log level.

void	log_enable (void)
	Enables logging. NOTE: Logging is enabled by default.

void	log_disable (void)
	Disables logging.

log_appender_t	log_add_appender (log_appender_fn appender_fp, log_level_t level, void *udata)
	Registers an appender.

log_appender_t	log_add_stream (FILE *stream, log_level_t level)
	Registers an output stream appender.

void	log_remove_appender (log_appender_t id)
	Unregisters appender (removes the appender from the logger).

void	log_enable_appender (log_appender_t id)
	Enables the specified appender. NOTE: Appenders are enabled by default after registration.

void	log_disable_appender (log_appender_t id)
	Disables the specified appender.

void	log_set_lock (log_appender_t id, log_appender_lock_fn lock_fp, void *udata)
	Sets the lock function for a given appender.

void	log_set_level (log_appender_t id, log_level_t level)
	Sets the logging level.

void	log_set_time_fmt (log_appender_t id, const char *fmt)
	Set the appender timestamp.

void	log_display_colors (log_appender_t id, bool enabled)
	Turns colors ouput on or off for the specified appender. NOTE: Off by default.

void	log_display_timestamp (log_appender_t id, bool enabled)
	Turns timestamp reporting on/off for the specified appender. NOTE: Off by default.

void	log_display_level (log_appender_t id, bool enabled)
	Turns log level reporting on/off for the specified appender. NOTE: On by default.

void	log_display_file (log_appender_t id, bool enabled)
	Turns filename and line number reporting on/off for the specified appender. NOTE: Off by default.

void	log_display_function (log_appender_t id, bool enabled)
	Turns function reporting on/off for the specified appender. NOTE: Off by default.

void	log_write (log_level_t level, const char file, unsigned line, const char func, const char *fmt,...)

Detailed Description

A minimal and flexible logging framework written in C99.

Licensing information at end of header

Features:

Written in pure C99, and compatible with C++
Single header library for easy integration into any build system
Tiny memory and code footprint
Simple and minimalistic API
Flexible and extensible appender handling
Ability to set logging level (TRACE, DEBUG, INFO, WARN, ERROR, and FATAL)
Ability to toggle date/time, log level, filename/line, and function
reporting individually, on a per appender basis
Permissive licensing (zlib or public domain)

Summary:

This library is built around the notion of appenders. An appender writes log messages to a sink. It could be a file, a network connection, or stream (e.g. stdout).

Once one or more appenders are registered, macros such as log_info will send messages to the appenders.

Output can be modified in a number of ways. The most important way to affect the output is to specify the log level (e.g. LOG_LEVEL_INFO). If the log level is set LOG_LEVEL_INFO, then messages sent to log_trace or log_debug will not be written whereas log_info, log_warn, log_error, and log_fatal will have no effect.

Output can also be modified to show or hide various metadata. These are date/time, log level, filename/line number, and calling function. They can be toggled using the log_display* functions. There is also an option to enable color coded output.

It is possible to synchronize appenders using log_set_lock. This function accepts a function pointer that takes a boolean and user data as input. If this function pointer is passed true the lock is acquired and false to release the lock.

Please see the examples for more details.

Usage:

To use this library in your project, add the following

‍#define PICO_LOG_IMPLEMENTATION #include "pico_log.h"

to a source file (once), then simply include the header normally.

Constants:

PICO_LOG_MAX_APPENDERS (default: 16)
PICO_LOG_MAX_MSG_LENGTH (default: 1024)

Must be defined before PICO_LOG_IMPLEMENTATION

Macro Definition Documentation

◆ log_trace

#define log_trace ( ... ) log_write(LOG_LEVEL_TRACE, __FILE__, __LINE__, __func__, __VA_ARGS__)

Logs a TRACE an INFO message.

Writes a TRACE level message to the log. Usage is similar to printf (i.e. log_trace(format, args...))

◆ log_debug

#define log_debug ( ... ) log_write(LOG_LEVEL_DEBUG, __FILE__, __LINE__, __func__, __VA_ARGS__)

Logs a DEBUG message.

Writes a DEBUG level message to the log. Usage is similar to printf (i.e. (i.e. log_debug(format, args...))

◆ log_info

#define log_info ( ... ) log_write(LOG_LEVEL_INFO, __FILE__, __LINE__, __func__, __VA_ARGS__)

Logs an INFO message.

Writes an INFO level message to the log. Usage is similar to printf (i.e. log_info(format, args...))

◆ log_warn

#define log_warn ( ... ) log_write(LOG_LEVEL_WARN, __FILE__, __LINE__, __func__, __VA_ARGS__)

Logs a WARN message.

Writes a WARN level message to the log. Usage is similar to printf (i.e. (i.e. log_warn(format, args...))

◆ log_error

#define log_error ( ... ) log_write(LOG_LEVEL_ERROR, __FILE__, __LINE__, __func__, __VA_ARGS__)

Logs an ERROR message.

Writes a ERROR level message to the log. Usage is similar to printf (i.e. (i.e. log_error(format, args...))

◆ log_fatal

#define log_fatal ( ... ) log_write(LOG_LEVEL_FATAL, __FILE__, __LINE__, __func__, __VA_ARGS__)

Logs a FATAL message.

Writes a FATAL level message to the log.. Usage is similar to printf (i.e. (i.e. log_fatal(format, args...))

Typedef Documentation

◆ log_appender_fn

typedef void(* log_appender_fn) (const char *entry, void *udata)

Appender function definition. An appender writes a log entry to an output stream. This could be the console, a file, a network connection, etc...

◆ log_appender_lock_fn

typedef void(* log_appender_lock_fn) (bool lock, void *udata)

Lock function definition. This is called during log_write.

Parameters

lock	True to lock, false to release the lock
udata	Data obtained from the corresponding `log_set_lock` function

◆ log_appender_t

typedef int log_appender_t

Identifies a registered appender.

Enumeration Type Documentation

◆ log_level_t

enum log_level_t

These codes allow different layers of granularity when logging. See the documentation of the log_set_level function for more information.

Enumerator
LOG_LEVEL_TRACE
LOG_LEVEL_DEBUG
LOG_LEVEL_INFO
LOG_LEVEL_WARN
LOG_LEVEL_ERROR
LOG_LEVEL_FATAL
LOG_LEVEL_COUNT

Function Documentation

◆ log_str_to_level()

bool log_str_to_level	(	const char *	str,
		log_level_t *	level
	)

Converts a string to the corresponding log level.

◆ log_enable()

void log_enable ( void )

Enables logging. NOTE: Logging is enabled by default.

◆ log_disable()

void log_disable ( void )

Disables logging.

◆ log_add_appender()

log_appender_t log_add_appender	(	log_appender_fn	appender_fp,
		log_level_t	level,
		void *	udata
	)

Registers an appender.

Adds appender to logger and enables the specified appender. An appender writes a log entry to an output stream. This could be a console, a file, a network connection, etc...

Parameters

appender_fp	Pointer to the appender function to register. An appender function has the signature, `void appender_func(const char* p_entry, void* p_udata)`
level	The appender's log level
udata	A pointer supplied to the appender function when writing a log entry. This pointer is not modified by the logger. If not required, pass in NULL for this parameter.

Returns: An identifier for the appender. This ID is valid until the appender is unregistered.

◆ log_add_stream()

log_appender_t log_add_stream	(	FILE *	stream,
		log_level_t	level
	)

Registers an output stream appender.

Parameters

stream	The output stream to write to
level	The appender's log level

Returns: An identifier for the appender. This ID is valid until the appender is unregistered.

◆ log_remove_appender()

void log_remove_appender ( log_appender_t id )

Unregisters appender (removes the appender from the logger).

Parameters

id	The appender to unregister

◆ log_enable_appender()

void log_enable_appender ( log_appender_t id )

Enables the specified appender. NOTE: Appenders are enabled by default after registration.

Parameters

id	The appender to enable.

◆ log_disable_appender()

void log_disable_appender ( log_appender_t id )

Disables the specified appender.

Parameters

id	The appender to disable

◆ log_set_lock()

void log_set_lock	(	log_appender_t	id,
		log_appender_lock_fn	lock_fp,
		void *	udata
	)

Sets the lock function for a given appender.

^

Parameters

lock_fp	The lock function pointer
id	The appender to hold the lock

◆ log_set_level()

void log_set_level	(	log_appender_t	id,
		log_level_t	level
	)

Sets the logging level.

Sets the logging level. Only those messages of equal or higher priority (severity) than this value will be logged.

Parameters

id	The appender
level	The new appender logging threshold.

◆ log_set_time_fmt()

void log_set_time_fmt	(	log_appender_t	id,
		const char *	fmt
	)

Set the appender timestamp.

Sets the appender timestamp format according to: https://man7.org/linux/man-pages/man3/strftime.3.html

Parameters

id	The appender id
fmt	The time format

◆ log_display_colors()

void log_display_colors	(	log_appender_t	id,
		bool	enabled
	)

Turns colors ouput on or off for the specified appender. NOTE: Off by default.

Parameters

id	The appender id
enabled	On if true

◆ log_display_timestamp()

void log_display_timestamp	(	log_appender_t	id,
		bool	enabled
	)

Turns timestamp reporting on/off for the specified appender. NOTE: Off by default.

Parameters

id	The appender id
enabled	On if true

◆ log_display_level()

void log_display_level	(	log_appender_t	id,
		bool	enabled
	)

Turns log level reporting on/off for the specified appender. NOTE: On by default.

Parameters

id	The appender id
enabled	On if true

◆ log_display_file()

void log_display_file	(	log_appender_t	id,
		bool	enabled
	)

Turns filename and line number reporting on/off for the specified appender. NOTE: Off by default.

Parameters

id	The appender id
enabled	On if true

◆ log_display_function()

void log_display_function	(	log_appender_t	id,
		bool	enabled
	)

Turns function reporting on/off for the specified appender. NOTE: Off by default.

Parameters

id	The appender id
enabled	On if true

◆ log_write()

void log_write	(	log_level_t	level,
		const char *	file,
		unsigned	line,
		const char *	func,
		const char *	fmt,
			...
	)

WARNING: It is inadvisable to call this function directly. Use the macros instead.

Macros

Typedefs

Enumerations

Functions

Detailed Description

Licensing information at end of header

Features:

Summary:

Usage:

Constants:

Macro Definition Documentation

◆ log_trace

◆ log_debug

◆ log_info

◆ log_warn

◆ log_error

◆ log_fatal

Typedef Documentation

◆ log_appender_fn

◆ log_appender_lock_fn

◆ log_appender_t

Enumeration Type Documentation

◆ log_level_t

Function Documentation

◆ log_str_to_level()

◆ log_enable()

◆ log_disable()

◆ log_add_appender()

◆ log_add_stream()

◆ log_remove_appender()

◆ log_enable_appender()

◆ log_disable_appender()

◆ log_set_lock()

◆ log_set_level()

◆ log_set_time_fmt()

◆ log_display_colors()

◆ log_display_timestamp()

◆ log_display_level()

◆ log_display_file()

◆ log_display_function()

◆ log_write()