Typedefs
typedef void(*	le_arg_FlagCallbackFunc_t) (void)

typedef void(*	le_arg_IntCallbackFunc_t) (int value)

typedef void(*	le_arg_StringCallbackFunc_t) (const char *value)

typedef size_t(*	le_arg_ErrorHandlerFunc_t) (size_t argIndex, le_result_t errorCode)

Functions
const char *	le_arg_GetProgramName (void)

size_t	le_arg_NumArgs (void)

const char *	le_arg_GetArg (size_t argIndex)

le_result_t	le_arg_GetFlagOption (const char shortName, const char longName)

le_result_t	le_arg_GetIntOption (int varPtr, const char shortName, const char *longName)

le_result_t	le_arg_GetStringOption (const char *varPtr, const char shortName, const char *longName)

void	le_arg_SetFlagVar (bool varPtr, const char shortName, const char *longName)

void	le_arg_SetIntVar (int varPtr, const char shortName, const char *longName)

void	le_arg_SetStringVar (const char *varPtr, const char shortName, const char *longName)

void	le_arg_SetFlagCallback (le_arg_FlagCallbackFunc_t func, const char shortName, const char longName)

void	le_arg_SetIntCallback (le_arg_IntCallbackFunc_t func, const char shortName, const char longName)

void	le_arg_SetStringCallback (le_arg_StringCallbackFunc_t func, const char shortName, const char longName)

void	le_arg_AddPositionalCallback (le_arg_StringCallbackFunc_t func)

void	le_arg_AllowMorePositionalArgsThanCallbacks (void)

void	le_arg_AllowLessPositionalArgsThanCallbacks (void)

void	le_arg_SetErrorHandler (le_arg_ErrorHandlerFunc_t errorHandlerFunc)

void	le_arg_SetExitOnError (bool exitOnError)

le_result_t	le_arg_GetScanResult (void)

void	le_arg_Scan (void)

void	le_arg_SetArgs (const size_t argc, const char **argv)

le_result_t	le_arg_Split (const char firstStr, char cmdlinePtr, int argc, const char *argv)

Detailed Description

Legato Command Line Arguments API include file.

Copyright (C) Sierra Wireless Inc.

Typedef Documentation

◆ le_arg_ErrorHandlerFunc_t

typedef size_t(* le_arg_ErrorHandlerFunc_t) (size_t argIndex, le_result_t errorCode)

Error handler function prototype. All argument error handler functions (passed into le_arg_SetErrorHandler() ) must conform to this prototype.

Errors that can be reported to this function are:

LE_BAD_PARAMETER - The argument is not expected.
LE_NOT_FOUND - The argument should have a value, but no value was given.
LE_FORMAT_ERROR - The argument should have a numerical value, but was given something else.
LE_OUT_OF_RANGE - Magnitude of numerical argument too big to be stored in chosen data type.
LE_OVERFLOW - Too many positional arguments found on command line.
LE_UNDERFLOW - Too few positional arguments found on command line.
LE_UNSUPPORTED - The argument should not have a value but was given one.

Returns: The number of arguments to skip before resuming argument scanning. 0 = resume scanning at argIndex + 1; 1 = resume at argIndex + 2; etc.

Parameters

argIndex	Index of argument that is bad (0 = first arg after program name).
errorCode	Code indicating the type of error that was encountered.

◆ le_arg_FlagCallbackFunc_t

typedef void(* le_arg_FlagCallbackFunc_t) (void)

Flag argument callback functions registered using le_arg_SetFlagCallback() must conform to this prototype.

If the flag appears N times on the command line, the callback will be called N times.

◆ le_arg_IntCallbackFunc_t

typedef void(* le_arg_IntCallbackFunc_t) (int value)

Integer argument callback functions registered using le_arg_SetIntCallback() must conform to this prototype.

If the option appears N times on the command line, the callback will be called N times.

Parameters

value The value of the integer option.

◆ le_arg_StringCallbackFunc_t

typedef void(* le_arg_StringCallbackFunc_t) (const char *value)

