logging.h File Reference

#include <stdarg.h>
#include <stdbool.h>
#include <stdio.h>
#include "rcutils/allocator.h"
#include "rcutils/error_handling.h"
#include "rcutils/time.h"
#include "rcutils/types/rcutils_ret.h"
#include "rcutils/visibility_control.h"

Include dependency graph for logging.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	rcutils_log_location_t
	The structure identifying the caller location in the source code. More...

Macros
#define	RCUTILS_LOGGING_SEPARATOR_CHAR   '.'
#define	RCUTILS_LOGGING_SEPARATOR_STRING   "."
#define	RCUTILS_DEFAULT_LOGGER_DEFAULT_LEVEL   RCUTILS_LOG_SEVERITY_INFO
	The default severity level of the default logger. More...
#define	RCUTILS_LIKELY(x)   __builtin_expect((x), 1)
#define	RCUTILS_UNLIKELY(x)   __builtin_expect((x), 0)
#define	RCUTILS_LOGGING_AUTOINIT
	Initialize the rcl logging library. Usually it is unnecessary to call the macro directly. All logging macros ensure that this has been called once. More...

Typedefs
typedef struct rcutils_log_location_t	rcutils_log_location_t
	The structure identifying the caller location in the source code. More...
typedef void(*	rcutils_logging_output_handler_t) (const rcutils_log_location_t *, int, const char *, rcutils_time_point_value_t, const char *, va_list *)
	The function signature to log messages. More...

Enumerations
enum	RCUTILS_LOG_SEVERITY {   RCUTILS_LOG_SEVERITY_UNSET = 0, RCUTILS_LOG_SEVERITY_DEBUG = 10, RCUTILS_LOG_SEVERITY_INFO = 20, RCUTILS_LOG_SEVERITY_WARN = 30,   RCUTILS_LOG_SEVERITY_ERROR = 40, RCUTILS_LOG_SEVERITY_FATAL = 50 }
	The severity levels of log messages / loggers. More...

Functions
rcutils_ret_t	rcutils_logging_initialize_with_allocator (rcutils_allocator_t allocator)
	Initialize the logging system using the specified allocator. More...
rcutils_ret_t	rcutils_logging_initialize (void)
	Initialize the logging system. More...
rcutils_ret_t	rcutils_logging_shutdown (void)
	Shutdown the logging system. More...
rcutils_ret_t	rcutils_logging_severity_level_from_string (const char *severity_string, rcutils_allocator_t allocator, int *severity)
	Get a severity value from its string representation (e.g. DEBUG). More...
rcutils_logging_output_handler_t	rcutils_logging_get_output_handler ()
	Get the current output handler. More...
void	rcutils_logging_set_output_handler (rcutils_logging_output_handler_t function)
	Set the current output handler. More...
rcutils_ret_t	rcutils_logging_format_message (const rcutils_log_location_t *location, int severity, const char *name, rcutils_time_point_value_t timestamp, const char *msg, rcutils_char_array_t *logging_output)
	Formats a log message according to RCUTILS_CONSOLE_OUTPUT_FORMAT. More...
int	rcutils_logging_get_default_logger_level ()
	Get the default level for loggers. More...
void	rcutils_logging_set_default_logger_level (int level)
	Set the default severity level for loggers. More...
int	rcutils_logging_get_logger_level (const char *name)
	Get the severity level for a logger. More...
int	rcutils_logging_get_logger_leveln (const char *name, size_t name_length)
	Get the level for a logger and its name length. More...
rcutils_ret_t	rcutils_logging_set_logger_level (const char *name, int level)
	Set the severity level for a logger. More...
bool	rcutils_logging_logger_is_enabled_for (const char *name, int severity)
	Determine if a logger is enabled for a severity level. More...
int	rcutils_logging_get_logger_effective_level (const char *name)
	Determine the effective level for a logger. More...
