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