logging.h File Reference

#include <stdarg.h>
#include <stdbool.h>
#include <stdio.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_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) (rcutils_log_location_t *, int, const char *, const char *, va_list *)
	The function signature to log messages. More...

Enumerations
enum	RCUTILS_LOG_SEVERITY {   RCUTILS_LOG_SEVERITY_DEBUG = 0, RCUTILS_LOG_SEVERITY_INFO = 1, RCUTILS_LOG_SEVERITY_WARN = 2, RCUTILS_LOG_SEVERITY_ERROR = 3,   RCUTILS_LOG_SEVERITY_FATAL = 4 }
	The severity levels of log message. More...

Functions
void	rcutils_logging_initialize ()
	Initialize the logging system. 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...
int	rcutils_logging_get_severity_threshold ()
	Get the global severity threshold. More...
void	rcutils_logging_set_severity_threshold (int severity)
	Set the global severity threshold. More...
void	rcutils_log (rcutils_log_location_t *location, int severity, const char *name, const char *format,...)
	Log a message. More...
void	rcutils_logging_console_output_handler (rcutils_log_location_t *location, int severity, const char *name, 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...
rcutils_logging_output_handler_t	g_rcutils_logging_output_handler
	The function pointer of the current output handler. More...
int	g_rcutils_logging_severity_threshold
	The global severity threshold before calling the output handler. More...

Macro Definition Documentation

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_logging_initialize(); \
  }

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) (rcutils_log_location_t *, int, const char *, const char *, va_list *)

The function signature to log messages.

Parameters

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

Enumeration Type Documentation

RCUTILS_LOG_SEVERITY

enum RCUTILS_LOG_SEVERITY

The severity levels of log message.

Enumerator
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()

void rcutils_logging_initialize

(

)

Initialize the logging system.

The function is called automatically when using the logging macros.

---

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

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
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
Thread-Safe	No
Uses Atomics	No
Lock-Free	Yes

Parameters

function

The function pointer of the output handler to be used.

rcutils_logging_get_severity_threshold()

int rcutils_logging_get_severity_threshold

(

)

Get the global severity threshold.

---

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

Returns

The severity threshold.

rcutils_logging_set_severity_threshold()

void rcutils_logging_set_severity_threshold

(

int

severity

)

Set the global severity threshold.

---

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

Parameters

severity

The severity threshold to be used.

rcutils_log()

void rcutils_log	(	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
Thread-Safe	No
Uses Atomics	No
Lock-Free	Yes

Parameters

location	The pointer to the location struct
severity	The severity level
name	The name of the logger
format	The format string
...	The variable arguments

rcutils_logging_console_output_handler()

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

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

The messages with a severity DEBUG and INFO are written to stdout. The messages with a severity WARN, ERROR, and FATAL are written to stderr. For each message the severity and name is prepended and the location information is appended when available.

---

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

| Yes, for formatted messages >= 1024 characters Thread-Safe | Yes, if the underlying *printf functions are Uses Atomics | No Lock-Free | Yes

Parameters

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

Variable Documentation

g_rcutils_logging_initialized

bool g_rcutils_logging_initialized

The flag if the logging system has been initialized.

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_severity_threshold

int g_rcutils_logging_severity_threshold

The global severity threshold before calling the output handler.

The global severity threshold is being checked after the conditions when using the various logging macros.

Parameters

severity

The global severity threshold to be used.