rcl  master
C API providing common ROS client library functionality.
Classes | Macros | Typedefs | Functions
arguments.h File Reference
#include "rcl/allocator.h"
#include "rcl/log_level.h"
#include "rcl/macros.h"
#include "rcl/types.h"
#include "rcl/visibility_control.h"
#include "rcl_yaml_param_parser/types.h"
Include dependency graph for arguments.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

struct  rcl_arguments_t
 Hold output of parsing command line arguments. More...
 

Macros

#define RCL_ROS_ARGS_FLAG   "--ros-args"
 The command-line flag that delineates the start of ROS arguments.
 
#define RCL_ROS_ARGS_EXPLICIT_END_TOKEN   "--"
 The token that delineates the explicit end of ROS arguments.
 
#define RCL_PARAM_FLAG   "--param"
 The ROS flag that precedes the setting of a ROS parameter.
 
#define RCL_SHORT_PARAM_FLAG   "-p"
 The short version of the ROS flag that precedes the setting of a ROS parameter.
 
#define RCL_PARAM_FILE_FLAG   "--params-file"
 The ROS flag that precedes a path to a file containing ROS parameters.
 
#define RCL_REMAP_FLAG   "--remap"
 The ROS flag that precedes a ROS remapping rule.
 
#define RCL_SHORT_REMAP_FLAG   "-r"
 The short version of the ROS flag that precedes a ROS remapping rule.
 
#define RCL_ENCLAVE_FLAG   "--enclave"
 The ROS flag that precedes the name of a ROS security enclave.
 
#define RCL_SHORT_ENCLAVE_FLAG   "-e"
 The short version of the ROS flag that precedes the name of a ROS security enclave.
 
#define RCL_LOG_LEVEL_FLAG   "--log-level"
 The ROS flag that precedes the ROS logging level to set.
 
#define RCL_EXTERNAL_LOG_CONFIG_FLAG   "--log-config-file"
 The ROS flag that precedes the name of a configuration file to configure logging.
 
#define RCL_LOG_STDOUT_FLAG_SUFFIX   "stdout-logs"
 
#define RCL_LOG_ROSOUT_FLAG_SUFFIX   "rosout-logs"
 
#define RCL_LOG_EXT_LIB_FLAG_SUFFIX   "external-lib-logs"
 

Typedefs

typedef struct rcl_arguments_t rcl_arguments_t
 Hold output of parsing command line arguments.
 

Functions

rcl_arguments_t rcl_get_zero_initialized_arguments (void)
 Return a rcl_arguments_t struct with members initialized to NULL.
 
rcl_ret_t rcl_parse_arguments (int argc, const char *const argv[], rcl_allocator_t allocator, rcl_arguments_t *args_output)
 Parse command line arguments into a structure usable by code. More...
 
int rcl_arguments_get_count_unparsed (const rcl_arguments_t *args)
 Return the number of arguments that were not ROS specific arguments. More...
 
rcl_ret_t rcl_arguments_get_unparsed (const rcl_arguments_t *args, rcl_allocator_t allocator, int **output_unparsed_indices)
 Return a list of indices to non ROS specific arguments. More...
 
int rcl_arguments_get_count_unparsed_ros (const rcl_arguments_t *args)
 Return the number of ROS specific arguments that were not successfully parsed. More...
 
rcl_ret_t rcl_arguments_get_unparsed_ros (const rcl_arguments_t *args, rcl_allocator_t allocator, int **output_unparsed_ros_indices)
 Return a list of indices to unknown ROS specific arguments that were left unparsed. More...
 
int rcl_arguments_get_param_files_count (const rcl_arguments_t *args)
 Return the number of parameter yaml files given in the arguments. More...
 
rcl_ret_t rcl_arguments_get_param_files (const rcl_arguments_t *arguments, rcl_allocator_t allocator, char ***parameter_files)
 Return a list of yaml parameter file paths specified on the command line. More...
 
rcl_ret_t rcl_arguments_get_param_overrides (const rcl_arguments_t *arguments, rcl_params_t **parameter_overrides)
 Return all parameter overrides parsed from the command line. More...
 
rcl_ret_t rcl_remove_ros_arguments (char const *const argv[], const rcl_arguments_t *args, rcl_allocator_t allocator, int *nonros_argc, const char **nonros_argv[])
 Return a list of arguments with ROS-specific arguments removed. More...
 
