C++ API

rcutils: ROS 2 C Utilities data structures

rcutils is a C API consisting of macros, functions, and data structures used through out the ROS 2 code base.

Quality Declaration

This package claims to be in the Quality Level 1 category, see the Quality Declaration for more details.

API

The API is a combination of parts:

• Allocator concept, used to inject the allocating and deallocating methods into a function or type.

  • rcutils_allocator_t

  • rcutils/allocator.h

• Command line interface utilities:

  • rcutils/cmdline_parser.h

• Utilities for setting error states (error message, file, and line number) like strerror for errno:

  • rcutils/error_handling.h

• Some basic filesystem utilities like checking for path existence, getting the cwd, etc…:

  • rcutils/filesystem.h

• A C string find method:

  • rcutils_find()

  • rcutils_find_last()

  • rcutils/find.h

• A convenient string formatting function, which takes a custom allocator:

  • rcutils_format_string()

  • rcutils/format_string.h

• Functions for interfacing with process environment variables:

  • rcutils_get_env()

  • rcutils_get_home_dir()

  • rcutils_set_env()

  • rcutils/env.h

  • rcutils/get_env.h

• Extensible logging macros:

  • Some examples (not exhaustive):

    • RCUTILS_LOG_DEBUG()

    • RCUTILS_LOG_INFO_NAMED()

    • RCUTILS_LOG_WARN_ONCE()

    • RCUTILS_LOG_ERROR_SKIPFIRST_NAMED()

  • rcutils/logging_macros.h

  • rcutils/logging.h

• Some basic utilities to load, unload and get symbols from shared libraries at run-time.

  • rcutils/shared_library.h

• A string replacement function which takes an allocator, based on http://creativeandcritical.net/str-replace-c:

  • rcutils_repl_str()

  • rcutils/repl_str.h

• String splitting functions which take a custom allocator:

  • rcutils_split()

  • rcutils_split_last()

  • rcutils/split.h

• A version of strdup which takes an allocator:

  • rcutils_strdup()

  • rcutils/strdup.h

• Portable implementations of “get system time” and “get steady time”:

  • rcutils_system_time_now()

  • rcutils_steady_time_now()

  • rcutils/time.h

• Some useful data structures:

  • A “string array” data structure (analogous to std::vector<std::string>):

    • rcutils_string_array_t

    • rcutils/types/string_array.h

  • A “string-string map” data structure (analogous to std::map<std::string, std::string>)

    • rcutils_string_map_t

    • rcutils/types/string_map.h

• Macros for controlling symbol visibility and linkage for this library:

  • rcutils/visibility_control.h

Class Hierarchy

• • Struct rcutils_allocator_s
  • Struct rcutils_array_list_s
  • Struct rcutils_char_array_s
  • Struct rcutils_dir_iter_s
  • Struct rcutils_error_state_s
  • Struct rcutils_error_string_s
  • Struct rcutils_hash_map_s
  • Struct rcutils_log_location_s
  • Struct rcutils_shared_library_s
  • Struct rcutils_string_array_s
  • Struct rcutils_string_map_s
  • Struct rcutils_uint8_array_s
  • Enum RCUTILS_LOG_SEVERITY

File Hierarchy

• • Directory include
    • Directory rcutils
      • Directory testing
        • File fault_injection.h
      • Directory types
        • File array_list.h
        • File char_array.h
        • File hash_map.h
        • File rcutils_ret.h
        • File string_array.h
        • File string_map.h
        • File uint8_array.h
      • File allocator.h
      • File cmdline_parser.h
      • File env.h
      • File error_handling.h
      • File filesystem.h
      • File find.h
      • File format_string.h
      • File get_env.h
      • File isalnum_no_locale.h
      • File logging.h
      • File macros.h
      • File process.h
      • File qsort.h
      • File repl_str.h
      • File shared_library.h
      • File snprintf.h
      • File split.h
      • File stdatomic_helper.h
      • File strcasecmp.h
      • File strdup.h
      • File strerror.h
      • File time.h
      • File types.h
      • File visibility_control.h
      • File visibility_control_macros.h
  • File README.md

Full C++ API

Classes and Structs

• Struct rcutils_allocator_s

• Struct rcutils_array_list_s

• Struct rcutils_char_array_s

