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.10.1 (2025-05-30)

• use getenv_s instead of getenv for Windows. (#499)
• Make linters happy
• Clean memory in test_process.cpp (#495)
• Contributors: Alejandro Hernández Cordero, Tomoya Fujita

6.10.0 (2025-04-24)

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 (#446)
• Use rcutils_string_array_init in rcutils_split & handle alloc fail (#445)
• Contributors: Christophe Bedard

6.5.1 (2024-01-24)

• Make rcutils_split() return RCUTILS_RET_BAD_ALLOC if alloc fails (#444)
• Contributors: Christophe Bedard

6.5.0 (2023-12-26)

• Remove two last uses of ament_target_dependencies. (#440)
• time_win32: Update dead link (#438)
• Contributors: Chris Lalancette, Silvio Traversaro

6.4.1 (2023-11-06)

• memmove for overlaping memory (#434)
• Contributors: Tyler Weaver

6.4.0 (2023-10-04)

• make escape characters work (#426)
• Contributors: Chen Lihui

6.3.1 (2023-09-07)

• Remove unused 'max' functions from sha256.c (#429)
• Contributors: Chris Lalancette

6.3.0 (2023-04-27)

6.2.1 (2023-04-12)

• fix memory leak (#423)
• Contributors: Chen Lihui

6.2.0 (2023-04-11)

• Add convenience error handling macros (#421)
• Calculate the next power-of-two for the user in hash_map_init. (#420)
• update cast to modern style (#418)
• Remove deprecated header get_env.h (#417)
• Updates to rcutils to make rosdoc2 generation happier. (#416)
• add RCUTILS_LOGGING_AUTOINIT_WITH_ALLOCATOR. (#415)
• Fix memory leak in string_map.c in rcutils (#411)
• avoid unnecessary copy for rcutils_char_array_vsprintf. (#412)
• Contributors: Chris Lalancette, Emerson Knapp, Mario Prats, Nikolai Morin, Tomoya Fujita, methylDragon

6.1.1 (2023-02-24)

• Add missing stddef include for size_t (#410)
• Contributors: Emerson Knapp

6.1.0 (2023-02-13)

• Add SHA256 utility implementation (#408)
• Upgrade rcutils to C++17. (#392)
• [rolling] Update maintainers - 2022-11-07 (#404)
• Contributors: Audrow Nash, Chris Lalancette, Emerson Knapp

6.0.1 (2022-11-02)

• Fix build on OpenHarmony (#395)
• regression of thread-safety for logging macros (#393)
• add portable nonnull macros (#382)
• Fix memory leak when adding the same key to the logger hash map multiple times (#391)
• time_unix: uses ZEPHYR_VERSION_CODE instead (#390)
• Cleanup time_unix.c (#389)
• time_unix: namespace zephyr headers (#383)
• Restrict overmatching MACH ifdef to only trigger on OSX and Mach (#386)
• Contributors: AIxWall, Chris Lalancette, Felipe Neves, Jacob Perron, Maximilian Downey Twiss, William Woodall

6.0.0 (2022-09-13)

• Optimize rcutils_logging_get_logger_effective_level() (#381)
• Change syntax __VAR_ARGS_ to __VA_ARGS_ (#376)
• Fix a bug in hash_map_get_next_key_and_data. (#375)
• More fixes from review.
• Fixes from review.
• Make g_rcutils_logging_output_handler static.
• Make g_rcutils_logging_default_logger_level static.
• Optimize rcutils_find_lastn where possible.
• Don't bother computing the hash_map key if the hash map is empty.
• Make sure to expand char_array by at least 1.5x.
• Optimize index computation in hash_map_find.
• Improve the performance of rcutils_logging_format_message. (#372)
• Get rid of unnecessary ret variable.
• Get rid of unnecessary ifdef cplusplus checks in the C file.
• Get rid of unnecessary rcutils_custom_add_{gtest,gmock}
• Get rid of unnecessary and unused RMW switching for logging tests.
• Remove unnecessary IS_OUTPUT_COLORIZED macro.
• Rename logging internal structures to use our new convention.
• Make all of the logging 'expand' methods static.
• Fix up error checking for RCUTILS_CONSOLE_STDOUT_LINE_BUFFERED.
• Cleanup error handling for the RCUTILS_CONSOLE_OUTPUT_FORMAT checks.
• Revamp error handling in rcutils_logging_initialize_with_allocator.
• Revamp rcutils_logging_initialize_with_allocator.
• Make a few logging global variables static.
• Optimize calls via the RCUTILS_LOG macros. (#369)
• time_unix: add zephyr posix time (#368)
• Optimize the implementation of rcutils_char_array_strncpy. (#367)
• strdup.c: fix arbitrary length overread (#366)
• Mirror rolling to master
• strdup.c: fix 1 byte buffer overread (#363)
• Clarify duration arg description in logging macros (#359)
• Contributors: Abrar Rahman Protyasha, Audrow Nash, Chris Lalancette, Felipe Neves, Yakumoo, guijan

5.2.0 (2022-04-29)

• Update rcutils_steady_time_now to return the same data as std::chrono (#357)
• Contributors: Chris Lalancette

5.1.1 (2022-03-31)

• Update launch test for change related to enviroment variables in launch (#354)
• Contributors: Jacob Perron

5.1.0 (2022-03-01)

• Remove dst_size from strlen usage (#353)
• Install headers to include${PROJECT_NAME} (#351)
• Contributors: Jorge Perez, Shane Loretz

5.0.1 (2022-01-14)

• Use static_cast instead of C-style cast (#349)
• Contributors: Jacob Perron

5.0.0 (2021-11-01)

• Fixing up documentation build when using rosdoc2 (#344)
• Stop double-defining structs. (#333)
• Use FindPython3 explicitly instead of FindPythonInterp implicitly (#345)
• Fix build on Android (#342)
• Deprecate get_env.h and move content to env.{h,c} (#340)
• Contributors: Chris Lalancette, Christophe Bedard, Ivan Santiago Paunovic, Shane Loretz, William Woodall

4.0.2 (2021-04-12)

• Declare dependency on libatomic (#338)
• Contributors: Scott K Logan

4.0.1 (2021-04-06)

• updating quality declaration links (re: ros2/docs.ros2.org#52) (#335)
• Contributors: shonigmann

4.0.0 (2021-03-18)

• Quiet down a warning in release mode. (#334)
• Make the logging separate char an implementation detail. (#332)
• Performance tests demo (#288)
• Remove references of __xstat (#330)
• Update the documentation to be more consistent. (#331)
• Shorten some excessively long lines of CMake (#328)
• qnx-support: include sys/link.h & avoid using dlinfo (#327)
• QNX uses XSI-compliant (#326)
• Contributors: Ahmed Sobhy, Chris Lalancette, Homalozoa X, Jorge Perez, Scott K Logan

3.1.0 (2021-01-25)

• Add an API for directory iteration (#323)
• Fix a leak during error handling in dir size calculation (#324)
• Fix rcutils_shared_library_t path on Windows. (#322)
• Check linker flags instead of assuming compiler correlation. (#321)
• Improve shared library relative paths handling (#320)
• Contributors: Michel Hidalgo, Scott K Logan

3.0.0 (2020-12-02)

• Update rcutils_calculate_directory_size() to support recursion (#306)
• Updating QD to QL 1 (#317)
• Address unused return values found in scan-build (#316)
• use one copy for continuous area instead of loop copy (#312)
• use a better way to check whether string is empty (#315)
• Use helper funciton to copy string (#314)
• Disable a Windows platform warning. (#311)
• Fix format of code description on document (#313)
• Make sure to check the return values of rcutils APIs. (#302)
• Contributors: Barry Xu, Chen Lihui, Chris Lalancette, Stephen Brawner

2.2.0 (2020-10-19)

• Add rcutils_expand_user() to expand user directory in path (#298)
• Update the maintainers. (#299)
• Remove the temporary variable in RCUTILS_LOGGING_AUTOINIT (#290)
• Contributors: Chris Lalancette, Christophe Bedard, Felix Endres

2.1.0 (2020-10-02)

• Add RCUTILS_NO_FAULT_INJECTION() macro. (#295)
• Inject faults on rcutils_get_env() and rcutils_set_env() call. (#292)
• env.h and get_env.h docblock fixes (#291)
• Introduce rcutils_strcasecmp, case insensitive string compare. (#280)
• Stop using fprintf to avoid using file handles by changing as few lines of code as possible. (#289)
• Defines QNX implementation for rcutils_get_platform_library_name (#287)
• Contributors: Ahmed Sobhy, Ivan Santiago Paunovic, Michel Hidalgo, tomoya

2.0.0 (2020-08-28)

• Add RCUTILS_CAN_SET_ERROR_MSG_AND_RETURN_WITH_ERROR_OF() macro. (#284) To fault inject error messages as well as return codes.
• Change rcutils_fault_injection_set_count to use int64_t (#283)
• adds QNX support for rcutils_get_executable_name (#282)
• Add fault injection hooks to default allocator (#277)
• Fault injection macros and functionality (plus example) (#264)
• ensure -fPIC is used when building a static lib (#276)
• Drop vsnprintf mocks entirely. (#275) Binary API is not portable across platforms and compilation config.
• Fix vsnprintf mocks for Release builds. (#274)
• Improve test coverage mocking system calls (#272)
• Use mimick/mimick.h header (#273)
• Add mock test for rcutils/strerror (#265)
• Add compiler option -Wconversion and add explicit casts for conversions that may alter the value or change the sign (#263) See https://github.com/ros2/rcutils/pull/263#issuecomment-663252537.
• Removed doxygen warnings (#266) (#268)
• Removed doxygen warnings (#266)
• Force _GNU_SOURCE if glibc is used. (#267)
• Add parenthesis around the argument in time conversion macros defined in time.h (#261)
• Contributors: Ahmed Sobhy, Alejandro Hernández Cordero, Dirk Thomas, Johannes Meyer, Jorge Perez, Michel Hidalgo, brawner

1.1.0 (2020-06-26)

• Add token join macros (#262)
• Add rcutils_string_array_sort function (#248)
• Add rcutils_string_array_resize function (#247)
• Increase testing coverage of rcutils to 95% (#258)
• Update QUALITY_DECLARATION to reflect QL 2 status (#260)
• Update version stability section of quality declaration for 1.0 (#256)
• Contributors: Alejandro Hernández Cordero, Jorge Perez, Karsten Knese, Michel Hidalgo, Scott K Logan, Steven! Ragnarök, Stephen Brawner

1.0.1 (2020-06-03)

• Set appropriate size for buffered logging on Windows (logging.c) (#259)
• Add Security Vulnerability Policy pointing to REP-2006
• Updates to QD to be more like other ones
• Contributors: Chris Lalancette, Stephen Brawner

1.0.0 (2020-05-26)

• Improved implementation and testing for empty rcutils_string_array_t (#246)
• Contributors: Scott K Logan

0.9.2 (2020-05-22)

• Move likely/unlikely macros from logging.h to macros.h (#253)
• Add rcutils_set_env function (#250)
• Reset error state after testing expected errors (#251)
• Fix a link to REP-2004 (#245)
• Contributors: Ivan Santiago Paunovic, Scott K Logan, Shota Aoki

0.9.1 (2020-05-08)

• Blast545/fix qd missing section (#243)
• update rcutils_get_env to always use getenv (#237)
• Contributors: Jorge Perez, Suyash Behera

0.9.0 (2020-04-24)

• Improved documentation (#225)
• Increased test coverage (#224)
• Set errno to EINVAL when explicitly returning -1 (#239)
• Don't assume errno is set to 0 on success on Windows (#238)
• Make sure to initialize buffers for logging testing (#233)
• Add deprecated with message macro (#235)
• Don't check GetLastError() on success (#236)
• Add a RCUTILS_DEPRECATED macro to enable platform specific deprecation (#234)
• Don't leak memory on realloc failing (#232)
• Assume WIN32 HINSTANCE is a void * (#230)
• Use ament_export_targets() (#228)
• Add freebsd support (#223)
• Added debug version for library names (#227)
• Fixed condition in rcutils_get_platform_library_name (#226)
• Added rcutils_is_shared_library_loaded function (#222)
• Export interfaces in a addition to include directories / libraries (#221)
• Included utils to load, unload and get symbols from shared libraries (#215)
• Check and link against libatomic (#172) (#178)
• Remove test for large allocation failure (#214)
• Increase rcutils line testing coverage (#208)
• Don't both print with fprintf and RCUTILS_SET_ERROR_MSG. (#213)
• All logging to the same stream (#196)
• Style update to match uncrustify with explicit language (#210)
• Add in a concurrent test to test_logging_output_format.py (#209)
• Fix bug in split function (#206)
• Fixes in comments (#207)
• Code style only: wrap after open parenthesis if not in one line (#203)
• Split visibility macro project independent logic (#194)
• Increase max length of env var value on Windows to 32767 (#201)
• Improve error message on Windows when rcutils_get_env fails (#200)
• Fix filesystem tests to account for extra byte on Windows (#199)
• Calculate file and directory size (#197)
• Fix race in rcutils launch_tests (#193)
• Changing default logging format to include timestamp (#190)
• Contributors: Alejandro Hernández Cordero, Chris Lalancette, Dirk Thomas, Jorge Perez, Karsten Knese, Peter Baughman, Scott K Logan, Shane Loretz, Steven Macenski, Thomas Moulard, Tully Foote, Michael Dodson

0.8.4 (2019-11-18)

• fix type of logging feature keys (#192)
• Contributors: Dirk Thomas

0.8.3 (2019-11-12)

• Fix uninitialized handle error (#187)
• Use Win32 wrapper around 64 bit atomic operations (#186)
• Contributors: Sean Kelly

0.8.2 (2019-10-23)

• Specify working directory for filesystem test (#185)
• Make use of time source type for throttling logs (#183)
• Remove ready_fn - will be replaced by ReadyToTest() (#184)
• Contributors: Brian Marchi, Dan Rose, Peter Baughman

0.8.1 (2019-10-03)

• Implement rcutils_mkdir. (#166)
• Contributors: Chris Lalancette

0.8.0 (2019-09-24)

• Make g_rcutils_log_severity_names public and immutable. (#180)
• use _WIN32 instead of WIN32 (#179)
• Revert "check and link against libatomic (#172)" (#177)
• check and link against libatomic (#172)
• Rewrite test_logging_throttle tests: (#167)
• Disable uncrustify indentation check for macros that use windows [__pragma]{.title-ref} (#164)
• Fix armhf warning (#163)
• Contributors: Christian Rauch, Dirk Thomas, Emerson Knapp, Michel Hidalgo, Shane Loretz, jpsamper2009

0.7.3 (2019-05-29)

• getprogname() is the correct API to use on Android. (#162)
• Contributors: Chris Lalancette

0.7.1 (2019-05-08)

• Add function rcutils_string_array_cmp (#144)
• Rename result variable for clarity. (#157)
• Add in utilities needed for log location (#155)
• remove macros from source file (#156)
• Migrate launch tests to new launch_testing features & API (#140)
• Use GCC extension for printf-like functions (#154)
• Fix leak in test_logging.cpp (#153)
• Fix leak in test_logging_macros.cpp (#152)
• Fix remaining leaks in test_string_map.cpp (#151)
• Fix a leak in test_array_list.cpp (#149)
• Contributors: Chris Lalancette, Dirk Thomas, Jacob Perron, Michel Hidalgo, Steven! Ragnarök, Thomas Moulard

0.7.0 (2019-04-13)

• Fix ASAN failure in test_string_map.cpp (#147)
• Add tests for stdatomic_helper.h and fix bugs (#150)
• Windows messages when atomic type is unsupported (#145)
• Use CMake property to determine when to use memory_tools. (#139)
• Add section about DCO to CONTRIBUTING.md
• Use ament_target_dependencies where possible. (#137)
• Fix doc typo in string_map.h. (#138)
• Add launch along with launch_testing as test dependencies. (#136)
• Drops legacy launch API usage. (#134)
• Contributors: Dirk Thomas, Jacob Perron, Michel Hidalgo, Shane Loretz, Steven! Ragnarök, Thomas Moulard, ivanpauno

0.6.2 (2019-02-07)

• Adding an ArrayList and HashMap implementation to rcutils (#131)
• Change uncrustify max line length to 0 (#133)
• Contributors: Jacob Perron, Nick Burek

0.6.1 (2018-12-06)

• Logging (#127)
• fixes to support including in c++ and fetch_add (#129)
• reiterate over char array (#130)
• add rcutils_unsigned_char_array_t (#125)
• Contributors: Karsten Knese, Nick Burek, William Woodall

0.6.0 (2018-11-16)

• Added rcutils_to_native_path function (#119)
• Moved stdatomic helper to rcutils (#126)
• Fixed warning in release build due to assert (#124)
• Updated to avoid dynamic memory allocation during error handling (#121)
• Added macro semicolons (#120)
• Added LL suffix to avoid c4307 (#118)
• Updated to use the same allocator to free allocated message (#115)
• Renamed rcutils_serialized_message -> rcutils_char_array (#111)
• Moved serialized_message from rmw (#110)
• Updated to verify that the requested allocation size does not overflow. (#109)
• Contributors: Chris Lalancette, Jacob Perron, Karsten Knese, Mikael Arguedas, Ruffin, Shane Loretz, Todd Malsbary, William Woodall

0.5.1 (2018-06-28)

• Removed redundant stat() call (#108)

0.5.0 (2018-06-20)

• Audited use of malloc/realloc/calloc/free to make sure it always goes through an rcutils_allocator_t (#102)
• Added ability to include a timestamp when a console logging message happens (#85)
• Updated to use new memory_tools from osrf_testing_tools_cpp (#101)
• Fixed a possible bug by preventing the default logger's level from being unset (#106)
• Updated to use launch.legacy instead of launch (now used for new launch system) (#105)
• Fixed a memory check issue in split.c (#104)
  • Signed-off-by: testkit <<cathy.shen@intel.com>>
• Added RCUTILS_CONSOLE_STDOUT_LINE_BUFFERED to control flusing of output from the default output handler of the logging macros. (#98)
• Can now control shared/static linking via BUILD_SHARED_LIBS (#94)
• Addressed some MISRA C compliance issues (#91)
• Fixed a steady time overflow issue (#87)
• Changed rcutils_time_point_value_t type from uint64_t to int64_t (#84)
• Fixed out-of-bounds read issue (#83)
  • Signed-off-by: Ethan Gao <<ethan.gao@linux.intel.com>>
• Contributors: Dirk Thomas, Ethan Gao, Michael Carroll, Mikael Arguedas, Sagnik Basu, Shane Loretz, William Woodall, cshen, dhood, serge-nikulin