rcutils
master
C API providing common utilities and data structures.
|
#include <stdarg.h>
#include <stdbool.h>
#include <stdio.h>
#include "rcutils/allocator.h"
#include "rcutils/error_handling.h"
#include "rcutils/macros.h"
#include "rcutils/time.h"
#include "rcutils/types/rcutils_ret.h"
#include "rcutils/visibility_control.h"
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_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... | |
#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.
#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.
typedef struct rcutils_log_location_t rcutils_log_location_t |
The structure identifying the caller location in the source code.
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.
[in] | location | The location information about where the log came from |
[in] | severity | The severity of the log message expressed as an integer |
[in] | name | The name of the logger that this message came from |
[in] | timestamp | The time at which the log message was generated |
[in] | format | The list of arguments to insert into the formatted log message |
[in] | args | The variable argument list |
enum RCUTILS_LOG_SEVERITY |
The severity levels of log messages / loggers.
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 pathfunction_name
, the function name of the callerline_number
, the line number of the callermessage
, the message string after it has been formattedname
, the full logger nameseverity
, the name of the severity level, e.g. INFO
time
, the timestamp of log message in floating point secondstime_as_nanoseconds
, the timestamp of log message in integer nanosecondsThe 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 |
[in] | allocator | rcutils_allocator_t to be used. |
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_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 |
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_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 |
RCUTILS_RET_OK
if successful. RCUTILS_RET_LOGGING_SEVERITY_MAP_INVALID
if the internal logger severity level map cannot be finalized. 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.
[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 |
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_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 |
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 |
[in] | function | The function pointer of the output handler to be used. |
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 |
RCUTILS_RET_OK
if successful. RCUTILS_RET_BAD_ALLOC
if memory allocation error occured [in] | location | The location information about where the log came from |
[in] | severity | The severity of the log message expressed as an integer |
[in] | name | The name of the logger that this message came from |
[in] | timestamp | The time at which the log message was generated |
[in] | msg | The message being logged |
[out] | logging_output | An output buffer for the formatted message |
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 |
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 |
[in] | level | The level to be used. |
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 |
[in] | name | The name of the logger, must be null terminated c string |
RCUTILS_LOG_SEVERITY_UNSET
if unset, or g_rcutils_logging_default_logger_level
for an empty name, or 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 |
[in] | name | The name of the logger |
[in] | name_length | Logger name length |
RCUTILS_LOG_SEVERITY_UNSET
if unset, or g_rcutils_logging_default_logger_level
for name_length
of 0
, or 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 |
[in] | name | The name of the logger, must be null terminated c string. |
[in] | level | The level to be used. |
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 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 |
[in] | name | The name of the logger, must be null terminated c string or NULL. |
[in] | severity | The severity 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 |
[in] | name | The name of the logger, must be null terminated c string. |
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
[in] | location | The pointer to the location struct or NULL |
[in] | severity | The severity level |
[in] | name | The name of the logger, must be null terminated c string or NULL |
[in] | format | The format string |
[in] | ... | The variable arguments |
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 |
[in] | location | The pointer to the location struct or NULL |
[in] | severity | The severity level |
[in] | name | The name of the logger, must be null terminated c string |
[in] | timestamp | The timestamp for when the log message was made |
[in] | format | The format string |
[in] | args | The va_list used by the logger |
bool g_rcutils_logging_initialized |
The flag if the logging system has been initialized.
const char* const g_rcutils_log_severity_names[RCUTILS_LOG_SEVERITY_FATAL+1] |
The names of severity levels.
rcutils_logging_output_handler_t g_rcutils_logging_output_handler |
The function pointer of the current output handler.
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.