Logging

Macros
#define	BJ_MAXIMUM_LOG_LEN   120
#define	bj_log_msg(LEVEL, ...)
#define	bj_trace(...)
#define	bj_debug(...)
#define	bj_info(...)
#define	bj_warn(...)
#define	bj_err(...)
#define	bj_fatal(...)

Enumerations
enum	bj_log_level {   BJ_LOG_TRACE , BJ_LOG_DEBUG , BJ_LOG_INFO , BJ_LOG_WARN ,   BJ_LOG_ERROR , BJ_LOG_FATAL }

Functions
const char *	bj_get_log_level_string (int level)
void	bj_set_log_level (int level)
int	bj_get_log_level (void)
size_t	bj_log_message (int level, const char *file, int line, const char *format,...)

Detailed Description

Logging utility functions.

Macro Definition Documentation

bj_debug

#define bj_debug

(

...

)

Value:

bj_log_msg(DEBUG, __VA_ARGS__)

Log a message using the BJ_LOG_DEBUG level.

The function effectively calls bj_log_message, forwarding arguments to format the input string.

This function is preferred over calling bj_log_msg of bj_log_message directly for clarity.

Parameters

...	The string formatting, forwarded to the last arguments of bj_log_message.

See also

bj_trace, bj_trace, bj_debug, bj_info, bj_warn, bj_err, bj_fatal. Log using BJ_LOG_DEBUG level.

bj_err

#define bj_err

(

...

)

Value:

bj_log_msg(ERROR, __VA_ARGS__)

Log a message using the BJ_LOG_ERROR level.

The function effectively calls bj_log_message, forwarding arguments to format the input string.

This function is preferred over calling bj_log_msg of bj_log_message directly for clarity.

Parameters

...	The string formatting, forwarded to the last arguments of bj_log_message.

See also

bj_warn, bj_trace, bj_debug, bj_info, bj_warn, bj_err, bj_fatal. Log using BJ_LOG_ERROR level.

bj_fatal

#define bj_fatal

(

...

)

Value:

bj_log_msg(FATAL, __VA_ARGS__)

Log a message using the BJ_LOG_FATAL level.

The function effectively calls bj_log_message, forwarding arguments to format the input string.

This function is preferred over calling bj_log_msg of bj_log_message directly for clarity.

Parameters

...	The string formatting, forwarded to the last arguments of bj_log_message.

See also

bj_err, bj_trace, bj_debug, bj_info, bj_warn, bj_err, bj_fatal. Log using BJ_LOG_FATAL level.

bj_info

#define bj_info

(

...

)

Value:

bj_log_msg(INFO, __VA_ARGS__)

Log a message using the BJ_LOG_INFO level.

The function effectively calls bj_log_message, forwarding arguments to format the input string.

This function is preferred over calling bj_log_msg of bj_log_message directly for clarity.

Parameters

...	The string formatting, forwarded to the last arguments of bj_log_message.

See also

bj_debug, bj_trace, bj_debug, bj_info, bj_warn, bj_err, bj_fatal. Log using BJ_LOG_INFO level.

bj_log_msg

#define bj_log_msg	(		LEVEL,
			... )

Value:

bj_log_message(BJ_LOG_ ## LEVEL, 0, 0, __VA_ARGS__)

Log a message using the given level LEVEL.

Any integer value can be used for LEVEL, but usually any of BJ_LOG_TRACE, BJ_LOG_DEBUG, BJ_LOG_INFO, BJ_LOG_WARN, BJ_LOG_ERROR or BJ_LOG_FATAL is used.

When a message is sent with a given level, it will be reported only if the value set with bj_set_log_level is at least the same value.

The function effectively calls bj_log_message, forwarding arguments to format the input string.

Parameters

LEVEL	The log level to report the message in.
...	Arguments forwarded to bj_log_message.

See also

bj_log_message, bj_trace, bj_debug, bj_info, bj_warn, bj_err, bj_fatal.

BJ_MAXIMUM_LOG_LEN

#define BJ_MAXIMUM_LOG_LEN   120

Maximum length of log messages.

Log messages, including header information such as timestamp and log level, cannot have a size in bytes larger than BJ_MAXIMUM_LOG_LEN, excluding the null character. In case a message is longer than this limit, the content is truncated in order of priority as described in bj_log_message.

bj_trace

#define bj_trace

(

...

)

Value:

bj_log_msg(TRACE, __VA_ARGS__)

Log a message using the BJ_LOG_TRACE level.

The function effectively calls bj_log_message, forwarding arguments to format the input string.

This function is preferred over calling bj_log_msg of bj_log_message directly for clarity.

Parameters

...	The string formatting, forwarded to the last arguments of bj_log_message.

See also

bj_log_msg, bj_trace, bj_debug, bj_info, bj_warn, bj_err, bj_fatal. Log using BJ_LOG_TRACE level.

bj_warn

#define bj_warn

(

...

)

Value:

bj_log_msg(WARN, __VA_ARGS__)

Log a message using the BJ_LOG_WARN level.

The function effectively calls bj_log_message, forwarding arguments to format the input string.

This function is preferred over calling bj_log_msg of bj_log_message directly for clarity.

Parameters

...	The string formatting, forwarded to the last arguments of bj_log_message.

See also

bj_info, bj_trace, bj_debug, bj_info, bj_warn, bj_err, bj_fatal. Log using BJ_LOG_WARN level.

Enumeration Type Documentation

bj_log_level

enum bj_log_level

Log Levels.

Level values are ordered from 0.

Enumerator
BJ_LOG_TRACE	Fine-grained diagnostic details.
BJ_LOG_DEBUG	Detailed information for debugging.
BJ_LOG_INFO	Informational messages about execution.
BJ_LOG_WARN	Warnings for potential issues.
BJ_LOG_ERROR	Errors preventing correct function.
BJ_LOG_FATAL	Critical errors leading to termination.

Function Documentation

bj_get_log_level()

int bj_get_log_level

(

void

)

Gets the current log level set by bj_set_log_level.

Returns

An integer value describing the current log level.

bj_get_log_level_string()

const char * bj_get_log_level_string

(

int

level

)

Returns a string describing the given level.

The function is only valid if called with BJ_LOG_TRACE, BJ_LOG_DEBUG, BJ_LOG_INFO, BJ_LOG_WARN, BJ_LOG_ERROR or BJ_LOG_FATAL.

The returned value is owned by the callee.

Parameters

level

The log level to get the description from.

Returns

A C-String describing level.

bj_log_message()

size_t bj_log_message	(	int	level,
		const char *	file,
		int	line,
		const char *	format,
			... )

Generic message reporting function.

Sends a message using the given level. Message will only be reported if level is at least the value set as a parameter to bj_set_log_level (or BJ_LOG_TRACE if never called).

The more convenient functions bj_log_msg, bj_trace, ... should be used for simplicity.

The string formatting follows standard printf signature and behaviour.

Parameters

level	The log level the message is reported in.
file	The file name the message is reported from.
line	The line number the message is reported from.
format,...	The formatted string to report.

Returns

The actual number of characters written, excluding the null-terminating symbol.

Format and Behavior

The log message will have the following format:

• TIME LEVEL: (SOURCE) MESSAGE Where:
• TIME is in the format "HH:MM:SS" and takes 8 characters
• LEVEL, in square brackets, is the result of calling bj_get_log_level_string. It takes up to 4 to 5 characters.
• SOURCE is in the format "FILE:LINE" and takes an undetermined number of characters. This is only present in a debug build.
• MESSAGE is the result of calling snprintf(format, ...) and the number of character varies.

For example: 12:23:34 WARN: logging.c:27 Warning level message

The maximum length a log message will take is hardcoded to the value set for BJ_MAXIMUM_LOG_LEN.

A first buffer is filled in with the expansion of the message. This message is truncated to fit the BJ_MAXIMUM_LOG_LEN characters limit entirely. If this limit is already reached, the message is logged as-is.

Then, in the order of below priority:

• If BJ_CONFIG_LOG_COLOR is set and but is not enough space for colored source (Debug only), SOURCE is not colored.
• If BJ_CONFIG_LOG_COLOR is set and but is not enough space for colored level, LEVEL is not colored.
• If there is not enough space left for TIME, it is not present.
• If there is not enough space for SOURCE (Debug only), it is not present.
• If there is not enough space for LEVEL, it is not present.

See also

bj_log_msg, bj_trace, bj_debug, bj_info, bj_warn, bj_err, bj_fatal

bj_set_log_level()

void bj_set_log_level

(

int

level

)

Sets the default log level.

Once set, any call to bj_log_message, bj_log_msg and helper macros will only report a message is its level is at least level.

Parameters

level

The level to set.

If not set, default is BJ_LOG_TRACE.