#include "rcl/allocator.h"
#include "rcl/macros.h"
#include "rcl/types.h"
#include "rcl/visibility_control.h"

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

Macros
#define	RCL_LOG_LEVEL_ARG_RULE "__log_level:="

#define	RCL_PARAM_FILE_ARG_RULE "__params:="

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

Functions
rcl_arguments_t	rcl_get_zero_initialized_arguments (void)
	Return a rcl_node_t struct with members initialized to `NULL`. More...

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 successfully parsed. 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 indexes that weren't successfully parsed. 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_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_copy (rcl_allocator_t error_alloc, 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...

rcl_arguments_t *	rcl_get_global_arguments ()
	Get a global instance of command line arguments. More...

Macro Definition Documentation

◆ RCL_LOG_LEVEL_ARG_RULE

#define RCL_LOG_LEVEL_ARG_RULE "__log_level:="

◆ RCL_PARAM_FILE_ARG_RULE

#define RCL_PARAM_FILE_ARG_RULE "__params:="

Typedef Documentation

◆ rcl_arguments_t

typedef struct rcl_arguments_t rcl_arguments_t

Hold output of parsing command line arguments.

Function Documentation

◆ rcl_get_zero_initialized_arguments()

rcl_arguments_t rcl_get_zero_initialized_arguments ( void )

Return a rcl_node_t struct with members initialized to NULL.

◆ 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.

If an argument does not appear to be a valid ROS argument then it is skipped and parsing continues with the next argument in argv.

See also: rcl_get_zero_initialized_arguments(); rcl_arguments_get_count_unparsed(); rcl_arguments_get_unparsed()

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.

The default log level will be parsed as __log_level:=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.

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

Attribute	Adherence —
Allocates Memory	Yes
Thread-Safe	Yes
Uses Atomics	No
Lock-Free	Yes

Parameters

[in]	argc	The number of arguments in argv.
[in]	argv	The values of the arguments.
[in]	allocator	A valid allocator.
[out]	args_output	A 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_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 successfully parsed.

Attribute	Adherence —
Allocates Memory	No
Thread-Safe	Yes
Uses Atomics	No
Lock-Free	Yes

Parameters

[in] args An 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 indexes that weren't successfully parsed.

Some arguments may not have been successfully parsed, or were not intended as ROS arguments. This function populates an array of indexes 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]	args	An arguments structure that has been parsed.
[in]	allocator	A valid allocator.
[out]	output_unparsed_indices	An 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_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] args An 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]	arguments	An arguments structure that has been parsed.
[in]	allocator	A valid allocator.
[out]	parameter_files	An 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_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]	argv	The argument vector
[in]	args	An arguments structure that has been parsed.
[in]	allocator	A valid allocator.
[out]	nonros_argc	The count of arguments that aren't ROS-specific
[out]	nonros_argv	An 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_copy()

rcl_ret_t rcl_arguments_copy	(	rcl_allocator_t	error_alloc,
		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]	error_alloc	an alocator to use if an error occurs. This allocator is not used to allocate args_out.
[in]	args	The structure to be copied. Its allocator is used to copy memory into the new structure.
[out]	args_out	A 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]	args	The structure to be deallocated.
[in]	allocator	A valid allocator.

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.

◆ rcl_get_global_arguments()

rcl_arguments_t* rcl_get_global_arguments ( )

Get a global instance of command line arguments.

See also: rcl_init(int, char **, rcl_allocator_t); rcl_shutdown() This returns parsed command line arguments that were passed to rcl_init(). The value returned by this function is undefined before rcl_init() is called and after rcl_shutdown() is called. The return value must not be finalized.

Attribute	Adherence —
Allocates Memory	No
Thread-Safe	Yes
Uses Atomics	No
Lock-Free	Yes

Returns: a global instance of parsed command line arguments.

Classes

Macros

Typedefs

Functions

Macro Definition Documentation

◆ RCL_LOG_LEVEL_ARG_RULE

◆ RCL_PARAM_FILE_ARG_RULE

Typedef Documentation

◆ rcl_arguments_t

Function Documentation

◆ rcl_get_zero_initialized_arguments()

◆ rcl_parse_arguments()

◆ rcl_arguments_get_count_unparsed()

◆ rcl_arguments_get_unparsed()

◆ rcl_arguments_get_param_files_count()

◆ rcl_arguments_get_param_files()

◆ rcl_remove_ros_arguments()

◆ rcl_arguments_copy()

◆ rcl_arguments_fini()

◆ rcl_get_global_arguments()