• Struct rcutils_dir_iter_s

• Struct rcutils_error_state_s

• Struct rcutils_error_string_s

• Struct rcutils_hash_map_s

• Struct rcutils_log_location_s

• Struct rcutils_shared_library_s

• Struct rcutils_string_array_s

• Struct rcutils_string_map_s

• Struct rcutils_uint8_array_s

Enums

• Enum RCUTILS_LOG_SEVERITY

Functions

• Function _rcutils_fault_injection_maybe_fail

• Function rcutils_allocator_is_valid

• Function rcutils_array_list_add

• Function rcutils_array_list_fini

• Function rcutils_array_list_get

• Function rcutils_array_list_get_size

• Function rcutils_array_list_init

• Function rcutils_array_list_remove

• Function rcutils_array_list_set

• Function rcutils_atomic_compare_exchange_strong_uint_least64_t

• Function rcutils_atomic_exchange_bool

• Function rcutils_atomic_exchange_int64_t

• Function rcutils_atomic_exchange_uint64_t

• Function rcutils_atomic_exchange_uintptr_t

• Function rcutils_atomic_fetch_add_uint64_t

• Function rcutils_atomic_load_bool

• Function rcutils_atomic_load_int64_t

• Function rcutils_atomic_load_uint64_t

• Function rcutils_atomic_load_uintptr_t

• Function rcutils_calculate_directory_size

• Function rcutils_calculate_directory_size_with_recursion

• Function rcutils_char_array_expand_as_needed

• Function rcutils_char_array_fini

• Function rcutils_char_array_init

• Function rcutils_char_array_memcpy

• Function rcutils_char_array_resize

• Function rcutils_char_array_strcat

• Function rcutils_char_array_strcpy

• Function rcutils_char_array_strncat

• Function rcutils_char_array_vsprintf

• Function rcutils_cli_get_option

• Function rcutils_cli_option_exist

• Function rcutils_dir_iter_end

• Function rcutils_dir_iter_next

• Function rcutils_dir_iter_start

• Function rcutils_error_is_set

• Function rcutils_exists

• Function rcutils_expand_user

• Function rcutils_fault_injection_get_count

• Function rcutils_fault_injection_is_test_complete

• Function rcutils_fault_injection_set_count

• Function rcutils_find

• Function rcutils_find_last

• Function rcutils_find_lastn

• Function rcutils_findn

• Function rcutils_format_string_limit

• Function rcutils_get_cwd

• Function rcutils_get_default_allocator

• Function rcutils_get_env

• Function rcutils_get_error_state

• Function rcutils_get_error_string

• Function rcutils_get_executable_name

• Function rcutils_get_file_size

• Function rcutils_get_home_dir

• Function rcutils_get_pid

• Function rcutils_get_platform_library_name

• Function rcutils_get_symbol

• Function rcutils_get_zero_initialized_allocator

• Function rcutils_get_zero_initialized_array_list

• Function rcutils_get_zero_initialized_char_array

• Function rcutils_get_zero_initialized_hash_map

• Function rcutils_get_zero_initialized_shared_library

• Function rcutils_get_zero_initialized_string_array

• Function rcutils_get_zero_initialized_string_map

• Function rcutils_get_zero_initialized_uint8_array

• Function rcutils_has_symbol

• Function rcutils_hash_map_fini

• Function rcutils_hash_map_get

• Function rcutils_hash_map_get_capacity

• Function rcutils_hash_map_get_next_key_and_data

• Function rcutils_hash_map_get_size

• Function rcutils_hash_map_init

• Function rcutils_hash_map_key_exists

• Function rcutils_hash_map_set

• Function rcutils_hash_map_string_cmp_func

• Function rcutils_hash_map_string_hash_func

• Function rcutils_hash_map_unset

• Function rcutils_initialize_error_handling_thread_local_storage

• Function rcutils_is_directory

• Function rcutils_is_file

• Function rcutils_is_readable

• Function rcutils_is_readable_and_writable

• Function rcutils_is_shared_library_loaded

• Function rcutils_is_writable

• Function rcutils_isalnum_no_locale

• Function rcutils_join_path

• Function rcutils_load_shared_library

• Function rcutils_log

• Function rcutils_logging_console_output_handler