rcl_ret_t rcl_arguments_get_log_levels (const rcl_arguments_t *arguments, rcl_log_levels_t *log_levels)
 Return log levels parsed from the command line. More...
 
rcl_ret_t rcl_arguments_copy (const rcl_arguments_t *args, rcl_arguments_t *args_out)
 Copy one arguments structure into another. More...
 
rcl_ret_t rcl_arguments_fini (rcl_arguments_t *args)
 Reclaim resources held inside rcl_arguments_t structure. More...
 

Macro Definition Documentation

◆ RCL_LOG_STDOUT_FLAG_SUFFIX

#define RCL_LOG_STDOUT_FLAG_SUFFIX   "stdout-logs"

The suffix of the ROS flag to enable or disable stdout logging (must be preceded with –enable- or –disable-).

◆ RCL_LOG_ROSOUT_FLAG_SUFFIX

#define RCL_LOG_ROSOUT_FLAG_SUFFIX   "rosout-logs"

The suffix of the ROS flag to enable or disable rosout logging (must be preceded with –enable- or –disable-).

◆ RCL_LOG_EXT_LIB_FLAG_SUFFIX

#define RCL_LOG_EXT_LIB_FLAG_SUFFIX   "external-lib-logs"

The suffix of the ROS flag to enable or disable external library logging (must be preceded with –enable- or –disable-).

Function Documentation

◆ rcl_parse_arguments()

rcl_ret_t rcl_parse_arguments ( int  argc,
const char *const  argv[],
rcl_allocator_t  allocator,
rcl_arguments_t args_output 
)

Parse command line arguments into a structure usable by code.

See also
rcl_get_zero_initialized_arguments()

ROS arguments are expected to be scoped by a leading --ros-args flag and a trailing double dash token -- which may be elided if no non-ROS arguments follow after the last --ros-args.

Remap rule parsing is supported via -r/--remap flags e.g. --remap from:=to or -r from:=to. Successfully parsed remap rules are stored in the order they were given in argv. If given arguments {"__ns:=/foo", "__ns:=/bar"} then the namespace used by nodes in this process will be /foo and not /bar.

See also
rcl_remap_topic_name()
rcl_remap_service_name()
rcl_remap_node_name()
rcl_remap_node_namespace()

Parameter override rule parsing is supported via -p/--param flags e.g. --param name:=value or -p name:=value.

The default log level will be parsed as --log-level level and logger levels will be parsed as multiple --log-level name:=level, where level is a name representing one of the log levels in the RCUTILS_LOG_SEVERITY enum, e.g. info, debug, warn, not case sensitive. If multiple of these rules are found, the last one parsed will be used.

If an argument does not appear to be a valid ROS argument e.g. a -r/--remap flag followed by anything but a valid remap rule, parsing will fail immediately.

If an argument does not appear to be a known ROS argument, then it is skipped and left unparsed.

See also
rcl_arguments_get_count_unparsed_ros()
rcl_arguments_get_unparsed_ros()

All arguments found outside a --ros-args ... -- scope are skipped and left unparsed.

See also
rcl_arguments_get_count_unparsed()
rcl_arguments_get_unparsed()

Attribute Adherence
Allocates Memory Yes
Thread-Safe Yes
Uses Atomics No
Lock-Free Yes
Parameters
[in]argcThe number of arguments in argv.
[in]argvThe values of the arguments.
[in]allocatorA valid allocator.
[out]args_outputA structure that will contain the result of parsing. Must be zero initialized before use.
Returns
RCL_RET_OK if the arguments were parsed successfully, or
RCL_RET_INVALID_ROS_ARGS if an invalid ROS argument is found, or
RCL_RET_INVALID_ARGUMENT if any function arguments are invalid, or
RCL_RET_BAD_ALLOC if allocating memory failed, or
RCL_RET_ERROR if an unspecified error occurs.

◆ rcl_arguments_get_count_unparsed()

int rcl_arguments_get_count_unparsed ( const rcl_arguments_t args)

Return the number of arguments that were not ROS specific arguments.