void	rcutils_log (const rcutils_log_location_t *location, int severity, const char *name, const char *format,...) RCUTILS_ATTRIBUTE_PRINTF_FORMAT(4
	Log a message. More...
void void	rcutils_logging_console_output_handler (const rcutils_log_location_t *location, int severity, const char *name, rcutils_time_point_value_t timestamp, const char *format, va_list *args)
	The default output handler outputs log messages to the standard streams. More...

Variables
bool	g_rcutils_logging_initialized
	The flag if the logging system has been initialized. More...
const char *const	g_rcutils_log_severity_names [RCUTILS_LOG_SEVERITY_FATAL+1]
	The names of severity levels. More...
rcutils_logging_output_handler_t	g_rcutils_logging_output_handler
	The function pointer of the current output handler. More...
int	g_rcutils_logging_default_logger_level
	The default severity level for loggers. More...

Macro Definition Documentation

RCUTILS_LOGGING_SEPARATOR_CHAR

#define RCUTILS_LOGGING_SEPARATOR_CHAR   '.'

RCUTILS_LOGGING_SEPARATOR_STRING

#define RCUTILS_LOGGING_SEPARATOR_STRING   "."

RCUTILS_DEFAULT_LOGGER_DEFAULT_LEVEL

#define RCUTILS_DEFAULT_LOGGER_DEFAULT_LEVEL   RCUTILS_LOG_SEVERITY_INFO

The default severity level of the default logger.

RCUTILS_LIKELY

#define RCUTILS_LIKELY

(

x

)

__builtin_expect((x), 1)

Instruct the compiler to optimize for the case where the argument equals 1.

RCUTILS_UNLIKELY

#define RCUTILS_UNLIKELY

(

x

)

__builtin_expect((x), 0)

Instruct the compiler to optimize for the case where the argument equals 0.

RCUTILS_LOGGING_AUTOINIT

#define RCUTILS_LOGGING_AUTOINIT

Value:

if (RCUTILS_UNLIKELY(!g_rcutils_logging_initialized)) { \
    rcutils_ret_t ret = rcutils_logging_initialize(); \
    if (ret != RCUTILS_RET_OK) { \
      RCUTILS_SAFE_FWRITE_TO_STDERR( \
        "[rcutils|" __FILE__ ":" RCUTILS_STRINGIFY(__LINE__) \
        "] error initializing logging: "); \
      RCUTILS_SAFE_FWRITE_TO_STDERR(rcutils_get_error_string().str); \
      RCUTILS_SAFE_FWRITE_TO_STDERR("\n"); \
      rcutils_reset_error(); \
    } \
  }

Initialize the rcl logging library. Usually it is unnecessary to call the macro directly. All logging macros ensure that this has been called once.

Typedef Documentation

rcutils_log_location_t

typedef struct rcutils_log_location_t rcutils_log_location_t

The structure identifying the caller location in the source code.

rcutils_logging_output_handler_t

typedef void(* rcutils_logging_output_handler_t) (const rcutils_log_location_t *, int, const char *, rcutils_time_point_value_t, const char *, va_list *)

The function signature to log messages.

Parameters

location	The pointer to the location struct
severity	The severity level
name	The name of the logger
timestamp	The timestamp
format	The format string
args	The variable argument list

Enumeration Type Documentation

RCUTILS_LOG_SEVERITY

enum RCUTILS_LOG_SEVERITY

The severity levels of log messages / loggers.

Enumerator
RCUTILS_LOG_SEVERITY_UNSET	The unset log level.
RCUTILS_LOG_SEVERITY_DEBUG	The debug log level.
RCUTILS_LOG_SEVERITY_INFO	The info log level.
RCUTILS_LOG_SEVERITY_WARN	The warn log level.
RCUTILS_LOG_SEVERITY_ERROR	The error log level.
RCUTILS_LOG_SEVERITY_FATAL	The fatal log level.

Function Documentation

rcutils_logging_initialize_with_allocator()

rcutils_ret_t rcutils_logging_initialize_with_allocator

(

rcutils_allocator_t

allocator

)

Initialize the logging system using the specified allocator.

Initialize the logging system only if it was not in an initialized state.

If an invalid allocator is passed, the initialization will fail. Otherwise, this function will still set the internal state to initialized even if an error occurs, to avoid repeated failing initialization attempts since this function is called automatically from logging macros. To re-attempt initialization, call rcutils_logging_shutdown() before re-calling this function.

If multiple errors occur, the error code of the last error will be returned.

The RCUTILS_CONSOLE_OUTPUT_FORMAT environment variable can be used to set the output format of messages logged to the console. Available tokens are:

• file_name, the full file name of the caller including the path
• function_name, the function name of the caller
• line_number, the line number of the caller
• message, the message string after it has been formatted
• name, the full logger name
• severity, the name of the severity level, e.g. INFO
• time, the timestamp of log message in floating point seconds
• time_as_nanoseconds, the timestamp of log message in integer nanoseconds

The RCUTILS_COLORIZED_OUTPUT environment variable allows configuring if colours are used or not. Available values are:

• 1: Force using colours.
• 0: Don't use colours. If it is unset, colours are used depending if the target stream is a terminal or not. See isatty documentation.

The format string can use these tokens by referencing them in curly brackets, e.g. "[{severity}] [{name}]: {message} ({function_name}() at {file_name}:{line_number})". Any number of tokens can be used. The limit of the format string is 2048 characters.

---

Attribute	Adherence
Allocates Memory	Yes
Thread-Safe	No
Uses Atomics	No
Lock-Free	Yes

Parameters

allocator

rcutils_allocator_t to be used.

Returns

RCUTILS_RET_OK if successful.

RCUTILS_RET_INVALID_ARGUMENT if the allocator is invalid, in which case initialization will fail.

RCUTILS_RET_INVALID_ARGUMENT if an error occurs reading the output format from the RCUTILS_CONSOLE_OUTPUT_FORMAT environment variable, in which case the default format will be used.

RCUTILS_RET_LOGGING_SEVERITY_MAP_INVALID if the internal logger severity level map cannot be initialized, in which case logger severity levels will not be configurable.

rcutils_logging_initialize()

rcutils_ret_t rcutils_logging_initialize

(

void

)

Initialize the logging system.

Call rcutils_logging_initialize_with_allocator() using the default allocator. This function is called automatically when using the logging macros.

---

Attribute	Adherence
Allocates Memory	Yes
Thread-Safe	No
Uses Atomics	No
Lock-Free	Yes

Returns

RCUTILS_RET_OK if successful.

RCUTILS_RET_INVALID_ARGUMENT if an error occurs reading the output format from the RCUTILS_CONSOLE_OUTPUT_FORMAT environment variable, in which case the default format will be used.

RCUTILS_RET_LOGGING_SEVERITY_MAP_INVALID if the internal logger severity level map cannot be initialized, in which case logger levels will not be configurable.

rcutils_logging_shutdown()

rcutils_ret_t rcutils_logging_shutdown

(

void

)

Shutdown the logging system.

Free the resources allocated for the logging system. This puts the system into a state equivalent to being uninitialized.

---

Attribute	Adherence
Allocates Memory	No
Thread-Safe	No
Uses Atomics	No
Lock-Free	Yes

Returns

RCUTILS_RET_OK if successful.

RCUTILS_RET_LOGGING_SEVERITY_MAP_INVALID if the internal logger severity level map cannot be finalized.

rcutils_logging_severity_level_from_string()

rcutils_ret_t rcutils_logging_severity_level_from_string	(	const char *	severity_string,
		rcutils_allocator_t	allocator,
		int *	severity
	)

Get a severity value from its string representation (e.g. DEBUG).

String representation must match one of the values in g_rcutils_log_severity_names, but is not case-sensitive. Examples: UNSET, DEBUG, INFO, WARN, Error, fatal.

Parameters

[in]	severity_string	String representation of the severity, must be a null terminated c string
[in]	allocator	rcutils_allocator_t to be used
[in,out]	severity	The severity level as a represented by the RCUTILS_LOG_SEVERITY enum

Returns

RCUTILS_RET_OK if successful, or

RCUTILS_RET_INVALID_ARGUMENT on invalid arguments, or

RCUTILS_RET_LOGGING_SEVERITY_STRING_INVALID if unable to match string, or

RCUTILS_RET_ERROR if an unspecified error occured

rcutils_logging_get_output_handler()

rcutils_logging_output_handler_t rcutils_logging_get_output_handler

(

)

Get the current output handler.

---

Attribute	Adherence
Allocates Memory	No, provided logging system is already initialized
Thread-Safe	No
Uses Atomics	No
Lock-Free	Yes

Returns

The function pointer of the current output handler.

rcutils_logging_set_output_handler()

void rcutils_logging_set_output_handler

(

rcutils_logging_output_handler_t

function

)

Set the current output handler.

---

Attribute	Adherence
Allocates Memory	No, provided logging system is already initialized
Thread-Safe	No
Uses Atomics	No
Lock-Free	Yes

Parameters

function

The function pointer of the output handler to be used.

rcutils_logging_format_message()

rcutils_ret_t rcutils_logging_format_message	(	const rcutils_log_location_t *	location,
		int	severity,
		const char *	name,
		rcutils_time_point_value_t	timestamp,
		const char *	msg,
		rcutils_char_array_t *	logging_output
	)

Formats a log message according to RCUTILS_CONSOLE_OUTPUT_FORMAT.

A formatter that is meant to be used by an output handler to format a log message to the match the format specified in RCUTILS_CONSOLE_OUTPUT_FORMAT by performing token replacement.

---

Attribute	Adherence
Allocates Memory	Yes
Thread-Safe	No
Uses Atomics	No
Lock-Free	Yes

Returns

RCUTILS_RET_OK if successful.

RCUTILS_RET_BAD_ALLOC if memory allocation error occured

Parameters

	location	The location information about where the log came from
	severity	The severity of the log message expressed as an integer
	name	The name of the logger that this message came from
	timestamp	The time at which the log message was generated
	msg	The message being logged
	args	The list of arguments to insert into the formatted log messgae
[out]	logging_output	An output buffer for the formatted message

rcutils_logging_get_default_logger_level()

int rcutils_logging_get_default_logger_level

(

)

Get the default level for loggers.

---

Attribute	Adherence
Allocates Memory	No, provided logging system is already initialized
Thread-Safe	No
Uses Atomics	No
Lock-Free	Yes

Returns

The level.

rcutils_logging_set_default_logger_level()

void rcutils_logging_set_default_logger_level

(

int

level

)

Set the default severity level for loggers.

If the severity level requested is RCUTILS_LOG_SEVERITY_UNSET, the default value for the default logger (RCUTILS_DEFAULT_LOGGER_DEFAULT_LEVEL) will be restored instead.

---

Attribute	Adherence
Allocates Memory	No, provided logging system is already initialized
Thread-Safe	No
Uses Atomics	No
Lock-Free	Yes

Parameters

level

The level to be used.

rcutils_logging_get_logger_level()

int rcutils_logging_get_logger_level

(

const char *

name

)

Get the severity level for a logger.

This considers the severity level of the specifed logger only. To get the effective level of a logger given the severity level of its ancestors, see rcutils_logging_get_logger_effective_level().

---

Attribute	Adherence
Allocates Memory	No, provided logging system is already initialized
Thread-Safe	No
Uses Atomics	No
Lock-Free	Yes

Parameters

name	The name of the logger, must be null terminated c string

Returns

The level of the logger if it has been set, or

RCUTILS_LOG_SEVERITY_UNSET if unset, or

g_rcutils_logging_default_logger_level for an empty name, or

-1 on invalid arguments, or

-1 if an error occurred

rcutils_logging_get_logger_leveln()

int rcutils_logging_get_logger_leveln	(	const char *	name,
		size_t	name_length
	)

Get the level for a logger and its name length.

Identical to rcutils_logging_get_logger_level() but without relying on the logger name to be a null terminated c string.

---

Attribute	Adherence
Allocates Memory	No, provided logging system is already initialized
Thread-Safe	No
Uses Atomics	No
Lock-Free	Yes

Parameters

name	The name of the logger
name_length	Logger name length

Returns

The level of the logger if it has been set, or

RCUTILS_LOG_SEVERITY_UNSET if unset, or

g_rcutils_logging_default_logger_level for name_length of 0, or

-1 on invalid arguments, or

-1 if an error occurred

rcutils_logging_set_logger_level()

rcutils_ret_t rcutils_logging_set_logger_level	(	const char *	name,
		int	level
	)

Set the severity level for a logger.

If an empty string is specified as the name, the g_rcutils_logging_default_logger_level will be set.

---

Attribute	Adherence
Allocates Memory	Yes
Thread-Safe	No
Uses Atomics	No
Lock-Free	Yes

Parameters

name	The name of the logger, must be null terminated c string.
level	The level to be used.

Returns

RCUTILS_RET_OK if successful, or

RCUTILS_RET_INVALID_ARGUMENT on invalid arguments, or

RCUTILS_RET_LOGGING_SEVERITY_MAP_INVALID if severity map invalid, or

RCUTILS_RET_ERROR if an unspecified error occured

rcutils_logging_logger_is_enabled_for()

bool rcutils_logging_logger_is_enabled_for	(	const char *	name,
		int	severity
	)

Determine if a logger is enabled for a severity level.

---

Attribute	Adherence
Allocates Memory	No, provided logging system is already initialized
Thread-Safe	No
Uses Atomics	No
Lock-Free	Yes

Parameters

name	The name of the logger, must be null terminated c string or NULL.
severity	The severity level.

Returns

true if the logger is enabled for the level; false otherwise.

rcutils_logging_get_logger_effective_level()

int rcutils_logging_get_logger_effective_level

(

const char *

name

)

Determine the effective level for a logger.

The effective level is determined as the severity level of the logger if it is set, otherwise it is the first specified severity level of the logger's ancestors, starting with its closest ancestor. The ancestor hierarchy is signified by logger names being separated by dots: a logger named x is an ancestor of x.y, and both x and x.y are ancestors of x.y.z, etc. If the level has not been set for the logger nor any of its ancestors, the default level is used.

---

Attribute	Adherence
Allocates Memory	No, provided logging system is already initialized
Thread-Safe	No
Uses Atomics	No
Lock-Free	Yes

Parameters

name	The name of the logger, must be null terminated c string.

Returns

The level, or

-1 on invalid arguments, or

-1 if an error occurred.

rcutils_log()

void rcutils_log	(	const rcutils_log_location_t *	location,
		int	severity,
		const char *	name,
		const char *	format,
			...
	)

Log a message.

The attributes of this function are also being influenced by the currently set output handler.

---

Attribute	Adherence
Allocates Memory	No, for formatted outputs <= 1023 characters

| Yes, for formatted outputs >= 1024 characters Thread-Safe | No Uses Atomics | No Lock-Free | Yes

Parameters

location	The pointer to the location struct or NULL
severity	The severity level
name	The name of the logger, must be null terminated c string or NULL
format	The format string
...	The variable arguments

rcutils_logging_console_output_handler()

void void rcutils_logging_console_output_handler	(	const rcutils_log_location_t *	location,
		int	severity,
		const char *	name,
		rcutils_time_point_value_t	timestamp,
		const char *	format,
		va_list *	args
	)

The default output handler outputs log messages to the standard streams.

The messages with a severity level DEBUG and INFO are written to stdout. The messages with a severity level WARN, ERROR, and FATAL are written to stderr. The console output format of the logged message can be configured through the RCUTILS_CONSOLE_OUTPUT_FORMAT environment variable: see rcutils_logging_initialize_with_allocator() for details. For configuring if using colours or not, RCUTILS_COLORIZED_OUTPUT can be used: see rcutils_logging_initialize_with_allocator() for details.

---

Attribute	Adherence
Allocates Memory	No
Thread-Safe	Yes, if the underlying *printf functions are
Uses Atomics	No
Lock-Free	Yes

Parameters

location	The pointer to the location struct or NULL
severity	The severity level
name	The name of the logger, must be null terminated c string
timestamp	The timestamp for when the log message was made
log_str	The string to be logged

Variable Documentation

g_rcutils_logging_initialized

bool g_rcutils_logging_initialized

The flag if the logging system has been initialized.

g_rcutils_log_severity_names

const char* const g_rcutils_log_severity_names[RCUTILS_LOG_SEVERITY_FATAL+1]

The names of severity levels.

g_rcutils_logging_output_handler

rcutils_logging_output_handler_t g_rcutils_logging_output_handler

The function pointer of the current output handler.

g_rcutils_logging_default_logger_level

int g_rcutils_logging_default_logger_level

The default severity level for loggers.

This level is used for (1) nameless log calls and (2) named log calls where the effective level of the logger name is unspecified.

See also

rcutils_logging_get_logger_effective_level()