Command Line Arguments API

API Reference

When a program starts, arguments may be passed from the command line.

$ foo bar baz

In a traditional C/C++ program, these arguments are received as parameters to main(). The Legato framework makes these available to component via function calls instead.

Argument Access By Index

The arguments can be fetched by index using le_arg_GetArg(). The first argument has index 0, the second argument has index 1, etc. In the above example, bar has index 0 and baz has index 1.

The number of available arguments is obtained using le_arg_NumArgs().

The name of the program is obtained using le_arg_GetProgramName().

The program name and all arguments are assumed to be Null-terminated UTF-8 strings. For more information about UTF-8 strings see UTF-8 String Handling API.

Options

Options are arguments that start with a "-" or "--".

To search for a specific option, the following functions are provided:

Note
A "-" or "--" by itself is not considered an option. These are treated as positional arguments.

Positional Arguments

Positional arguments are arguments that do not start with a "-" or "--"; except for "-" or "--" by itself (these are positional arguments).

For example, the following command line has four positional arguments ("foo", "bar", "-", and "--"). A flag option ("-x"), and two string options ("-f ./infile" and "--output=/tmp/output file") are intermixed with the positional arguments.

$ myExe -x foo -f ./infile - "--output=/tmp/output file" bar --

In this example, "foo" is the first positional argument, "-" is the second, "bar" is the third, and "--" is the fourth.

Positional arguments are retrieved using the Argument Scanner and le_arg_AddPositionalCallback().

Argument Scanner

If you're building a command-line application with a complex argument list, you may want to use the Legato framework's argument scanner feature. It supports many options commonly seen in command-line tools and performs a lot of the error checking and reporting for you.

For example, the commandLine sample application implements a tool called fileInfo that prints information about files or directories. It is flexible about the order of appearance of options on the command-line. For example, the following are equivalent:

# fileInfo -x -mc 20 permissions *

# fileInfo permissions --max-count=20 * -x

Note that

  • "-mc 20" and "--max-count=20" are different ways of specifying the same option;
  • the order of appearance of the options can change;
  • options (which start with '-' or '--') and other arguments can be intermixed.

Usage

A program (typically inside a COMPONENT_INIT) can call functions to register variables to be set or call-back functions to be called when certain arguments are passed to the program.

After registering the variables and call-back functions, le_arg_Scan() is called to parse the argument list.

The following functions can be called before le_arg_Scan() is called to register variables to be set or call-back functions to be called by le_arg_Scan():

There are essentially 3 forms of function:

  • le_arg_SetXxxVar() - Registers a variable to be set by le_arg_Scan() when it sees a certain argument starting with '-' or '--'.
  • le_arg_SetXxxCallback() - Registers a call-back function to be called by le_arg_Scan() when it sees a certain argument starting with '-' or '--'.
  • le_arg_AddPositionalCallback() - Registers a call-back function to be called by le_arg_Scan() when it sees an argument that does not start with either '-' or '--'.

le_arg_AddPositionalCallback() can be called multiple times. This constructs a list of call-back functions, where the first function in that list will be called for the first positional argument, the second function in the list will be called for the second positional argument, etc.

Normally, an error will be generated if there are not the same number of positional arguments as there are positional callbacks in the list. However, this behaviour can be changed:

le_utf8_ParseInt() can be used by a positional callback to convert the string value it receives into an integer value, if needed.

Example

// Set IsExtreme to true if the -x or --extreme appears on the command-line.
le_arg_SetFlagVar(&IsExtreme, "x", "extreme");
 
// Set Count to the value N given by "-mc N" or "--max-count=N".
le_arg_SetIntVar(&MaxCount, "mc", "max-count");
 
// Register a function to be called if -h or --help appears on the command-line.
le_arg_SetFlagCallback(PrintHelp, "h", "help");
 
// The first argument that doesn't start with '-' or '--' should be a command.
le_arg_AddPositionalCallback(SetCommand);
 
// All other arguments that don't start with '-' or '--' should be file paths.
le_arg_AddPositionalCallback(SetFilePath);
le_arg_AllowMorePositionalArgsThanCallbacks();
 
// Perform command-line argument processing.
le_arg_Scan();

Error Handling

If a program wishes to try to recover from errors on the command-line or to generate its own special form of error message, it can use le_arg_SetErrorHandler() to register a callback function to be called to handle errors.

If no error handler is set, the default handler will print an error message to the standard error stream and terminate the process with an exit code of EXIT_FAILURE.

Error conditions that can be reported to the error handler are described in the documentation for le_arg_ErrorHandlerFunc_t.

// Set Count to the value N given by "-mc N" or "--max-count=N".
le_arg_SetIntVar(&MaxCount, "mc", "max-count");
 
// Register my own error handler.
le_arg_SetErrorHandler(HandleArgError);
 
// Perform command-line argument processing.
le_arg_Scan();

Writing Your Own main()?

If you are not using a main() function that is auto-generated by the Legato application framework's build tools (mksys, mkapp, or mkexe ), then you must call le_arg_SetArgs() to pass argc and argv to the argument parsing system before using any other le_arg functions.

Copyright (C) Sierra Wireless Inc.