String argument callback functions registered using le_arg_SetStringCallback() or le_arg_AddPositionalCallback() must conform to this prototype.

If the option appears N times on the command line, the callback will be called N times.

Parameters

value Pointer to the value of the string option.

Function Documentation

◆ le_arg_AddPositionalCallback()

void le_arg_AddPositionalCallback ( le_arg_StringCallbackFunc_t func )

Register a callback function to be called if an argument appears outside of any options. For example, in the following command-line, "foo" and "bar" are positional arguments (while "-l" is a flag option and "ls" is the program name):

$ ls -l foo bar

Each callback function registered using this method is added to the positional callback list. When the first positional argument is encountered, the first positional callback function is called. When the Nth positional argument is encountered, the Nth positional callback is called. If there are N positional arguments and M positional callbacks, and N > M, then the last positional callback will be called once for each positional argument from M through N, inclusive.

Parameters

func	The callback function address.

◆ le_arg_AllowLessPositionalArgsThanCallbacks()

void le_arg_AllowLessPositionalArgsThanCallbacks ( void )

Tell the argument parser to allow less positional arguments than positional callbacks.

If less positional arguments are encountered than the number of positional callbacks when this is allowed, any positional callbacks that don't have arguments won't be called. If this is not allowed, le_arg_Scan() will print an error message to the standard error stream and exit the process with EXIT_FAILURE if there are less positional arguments than there are positional callbacks.

◆ le_arg_AllowMorePositionalArgsThanCallbacks()

void le_arg_AllowMorePositionalArgsThanCallbacks ( void )

Tell the argument parser to allow more positional arguments than positional callbacks.

If more positional arguments are encountered than the number of positional callbacks when this is allowed, le_arg_Scan() will call the last positional callback again for each extra positional argument it finds. If this is not allowed, le_arg_Scan() will print an error message to the standard error stream and exit the process with EXIT_FAILURE if there are more positional arguments than there are positional callbacks.

◆ le_arg_GetArg()

const char* le_arg_GetArg ( size_t argIndex )

Gets a command line argument by index.

Returns: Pointer to the argument string (null-terminated), or NULL if the index is out of range.

Parameters

[in] argIndex Index of the argument (0 = first argument after the program name).

◆ le_arg_GetFlagOption()

le_result_t le_arg_GetFlagOption	(	const char *	shortName,
		const char *	longName
	)

Searches the argument list for a flag option. Can search for a short name (e.g., -f) or a long name (e.g., --flag) for the same flag at the same time.

Returns

LE_OK if found,
LE_NOT_FOUND if not found,
LE_FORMAT_ERROR if found but has a value (e.g., --flag=foo).

Note: If both shortName and longName are NULL, LE_NOT_FOUND will be returned.

Parameters

[in]	shortName	Name that appears after a single '-' (can be NULL).
[in]	longName	Name that appears afer a "--" (can be NULL).

◆ le_arg_GetIntOption()

le_result_t le_arg_GetIntOption	(	int *	varPtr,
		const char *	shortName,
		const char *	longName
	)

Searches the argument list for an option with an integer value. Can search for a short name (e.g., -c 1234) or a long name (e.g., --count=1234) form of the same option at the same time.

Returns

LE_OK if found and successfully converted to an integer.
LE_NOT_FOUND if not found.
LE_FORMAT_ERROR if the option wasn't provided with an integer value.
LE_OUT_OF_RANGE - Magnitude of integer value too big to be stored in an int.

Note: If both shortName and longName are NULL, LE_NOT_FOUND will be returned.

Parameters

[out]	varPtr	Variable into which the value will be stored if found.
[in]	shortName	Name that appears after a single '-' (can be NULL).
[in]	longName	Name that appears afer a "--" (can be NULL).

◆ le_arg_GetProgramName()

const char* le_arg_GetProgramName ( void )

Gets the program name.

Returns: Pointer to the null-terminated program name string.

◆ le_arg_GetScanResult()

le_result_t le_arg_GetScanResult ( void )

Determine if argument scanning failed.

