In addition to key values corresponding to user options, the key
argument to argp parser functions may have a number of other special
values. In the following example arg and state refer to
parser function arguments. See Argp Parser Functions.
This is not an option at all, but rather a command line argument, whose
value is pointed to by arg.
When there are multiple parser functions in play due to argp parsers
being combined, it's impossible to know which one will handle a specific
argument. Each is called until one returns 0 or an error other than
ARGP_ERR_UNKNOWN; if an argument is not handled,
argp_parse immediately returns success, without parsing any more
Once a parser function returns success for this key, that fact is
recorded, and the ARGP_KEY_NO_ARGS case won't be
used. However, if while processing the argument a parser function
decrements the next field of its state argument, the option
won't be considered processed; this is to allow you to actually modify
the argument, perhaps into an option, and have it processed again.
If a parser function returns ARGP_ERR_UNKNOWN for
ARGP_KEY_ARG, it is immediately called again with the key
ARGP_KEY_ARGS, which has a similar meaning, but is slightly more
convenient for consuming all remaining arguments. arg is 0, and
the tail of the argument vector may be found at state->argv
+ state->next. If success is returned for this key, and
state->next is unchanged, all remaining arguments are
considered to have been consumed. Otherwise, the amount by which
state->next has been adjusted indicates how many were used.
Here's an example that uses both, for different args:
if (state->arg_num == 0)
/* First argument */
first_arg = arg;
/* Let the next case parse it. */
remaining_args = state->argv + state->next;
num_remaining_args = state->argc - state->next;
This indicates that there are no more command line arguments. Parser
functions are called in a different order, children first. This allows
each parser to clean up its state for the parent.
Because it's common to do some special processing if there aren't any
non-option args, parser functions are called with this key if they
didn't successfully process any non-option arguments. This is called
just before ARGP_KEY_END, where more general validity checks on
previously parsed arguments take place.
This is passed in before any parsing is done. Afterwards, the values of
each element of the child_input field of state, if any, are
copied to each child's state to be the initial value of the input
when their parsers are called.
Passed in when parsing has successfully been completed, even if
Passed in if an error has occurred and parsing is terminated. In this
case a call with a key of ARGP_KEY_SUCCESS is never made.
The final key ever seen by any parser, even after
ARGP_KEY_SUCCESS and ARGP_KEY_ERROR. Any resources
allocated by ARGP_KEY_INIT may be freed here. At times, certain
resources allocated are to be returned to the caller after a successful
parse. In that case, those particular resources can be freed in the
In all cases, ARGP_KEY_INIT is the first key seen by parser
functions, and ARGP_KEY_FINI the last, unless an error was
returned by the parser for ARGP_KEY_INIT. Other keys can occur
in one the following orders. opt refers to an arbitrary option
All non-option arguments were successfully handled by a parser
function. There may be multiple parser functions if multiple argp
parsers were combined.
( opt | ARGP_KEY_ARG )... ARGP_KEY_SUCCESS
Some non-option argument went unrecognized.
This occurs when every parser function returns ARGP_KEY_UNKNOWN
for an argument, in which case parsing stops at that argument if
arg_index is a null pointer. Otherwise an error occurs.
In all cases, if a non-null value for arg_index gets passed to
argp_parse, the index of the first unparsed command-line argument
is passed back in that value.
If an error occurs and is either detected by argp or because a parser
function returned an error value, each parser is called with
ARGP_KEY_ERROR. No further calls are made, except the final call
Published under the terms of the GNU General Public License