• Function rcutils_logging_format_message

• Function rcutils_logging_get_default_logger_level

• Function rcutils_logging_get_logger_effective_level

• Function rcutils_logging_get_logger_level

• Function rcutils_logging_get_logger_leveln

• Function rcutils_logging_get_output_handler

• Function rcutils_logging_initialize

• Function rcutils_logging_initialize_with_allocator

• Function rcutils_logging_logger_is_enabled_for

• Function rcutils_logging_set_default_logger_level

• Function rcutils_logging_set_logger_level

• Function rcutils_logging_set_output_handler

• Function rcutils_logging_severity_level_from_string

• Function rcutils_logging_shutdown

• Function rcutils_mkdir

• Function rcutils_qsort

• Function rcutils_reallocf

• Function rcutils_repl_str

• Function rcutils_reset_error

• Function rcutils_set_env

• Function rcutils_set_error_state

• Function rcutils_snprintf

• Function rcutils_split

• Function rcutils_split_last

• Function rcutils_steady_time_now

• Function rcutils_strcasecmp

• Function rcutils_strdup

• Function rcutils_strerror

• Function rcutils_string_array_cmp

• Function rcutils_string_array_fini

• Function rcutils_string_array_init

• Function rcutils_string_array_resize

• Function rcutils_string_array_sort

• Function rcutils_string_array_sort_compare

• Function rcutils_string_map_clear

• Function rcutils_string_map_copy

• Function rcutils_string_map_fini

• Function rcutils_string_map_get

• Function rcutils_string_map_get_capacity

• Function rcutils_string_map_get_next_key

• Function rcutils_string_map_get_size

• Function rcutils_string_map_getn

• Function rcutils_string_map_init

• Function rcutils_string_map_key_exists

• Function rcutils_string_map_key_existsn

• Function rcutils_string_map_reserve

• Function rcutils_string_map_set

• Function rcutils_string_map_set_no_resize

• Function rcutils_string_map_unset

• Function rcutils_strncasecmp

• Function rcutils_strndup

• Function rcutils_system_time_now

• Function rcutils_time_point_value_as_nanoseconds_string

• Function rcutils_time_point_value_as_seconds_string

• Function rcutils_to_native_path

• Function rcutils_uint8_array_fini

• Function rcutils_uint8_array_init

• Function rcutils_uint8_array_resize

• Function rcutils_unload_shared_library

• Function rcutils_vsnprintf

Variables

• Variable g_rcutils_log_severity_names

• Variable g_rcutils_logging_default_logger_level

• Variable g_rcutils_logging_initialized

• Variable g_rcutils_logging_output_handler

Defines

• Define __STDC_WANT_LIB_EXT1__

• Define ARRAY_LIST_VALIDATE_ARRAY_LIST

• Define HASH_MAP_VALIDATE_HASH_MAP

• Define my__has_feature

• Define rcutils_atomic_compare_exchange_strong

• Define rcutils_atomic_exchange

• Define rcutils_atomic_fetch_add

• Define rcutils_atomic_load

• Define rcutils_atomic_store

• Define RCUTILS_ATTRIBUTE_PRINTF_FORMAT

• Define RCUTILS_CAN_FAIL_WITH

• Define RCUTILS_CAN_RETURN_WITH_ERROR_OF

• Define RCUTILS_CAN_SET_MSG_AND_RETURN_WITH_ERROR_OF

• Define RCUTILS_CHECK_ALLOCATOR

• Define RCUTILS_CHECK_ALLOCATOR_WITH_MSG

• Define RCUTILS_CHECK_ARGUMENT_FOR_NULL

• Define RCUTILS_CHECK_FOR_NULL_WITH_MSG

• Define RCUTILS_DEFAULT_LOGGER_DEFAULT_LEVEL

• Define RCUTILS_DEPRECATED

• Define RCUTILS_DEPRECATED_WITH_MSG

• Define RCUTILS_ERROR_FORMATTING_CHARACTERS

• Define RCUTILS_ERROR_MESSAGE_MAX_LENGTH

• Define RCUTILS_ERROR_STATE_FILE_MAX_LENGTH

• Define RCUTILS_ERROR_STATE_LINE_NUMBER_STR_MAX_LENGTH