If process termination is disabled via le_arg_SetExitOnError(), then this function may be used to get the result of argument scanning (le_arg_Scan()).

Returns: The result of the last argument scan.

◆ le_arg_GetStringOption()

le_result_t le_arg_GetStringOption	(	const char **	varPtr,
		const char *	shortName,
		const char *	longName
	)

Searches the argument list for an option with a string value. Can search for a short name (e.g., -f foo) or a long name (e.g., --file=foo) form of the same option at the same time.

Note: --file= is a valid string option with an empty string ("") value. The equivalent short name version of that option would be something like -f "".

Returns

LE_OK if found.
LE_NOT_FOUND if not found.
LE_FORMAT_ERROR if the option wasn't provided with a value.

Note: If both shortName and longName are NULL, LE_NOT_FOUND will be returned.

Parameters

[out]	varPtr	Variable into which to store a pointer to the value if found.
[in]	shortName	Name that appears after a single '-' (can be NULL).
[in]	longName	Name that appears afer a "--" (can be NULL).

◆ le_arg_NumArgs()

size_t le_arg_NumArgs ( void )

Gets the number of command line arguments available not including the program name.

Returns: Number of command line arguments available.

◆ le_arg_Scan()

void le_arg_Scan ( void )

Scans the argument list, setting variables and calling callbacks registered using the le_arg_SetXxxVar(), le_arg_SetXxxCallback(), and le_arg_AddPositionalParameters() functions.

◆ le_arg_SetArgs()

void le_arg_SetArgs	(	const size_t	argc,
		const char **	argv
	)

Passes argc and argv to the argument parser for later use by le_arg_Scan().

Note: This function is normally called by main(). If the Legato application framework is automatically generating main() for you, then you can just ignore this function.

Parameters

[in]	argc	argc from main().
[in]	argv	argv from main().

◆ le_arg_SetErrorHandler()

void le_arg_SetErrorHandler ( le_arg_ErrorHandlerFunc_t errorHandlerFunc )

Register an error handler function to be called by le_arg_Scan() whenever an unexpected argument is encountered or an option's value cannot be converted to the correct data type.

Parameters

[in] errorHandlerFunc The error handler function.

◆ le_arg_SetExitOnError()

void le_arg_SetExitOnError ( bool exitOnError )

Control whether an argument scanning error should cause the process to exit.

The default behaviour is to exit. If this is set to false then le_arg_GetScanResult() should be called after le_arg_Scan() to determine if an error occured.

Parameters

[in] exitOnError Exit on scan error.

◆ le_arg_SetFlagCallback()

void le_arg_SetFlagCallback	(	le_arg_FlagCallbackFunc_t	func,
		const char *	shortName,
		const char *	longName
	)

Register a callback function to be called if a given flag option appears on the argument list.

No value is expected after the option name.

One or the other of shortName or longName may be NULL. If not NULL, these MUST be pointers to strings that are never deallocated or changed.

Parameters

func	The callback function address.
shortName	Short form of option name (e.g., "h" will match "-h").
longName	Long form of option name (e.g., "help" will match "--help").

◆ le_arg_SetFlagVar()

void le_arg_SetFlagVar	(	bool *	varPtr,
		const char *	shortName,
		const char *	longName
	)

Register a boolean variable to be set if a given flag option appears on the argument list.

No value is expected after the option name.

One or the other of shortName or longName may be NULL. If not NULL, these MUST be pointers to strings that are never deallocated or changed.

Parameters

varPtr	Ptr to the variable to be set true if the flag option is found.
shortName	Short form of option name (e.g., "h" will match "-h").
longName	Long form of option name (e.g., "help" will match "--help").

◆ le_arg_SetIntCallback()

void le_arg_SetIntCallback	(	le_arg_IntCallbackFunc_t	func,
		const char *	shortName,
		const char *	longName
	)

Register a callback function to be called if a given integer value option appears on the argument list.

An integer value is expected after the option name.

One or the other of shortName or longName may be NULL. If not NULL, these MUST be pointers to strings that are never deallocated or changed.