Attribute Adherence
Allocates Memory No
Thread-Safe Yes
Uses Atomics No
Lock-Free Yes
Parameters
[in]argsAn arguments structure that has been parsed.
Returns
number of unparsed arguments, or
-1 if args is NULL or zero initialized.

◆ rcl_arguments_get_unparsed()

rcl_ret_t rcl_arguments_get_unparsed ( const rcl_arguments_t args,
rcl_allocator_t  allocator,
int **  output_unparsed_indices 
)

Return a list of indices to non ROS specific arguments.

Non ROS specific arguments may have been provided i.e. arguments outside a '–ros-args' scope. This function populates an array of indices to these arguments in the original argv array. Since the first argument is always assumed to be a process name, the list will always contain the index 0.


Attribute Adherence
Allocates Memory Yes
Thread-Safe Yes
Uses Atomics No
Lock-Free Yes
Parameters
[in]argsAn arguments structure that has been parsed.
[in]allocatorA valid allocator.
[out]output_unparsed_indicesAn allocated array of indices into the original argv array. This array must be deallocated by the caller using the given allocator. If there are no unparsed args then the output will be set to NULL.
Returns
RCL_RET_OK if everything goes correctly, or
RCL_RET_INVALID_ARGUMENT if any function arguments are invalid, or
RCL_RET_BAD_ALLOC if allocating memory failed, or
RCL_RET_ERROR if an unspecified error occurs.

◆ rcl_arguments_get_count_unparsed_ros()

int rcl_arguments_get_count_unparsed_ros ( const rcl_arguments_t args)

Return the number of ROS specific arguments that were not successfully parsed.


Attribute Adherence
Allocates Memory No
Thread-Safe Yes
Uses Atomics No
Lock-Free Yes
Parameters
[in]argsAn arguments structure that has been parsed.
Returns
number of unparsed ROS specific arguments, or
-1 if args is NULL or zero initialized.

◆ rcl_arguments_get_unparsed_ros()

rcl_ret_t rcl_arguments_get_unparsed_ros ( const rcl_arguments_t args,
rcl_allocator_t  allocator,
int **  output_unparsed_ros_indices 
)

Return a list of indices to unknown ROS specific arguments that were left unparsed.

Some ROS specific arguments may not have been recognized, or were not intended to be parsed by rcl. This function populates an array of indices to these arguments in the original argv array.


Attribute Adherence
Allocates Memory Yes
Thread-Safe Yes
Uses Atomics No
Lock-Free Yes
Parameters
[in]argsAn arguments structure that has been parsed.
[in]allocatorA valid allocator.
[out]output_unparsed_ros_indicesAn allocated array of indices into the original argv array. This array must be deallocated by the caller using the given allocator. If there are no unparsed ROS specific arguments then the output will be set to NULL.
Returns
RCL_RET_OK if everything goes correctly, or
RCL_RET_INVALID_ARGUMENT if any function arguments are invalid, or
RCL_RET_BAD_ALLOC if allocating memory failed, or
RCL_RET_ERROR if an unspecified error occurs.

◆ rcl_arguments_get_param_files_count()

int rcl_arguments_get_param_files_count ( const rcl_arguments_t args)

Return the number of parameter yaml files given in the arguments.


Attribute Adherence
Allocates Memory No
Thread-Safe No
Uses Atomics No
Lock-Free Yes
Parameters
[in]argsAn arguments structure that has been parsed.
Returns
number of yaml files, or
-1 if args is NULL or zero initialized.

◆ rcl_arguments_get_param_files()

rcl_ret_t rcl_arguments_get_param_files ( const rcl_arguments_t arguments,
rcl_allocator_t  allocator,
char ***  parameter_files 
)

Return a list of yaml parameter file paths specified on the command line.


Attribute Adherence
Allocates Memory Yes
Thread-Safe No
Uses Atomics No
Lock-Free Yes
Parameters
[in]argumentsAn arguments structure that has been parsed.
[in]allocatorA valid allocator.
[out]parameter_filesAn allocated array of paramter file names. This array must be deallocated by the caller using the given allocator. The output is NULL if there were no paramter files.
Returns
RCL_RET_OK if everything goes correctly, or
RCL_RET_INVALID_ARGUMENT if any function arguments are invalid, or
RCL_RET_BAD_ALLOC if allocating memory failed, or
RCL_RET_ERROR if an unspecified error occurs.

