Banjo API 1.1.0-alpha
Low-level C99 game development API
Loading...
Searching...
No Matches
Logging

Macros

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

Typedefs

typedef enum bj_log_level bj_log_level

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_log_level_name (int level)
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

Severity-filtered structured logging.

Banjo applications and the library itself log through one shared channel. Six severity levels are defined in bj_log_level (TRACE, DEBUG, INFO, WARN, ERROR, FATAL). At runtime only messages at or above the threshold set by bj_set_log_level are emitted; everything below is dropped at the call site, so leaving trace logs in shipped code costs nothing when the threshold is higher.

The fast path: macros per level

Use the per-level macros (bj_trace, bj_debug, bj_info, bj_warn, bj_err, bj_fatal) over the generic bj_log_msg / bj_log_message. They take printf-style arguments:

bj_info("server listening on port %d", port);
bj_err("read failed: %s", bj_error_message(err));
const char * bj_error_message(const struct bj_error *error)
Gets the error message from an error object.
#define bj_info(...)
Log a message using the BJ_LOG_INFO level.
Definition log.h:141
#define bj_err(...)
Log a message using the BJ_LOG_ERROR level.
Definition log.h:169

In debug builds, the macros also pass the source file and line to bj_log_message, which does not print them. In release builds they pass neither.

Format

A log line is the name of the level, a space and the message, written to the standard output with a newline: WARN Warning level message. It holds at most BJ_MAXIMUM_LOG_LEN characters. A longer message is truncated, and the level is left out when it no longer fits beside the message.

Configure with the CMake option BANJO_CONFIG_LOG_COLOR, which defines BJ_CONFIG_LOG_COLOR, to wrap level names in ANSI colour codes. They are written whether or not the output is a terminal.

See also
logging.c for a runnable demo.

Macro Definition Documentation

◆ bj_debug

#define bj_debug ( ...)
Value:
bj_log_msg(DEBUG, __VA_ARGS__)
#define bj_log_msg(LEVEL,...)
Log a message using the given level LEVEL.
Definition log.h:96

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 or 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.

Definition at line 127 of file log.h.

◆ 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 or 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.
Examples
handling_errors.c, logging.c, net_tcp_client.c, net_tcp_nonblocking.c, net_tcp_server.c, net_tcp_timeout.c, net_udp_broadcast_recv.c, net_udp_broadcast_send.c, net_udp_client.c, net_udp_server.c, pong.c, stream_custom.c, stream_file.c, stream_memory.c, strings.c, and text_wrapper.c.

Definition at line 169 of file log.h.

Referenced by main(), main(), setup(), and write_text().

◆ 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 or 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.

Definition at line 183 of file log.h.

◆ bj_info

◆ bj_log_msg

#define bj_log_msg ( LEVEL,
... )
Value:
bj_log_message(BJ_LOG_ ## LEVEL, 0, 0, __VA_ARGS__)
size_t bj_log_message(int level, const char *file, int line, const char *format,...)
Generic message reporting function.

Log a message using the given level LEVEL.

LEVEL is the name of a level without its BJ_LOG_ prefix, which the macro pastes back on: TRACE, DEBUG, INFO, WARN, ERROR or FATAL. Call bj_log_message for a level held in a variable.

A message is reported only if LEVEL is at least the threshold set with bj_set_log_level.

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

Parameters
LEVELThe name of the level to report the message in, without its BJ_LOG_ prefix.
...Arguments forwarded to bj_log_message.
See also
bj_log_message, bj_trace, bj_debug, bj_info, bj_warn, bj_err, bj_fatal.
Examples
logging.c.

Definition at line 96 of file log.h.

Referenced by main().

◆ BJ_MAXIMUM_LOG_LEN

#define BJ_MAXIMUM_LOG_LEN   120u

Maximum length of log messages.

Log lines, the level and its colour codes included, cannot have a size in bytes larger than BJ_MAXIMUM_LOG_LEN, excluding the newline. In case a message is longer than this limit, the content is truncated in order of priority as described in bj_log_message.

Definition at line 59 of file log.h.

◆ 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 or 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.
Examples
stopwatch.c, and time.c.

Definition at line 113 of file log.h.

Referenced by main().

◆ 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 or 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.
Examples
logging.c.

Definition at line 155 of file log.h.

Referenced by main().

Typedef Documentation

◆ bj_log_level

typedef enum bj_log_level bj_log_level

Definition at line 74 of file log.h.

Enumeration Type Documentation

◆ 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.

Definition at line 65 of file log.h.

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.
Examples
logging.c.

Referenced by main().

◆ bj_get_log_level_string()

const char * bj_get_log_level_string ( int level)
Deprecated
Renamed to bj_log_level_name. Removed in 2.0.

◆ bj_log_level_name()

const char * bj_log_level_name ( int level)

Return the name of the given log level ("TRACE", "WARN", ...).

A level outside bj_log_level gives "UNKNOWN".

Parameters
levelThe log level to name.
Returns
A null-terminated string owned by the library.

◆ 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
levelThe log level the message is reported in. A level outside bj_log_level is named UNKNOWN and is never coloured.
fileThe file the message is reported from, or NULL. It is not printed.
lineThe line the message is reported from. It is not printed.
format,...The formatted string to report. A NULL format logs nothing and returns 0.
Returns
The number of characters written, colour codes included and the newline excluded, or 0 when nothing is written.
Format and Behaviour

The line written to the standard output is LEVEL MESSAGE and a newline, where:

  • LEVEL is the result of bj_log_level_name, which takes 4 or 5 characters, or 7 for UNKNOWN. Under BJ_CONFIG_LOG_COLOR it is wrapped in ANSI colour codes, 9 characters in all, except for UNKNOWN.
  • MESSAGE is format expanded with the arguments, as printf does.

For example: WARN Warning level message

The line holds at most BJ_MAXIMUM_LOG_LEN characters, the newline excluded. To keep to it, the function gives things up in this order:

  • A message longer than BJ_MAXIMUM_LOG_LEN keeps its first BJ_MAXIMUM_LOG_LEN characters.
  • If the colour codes do not fit beside the message with the level and its space, the level is not coloured.
  • If the level and its space do not fit beside the message, the line is the message alone.
See also
bj_log_msg, bj_trace, bj_debug, bj_info, bj_warn, bj_err, bj_fatal
Todo
This function does not yet enforce UTF-8 on its string parameters. Per ADR 0008, it will.

◆ 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 if its level is at least level.

Parameters
levelThe level to set.

If not set, default is BJ_LOG_TRACE.

Examples
logging.c.

Referenced by main().