• Define RCUTILS_ERROR_STATE_MESSAGE_MAX_LENGTH

• Define RCUTILS_EXPORT

• Define RCUTILS_FAULT_INJECTION_FAIL_NOW

• Define RCUTILS_FAULT_INJECTION_MAYBE_FAIL

• Define RCUTILS_FAULT_INJECTION_MAYBE_RETURN_ERROR

• Define RCUTILS_FAULT_INJECTION_NEVER_FAIL

• Define RCUTILS_FAULT_INJECTION_TEST

• Define rcutils_format_string

• Define RCUTILS_IMPORT

• Define RCUTILS_LIKELY

• Define RCUTILS_LOCAL

• Define RCUTILS_LOGGING_AUTOINIT

• Define RCUTILS_LOGGING_SEPARATOR_STRING

• Define RCUTILS_MS_TO_NS

• Define RCUTILS_NO_FAULT_INJECTION

• Define RCUTILS_NS_TO_MS

• Define RCUTILS_NS_TO_S

• Define RCUTILS_NS_TO_US

• Define RCUTILS_PUBLIC

• Define RCUTILS_PUBLIC_TYPE

• Define RCUTILS_RET_BAD_ALLOC

• Define RCUTILS_RET_ERROR

• Define RCUTILS_RET_HASH_MAP_NO_MORE_ENTRIES

• Define RCUTILS_RET_INVALID_ARGUMENT

• Define RCUTILS_RET_LOGGING_SEVERITY_MAP_INVALID

• Define RCUTILS_RET_LOGGING_SEVERITY_STRING_INVALID

• Define RCUTILS_RET_NOT_ENOUGH_SPACE

• Define RCUTILS_RET_NOT_FOUND

• Define RCUTILS_RET_NOT_INITIALIZED

• Define RCUTILS_RET_OK

• Define RCUTILS_RET_STRING_KEY_NOT_FOUND

• Define RCUTILS_RET_STRING_MAP_ALREADY_INIT

• Define RCUTILS_RET_STRING_MAP_INVALID

• Define RCUTILS_RET_WARN

• Define RCUTILS_S_TO_NS

• Define RCUTILS_SAFE_FWRITE_TO_STDERR

• Define RCUTILS_SAFE_FWRITE_TO_STDERR_WITH_FORMAT_STRING

• Define RCUTILS_SET_ERROR_MSG

• Define RCUTILS_SET_ERROR_MSG_WITH_FORMAT_STRING

• Define RCUTILS_STEADY_TIME

• Define RCUTILS_UNLIKELY

• Define RCUTILS_US_TO_NS

• Define RCUTILS_WARN_UNUSED

Typedefs

• Typedef rcutils_allocator_t

• Typedef rcutils_array_list_t

• Typedef rcutils_char_array_t

• Typedef rcutils_dir_iter_t

• Typedef rcutils_duration_value_t

• Typedef rcutils_error_state_t

• Typedef rcutils_error_string_t

• Typedef rcutils_hash_map_key_cmp_t

• Typedef rcutils_hash_map_key_hasher_t

• Typedef rcutils_hash_map_t

• Typedef rcutils_log_location_t

• Typedef rcutils_logging_output_handler_t

• Typedef rcutils_ret_t

• Typedef rcutils_shared_library_t

• Typedef rcutils_string_array_t

• Typedef rcutils_string_map_t

• Typedef rcutils_time_point_value_t

• Typedef rcutils_uint8_array_t

Directories

• Directory include

• Directory rcutils

• Directory testing

• Directory types

Files

• File allocator.h

• File array_list.h

• File char_array.h

• File cmdline_parser.h

• File env.h

• File error_handling.h

• File fault_injection.h

• File filesystem.h

• File find.h

• File format_string.h

• File get_env.h

• File hash_map.h

• File isalnum_no_locale.h

• File logging.h

• File macros.h

• File process.h

• File qsort.h

• File rcutils_ret.h

• File README.md

• File repl_str.h

• File shared_library.h

• File snprintf.h

• File split.h

• File stdatomic_helper.h

• File strcasecmp.h

• File strdup.h

• File strerror.h

• File string_array.h

• File string_map.h

• File time.h

• File types.h

• File uint8_array.h

• File visibility_control.h

• File visibility_control_macros.h