NAME
parseopt - parse command-line options
SYNOPSIS
#include <limb/parseopt.h>
int parseopt(int argc, const char **argv, const struct option *options,
unsigned int flags, struct parseopt *ctx)
const char *PO_ARG(struct parseopt *ctx)
u16 PO_CUR(struct parseopt *ctx)
int PO_IDX(struct parseopt *ctx)
DESCRIPTION
The parseopt() function parses command-line arguments. Its arguments argc
and argv are the argument count and array as passed to the main() function
on program invocation.
The options argument is a pointer to the first element of an array defining
all possible options. See Options below for more.
The flags argument allows to enable certain options, see FLAGS below.
The last argument ctx is pointer to an opaque structure, that should be
initialized to PARSEOPT_ZERO.
When parseopt() returns a positive value, i.e. an option was successfully
found, the PO_ARG() macro will return a pointer to the option's argument if
any (NULL otherwise). It is similar to the global optarg from getopt(3).
Additionally, the PO_IDX() macro will return the index of said option within
the options array. When an error occurs, it can either be -1 or, in the case
of abbreviated long options (and more than one option did match), the
first-matching option.
When parseopt() returns 0, the PO_CUR() macro will return the index in
argv of the first non-option element. In that way, it is similar to the global
optind from getopt(3).
Parsing
Parsing starts at element 1, as expected from a typical argv.
An element of argv starting with '-' is treated as an option element. If
followed by a second dash, then a long option name is expected to follow, else a
short option character.
An element of "--" has special meaning, indicating the end of options and
stopping parsing, i.e. parseopt() will return 0 when encountered.
When an option has been identified, parseopt() will return its id if it is
non-zero, else its shortopt (see Options below).
Parsing stops when the first non-option element is encountered, or an element "--" is met.
Options
Long options do not require to be specified in full, and an abbreviation will be recognized as long as there's no other match possible. (This behavior can be disabled, see FLAGS below.)
When an argument is required, it can be specified within the same element, following a '=' for long options, or as the next element. Optional arguments can only be specified within the same element.
An element for short options can specify more than one option in a row, so long as they don't accept argument. When an option accepts an argument (whether optional or not), what follows next within the element will be treated as the option's argument. (Note that it remains possible to specify a required argument as next element.)
options must be a pointer to the first element of an array of struct option,
which contains the following members :
const char shortopt;
const char *longopt;
u16 arg : 2;
u16 flags : 10;
int id;
The meanings of different members are :
shortopt
The character of the short option. Obviously this should be a character that can be found on the command line. Valid values are comprised between 33 (0x21) and 126 (0x7E), which includes all alphanumeric ASCII characters.
longopt
The name of the long option.
arg
One of the constants ARG_NONE, ARG_REQ or ARG_OPT to indicate whether the option takes no argument, requires an argument, or accepts an optional argument, respectively.
flags
Not used, leave at 0. (See loadopt(3) for possible use.)
id
An integer value unique to this option, to recognize when it is parsed. It
must be a value >= 128 (OPTID_FIRST), or 0 (OPTID_SHORTOPT) in which
case shortopt will be returned instead.
Other values (between 1 and 32) are reserved for internal use.
To define options you can use the following convenience macros :
OPTION_ARG_NONE(shortopt, longopt, flags, id)
To define an option taking no arguments
OPTION_ARG_OPT(shortopt, longopt, flags, id)
To define an option accepting an optional argument
OPTION_ARG_REQ(shortopt, longopt, flags, id)
To define an option requiring an argument
The last element of the array must be set to OPTION_DONE (all members set to 0
except flags set to 1) to indicate the end.
FLAGS
It is possible to define some options via the flags argument, whose value is
constructed as a bitwise-inclusive OR of flags from the following list :
PARSEOPT_STRICT
Long options can not be abbreviated, and must be exact match.
PARSEOPT_SILENT
Do not emit any warnings in case of errors.
RETURN VALUE
If an option was successfully found, parseopt() returns the option's id
unless it is OPTID_SHORTOPT, in which case its shortopt is returned instead.
When all command-line options have been parsed it returns 0.
If an error occurs, it returns -1 and sets errno to indicate the error.
In case of error, parseopt() will also write a warning explaining the error
on stderr (done through the warn(3) family of functions), unless
PARSEOPT_SILENT was specified in its flags argument.
ERRORS
The parseopt() function may fail if :
EINVAL
Option name was missing, i.e. the element was "-" only
ENOENT
Unknown option
ENOMSG
An option requiring an argument was found, but no argument was specified.