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
• 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

Changelog for package rcutils

6.9.5 (2025-04-02)

• Handle spaces in start_process arguments on Windows (#494)
• Add utility functions for invoking a subprocess (#491) (#492)
• Add rcutils_join function for concatenating strings (#490)
• Switch to ament_cmake_ros_core package (#489)
• Contributors: Alejandro Hernández Cordero, Michael Carroll, Scott K Logan

6.9.4 (2025-02-02)

• Cleanup error handling in rcutils. (#485)
• Remove CODEOWNERS and mirror-rolling-to-master workflow. (#483)
• Contributors: Chris Lalancette

6.9.3 (2024-10-03)

• Fix setting allocator to NULL. (#478)
• Contributors: Chris Lalancette

6.9.2 (2024-09-16)

• Add new API to set envar while specifying overwrite (#473)
• Contributors: Yadu

6.9.1 (2024-07-29)

• Remove completely unnecessary use of CLASSNAME. (#471)
• Contributors: Chris Lalancette

6.9.0 (2024-06-17)

• load dll built by MINGW with lib prefix (#470)
• add mingw support (#468)
• Fix filesystem iteration on Windows (#469)
• Add 'mimick' label to tests which use Mimick (#466)
• Contributors: Chris Lalancette, Felix F Xu, Scott K Logan

6.8.0 (2024-04-26)

• Removed warnings - strict-prototypes (#461)
• Increase timeout repl_str test (#463)
• Contributors: Alejandro Hernández Cordero

6.7.0 (2024-04-16)

• validate the allocator before use. (#455)

  • validate the allocator before use.
  • address review comments.
  • validate allocator only if the function specifically uses.

  - argument null check comes before validation of value. ---------

• Contributors: Tomoya Fujita

6.6.0 (2024-03-28)

• feat: Add human readable date to logging formats (#441)
• Updates for uncrustify 0.78. (#454)
• Set hints to find the python version we actually want. (#451)
• Bring ament_add_gtest/target_link_libraries back together (#452)
• Change 'ROS2' to 'ROS 2' in quality declaration (#453)
• Allow parsing of escape sequence in log format (#443)
• Contributors: Chris Lalancette, Christophe Bedard, Kaju-Bubanja, Marc Bestmann

6.5.2 (2024-02-07)

• Clean up unused references to mimick/mocking in tests (#450)
• Fix if(TARGET ...) condition for test (#447)
• Zero-initialize rcutils_string_array_t in test_string_array

File truncated at 100 lines see the full file