Parameters

func	The callback function address.
shortName	Short form of option name (e.g., "n" will match "-n 1234").
longName	Long form of name ("max-count" matches "--max-count=1234").

◆ le_arg_SetIntVar()

void le_arg_SetIntVar	(	int *	varPtr,
		const char *	shortName,
		const char *	longName
	)

Register an integer variable to be set if a given option appears on the argument list.

An integer value is expected after the option name.

One or the other of shortName or longName may be NULL. If not NULL, these MUST be pointers to strings that are never deallocated or changed.

Parameters

varPtr	Ptr to the variable to be set if the option is found.
shortName	Short form of option name (e.g., "n" will match "-n 1234").
longName	Long form of name ("max-count" matches "--max-count=1234").

◆ le_arg_SetStringCallback()

void le_arg_SetStringCallback	(	le_arg_StringCallbackFunc_t	func,
		const char *	shortName,
		const char *	longName
	)

Register a callback function to be called if a given string option appears on the argument list.

A string value is expected after the option name.

One or the other of shortName or longName may be NULL. If not NULL, these MUST be pointers to strings that are never deallocated or changed.

Parameters

func	The callback function address.
shortName	Short form of option name (e.g., "n" will match "-n foo").
longName	Long form of name ("name" matches "--name=foo").

◆ le_arg_SetStringVar()

void le_arg_SetStringVar	(	const char **	varPtr,
		const char *	shortName,
		const char *	longName
	)

Register a string variable to be set if a given option appears on the argument list.

A value is expected after the option name.

const char* namePtr = "default";
le_arg_SetStringVar(&namePtr, "n", "name");

One or the other of shortName or longName may be NULL. If not NULL, these MUST be pointers to strings that are never deallocated or changed.

Parameters

varPtr	Ptr to the variable to be set if the option is found.
shortName	Short form of option name (e.g., "n" will match "-n foo").
longName	Long form of name ("name" matches "--name=foo").

◆ le_arg_Split()

le_result_t le_arg_Split	(	const char *	firstStr,
		char *	cmdlinePtr,
		int *	argc,
		const char **	argv
	)

Tokenizes a string into individual arguments. Simple quoting is allowed using either ' or " to enclose multi-word arguments.

Returns

LE_OK on success.
LE_BAD_PARAMETER if a parameter is invalid.
LE_OUT_OF_RANGE if more arguments are present than can be captured in the provided array (those that can be captured will be).

Parameters

[in]	firstStr	A separate string to treat as the first argument (for example, the program name). May be NULL.
[in,out]	cmdlinePtr	Command line argument string to split. This string will be modified in-place.
[in,out]	argc	As input, the size of the argv array. As output, the number of arguments obtained.
[out]	argv	The tokenized arguments. These will be pointers into the firstStr and modified cmdlinePtr buffers.

/ Build Apps

le_args.h File Reference

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ le_arg_ErrorHandlerFunc_t

◆ le_arg_FlagCallbackFunc_t

◆ le_arg_IntCallbackFunc_t

◆ le_arg_StringCallbackFunc_t

Function Documentation

◆ le_arg_AddPositionalCallback()

◆ le_arg_AllowLessPositionalArgsThanCallbacks()

◆ le_arg_AllowMorePositionalArgsThanCallbacks()

◆ le_arg_GetArg()

◆ le_arg_GetFlagOption()

◆ le_arg_GetIntOption()

◆ le_arg_GetProgramName()

◆ le_arg_GetScanResult()

◆ le_arg_GetStringOption()

◆ le_arg_NumArgs()

◆ le_arg_Scan()

◆ le_arg_SetArgs()

◆ le_arg_SetErrorHandler()

◆ le_arg_SetExitOnError()

◆ le_arg_SetFlagCallback()

◆ le_arg_SetFlagVar()

◆ le_arg_SetIntCallback()

◆ le_arg_SetIntVar()

◆ le_arg_SetStringCallback()

◆ le_arg_SetStringVar()

◆ le_arg_Split()