Function rcutils_logging_initialize_with_allocator

Function Documentation

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 – [in] rcutils_allocator_t to be used.

Returns:

RCUTILS_RET_OK if successful, or

Returns:

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

Returns:

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

Returns:

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.