rcutils  master
C API providing common utilities and data structures.
logging.h
Go to the documentation of this file.
1 // Copyright 2017 Open Source Robotics Foundation, Inc.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 
15 #ifndef RCUTILS__LOGGING_H_
16 #define RCUTILS__LOGGING_H_
17 
18 #include <stdarg.h>
19 #include <stdbool.h>
20 #include <stdio.h>
21 
22 #include "rcutils/allocator.h"
23 #include "rcutils/error_handling.h"
24 #include "rcutils/time.h"
27 
28 #ifdef __cplusplus
29 extern "C"
30 {
31 #endif
32 
33 #define RCUTILS_LOGGING_SEPARATOR_CHAR '.'
34 #define RCUTILS_LOGGING_SEPARATOR_STRING "."
35 
40 #define RCUTILS_DEFAULT_LOGGER_DEFAULT_LEVEL RCUTILS_LOG_SEVERITY_INFO
41 
45 
47 
105 
107 
130 
132 
151 
154 {
156  const char * function_name;
158  const char * file_name;
160  size_t line_number;
162 
165 {
172 };
173 
176 extern const char * const g_rcutils_log_severity_names[RCUTILS_LOG_SEVERITY_FATAL + 1];
177 
179 
199  const char * severity_string, rcutils_allocator_t allocator, int * severity);
200 
202 
211  const rcutils_log_location_t *, // location
212  int, // severity
213  const char *, // name
214  rcutils_time_point_value_t, // timestamp
215  const char *, // format
216  va_list * // args
217 );
218 
222 
224 
238 
240 
253 
255 
280  const rcutils_log_location_t * location,
281  int severity, const char * name, rcutils_time_point_value_t timestamp,
282  const char * msg, rcutils_char_array_t * logging_output);
283 
285 
293 
295 
309 
311 
328 
330 
352 int rcutils_logging_get_logger_level(const char * name);
353 
355 
377 int rcutils_logging_get_logger_leveln(const char * name, size_t name_length);
378 
380 
401 rcutils_ret_t rcutils_logging_set_logger_level(const char * name, int level);
402 
404 
420 bool rcutils_logging_logger_is_enabled_for(const char * name, int severity);
421 
423 
449 int rcutils_logging_get_logger_effective_level(const char * name);
450 
452 
472 void rcutils_log(
473  const rcutils_log_location_t * location,
474  int severity,
475  const char * name,
476  const char * format,
477  ...)
479 
481 
507  const rcutils_log_location_t * location,
508  int severity, const char * name, rcutils_time_point_value_t timestamp,
509  const char * format, va_list * args);
510 
511 // Provide the compiler with branch prediction information
512 #ifndef _WIN32
513 
517 # define RCUTILS_LIKELY(x) __builtin_expect((x), 1)
518 
522 # define RCUTILS_UNLIKELY(x) __builtin_expect((x), 0)
523 #else
524 
528 # define RCUTILS_LIKELY(x) (x)
529 
533 # define RCUTILS_UNLIKELY(x) (x)
534 #endif // _WIN32
535 
542 #define RCUTILS_LOGGING_AUTOINIT \
543  if (RCUTILS_UNLIKELY(!g_rcutils_logging_initialized)) { \
544  rcutils_ret_t ret = rcutils_logging_initialize(); \
545  if (ret != RCUTILS_RET_OK) { \
546  RCUTILS_SAFE_FWRITE_TO_STDERR( \
547  "[rcutils|" __FILE__ ":" RCUTILS_STRINGIFY(__LINE__) \
548  "] error initializing logging: "); \
549  RCUTILS_SAFE_FWRITE_TO_STDERR(rcutils_get_error_string().str); \
550  RCUTILS_SAFE_FWRITE_TO_STDERR("\n"); \
551  rcutils_reset_error(); \
552  } \
553  }
554 
555 #ifdef __cplusplus
556 }
557 #endif
558 
559 #endif // RCUTILS__LOGGING_H_
int rcutils_logging_get_logger_leveln(const char *name, size_t name_length)
Get the level for a logger and its name length.
rcutils_ret_t rcutils_logging_shutdown(void)
Shutdown the logging system.
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.
Definition: char_array.h:29
The info log level.
Definition: logging.h:168
The warn log level.
Definition: logging.h:169
The unset log level.
Definition: logging.h:166
rcutils_ret_t rcutils_logging_initialize(void)
Initialize the logging system.
int rcutils_ret_t
Definition: rcutils_ret.h:23
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).
bool g_rcutils_logging_initialized
The flag if the logging system has been initialized.
void rcutils_logging_set_output_handler(rcutils_logging_output_handler_t function)
Set the current output handler.
int64_t rcutils_time_point_value_t
A single point in time, measured in nanoseconds since the Unix epoch.
Definition: time.h:46
size_t line_number
The line number containing the log call.
Definition: logging.h:160
#define RCUTILS_ATTRIBUTE_PRINTF_FORMAT(format_string_index, first_to_check_index)
Definition: macros.h:91
int g_rcutils_logging_default_logger_level
The default severity level for loggers.
Encapsulation of an allocator.
Definition: allocator.h:45
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.
rcutils_ret_t rcutils_logging_set_logger_level(const char *name, int level)
Set the severity level for a logger.
rcutils_logging_output_handler_t rcutils_logging_get_output_handler()
Get the current output handler.
void rcutils_logging_set_default_logger_level(int level)
Set the default severity level for loggers.
RCUTILS_LOG_SEVERITY
The severity levels of log messages / loggers.
Definition: logging.h:164
const char * file_name
The name of the source file containing the log call.
Definition: logging.h:158
The structure identifying the caller location in the source code.
Definition: logging.h:153
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.
#define RCUTILS_WARN_UNUSED
Definition: macros.h:24
#define RCUTILS_PUBLIC
Definition: visibility_control.h:48
The fatal log level.
Definition: logging.h:171
rcutils_ret_t rcutils_logging_initialize_with_allocator(rcutils_allocator_t allocator)
Initialize the logging system using the specified allocator.
bool rcutils_logging_logger_is_enabled_for(const char *name, int severity)
Determine if a logger is enabled for a severity level.
const char *const g_rcutils_log_severity_names[RCUTILS_LOG_SEVERITY_FATAL+1]
The names of severity levels.
int rcutils_logging_get_logger_effective_level(const char *name)
Determine the effective level for a logger.
struct rcutils_log_location_t rcutils_log_location_t
The structure identifying the caller location in the source code.
rcutils_logging_output_handler_t g_rcutils_logging_output_handler
The function pointer of the current output handler.
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.
Definition: logging.h:210
The debug log level.
Definition: logging.h:167
const char * function_name
The name of the function containing the log call.
Definition: logging.h:156
int rcutils_logging_get_default_logger_level()
Get the default level for loggers.
The error log level.
Definition: logging.h:170
int rcutils_logging_get_logger_level(const char *name)
Get the severity level for a logger.