le_args.h File Reference

Go to the source code of this file.

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_Scan (void)
void	le_arg_SetArgs (const size_t argc, char **argv)

Detailed Description

Legato Command Line Arguments API include file.

Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.

Typedef Documentation

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.

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.

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.

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

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.

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.

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.

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_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_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).

const char* le_arg_GetProgramName

(

void

)

Gets the program name.

Returns

Pointer to the null-terminated program name string.

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

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.

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.

void le_arg_SetArgs	(	const size_t	argc,
		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().

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.

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").

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").

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").

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").

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").

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").