◆ rcl_arguments_get_param_overrides()

rcl_ret_t rcl_arguments_get_param_overrides ( const rcl_arguments_t arguments,
rcl_params_t **  parameter_overrides 
)

Return all parameter overrides parsed from the command line.

Parameter overrides are parsed directly from command line arguments and parameter files provided in the command line.


Attribute Adherence
Allocates Memory Yes
Thread-Safe No
Uses Atomics No
Lock-Free Yes
Parameters
[in]argumentsAn arguments structure that has been parsed.
[out]parameter_overridesParameter overrides as parsed from command line arguments. This structure must be finalized by the caller. The output is NULL if no parameter overrides were parsed.
Returns
RCL_RET_OK if everything goes correctly, or
RCL_RET_INVALID_ARGUMENT if any function arguments are invalid, or
RCL_RET_BAD_ALLOC if allocating memory failed, or
RCL_RET_ERROR if an unspecified error occurs.

◆ rcl_remove_ros_arguments()

rcl_ret_t rcl_remove_ros_arguments ( char const *const  argv[],
const rcl_arguments_t args,
rcl_allocator_t  allocator,
int *  nonros_argc,
const char **  nonros_argv[] 
)

Return a list of arguments with ROS-specific arguments removed.

Some arguments may not have been intended as ROS arguments. This function populates an array of the aruments in a new argv array. Since the first argument is always assumed to be a process name, the list will always contain the first value from the argument vector.


Attribute Adherence
Allocates Memory Yes
Thread-Safe Yes
Uses Atomics No
Lock-Free Yes
Parameters
[in]argvThe argument vector
[in]argsAn arguments structure that has been parsed.
[in]allocatorA valid allocator.
[out]nonros_argcThe count of arguments that aren't ROS-specific
[out]nonros_argvAn allocated array of arguments that aren't ROS-specific This array must be deallocated by the caller using the given allocator. If there are no non-ROS args, then the output will be set to NULL.
Returns
RCL_RET_OK if everything goes correctly, or
RCL_RET_INVALID_ARGUMENT if any function arguments are invalid, or
RCL_RET_BAD_ALLOC if allocating memory failed, or
RCL_RET_ERROR if an unspecified error occurs.

◆ rcl_arguments_get_log_levels()

rcl_ret_t rcl_arguments_get_log_levels ( const rcl_arguments_t arguments,
rcl_log_levels_t log_levels 
)

Return log levels parsed from the command line.

Log levels are parsed directly from command line arguments.


Attribute Adherence
Allocates Memory Yes
Thread-Safe No
Uses Atomics No
Lock-Free Yes
Parameters
[in]argumentsAn arguments structure that has been parsed.
[out]log_levelsLog levels as parsed from command line arguments. The output must be finished by the caller if the function successes.
Returns
RCL_RET_OK if everything goes correctly, or
RCL_RET_INVALID_ARGUMENT if any function arguments are invalid, or
RCL_RET_BAD_ALLOC if allocating memory failed.

◆ rcl_arguments_copy()

rcl_ret_t rcl_arguments_copy ( const rcl_arguments_t args,
rcl_arguments_t args_out 
)

Copy one arguments structure into another.


Attribute Adherence
Allocates Memory Yes
Thread-Safe No
Uses Atomics No
Lock-Free Yes
Parameters
[in]argsThe structure to be copied. Its allocator is used to copy memory into the new structure.
[out]args_outA zero-initialized arguments structure to be copied into.
Returns
RCL_RET_OK if the structure was copied successfully, or
RCL_RET_INVALID_ARGUMENT if any function arguments are invalid, or
RCL_RET_BAD_ALLOC if allocating memory failed, or
RCL_RET_ERROR if an unspecified error occurs.

◆ rcl_arguments_fini()

rcl_ret_t rcl_arguments_fini ( rcl_arguments_t args)

Reclaim resources held inside rcl_arguments_t structure.


Attribute Adherence
Allocates Memory No
Thread-Safe Yes
Uses Atomics No
Lock-Free Yes
Parameters
[in]argsThe structure to be deallocated.
Returns
RCL_RET_OK if the memory was successfully freed, or
RCL_RET_INVALID_ARGUMENT if any function arguments are invalid, or
RCL_RET_ERROR if an unspecified error occurs.