In addition to key values corresponding to user options, the key argument to argp parser functions may have a number of other special values (arg and state refer to parser function arguments; see section Argp Parser Functions):
ARGP_KEY_ARG
ARGP_ERR_UNKNOWN; if an argument is handled by no one,
argp_parse immediately returns success, without parsing any more
arguments.
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.
ARGP_KEY_ARGS
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, then all remaining arguments are
considered to have been consumed, otherwise, the amount by which
state->next has been adjust indicates how many were used.
For instance, here's an example that uses both, for different args:
...
case ARGP_KEY_ARG:
if (state->arg_num == 0)
/* First argument */
first_arg = arg;
else
/* Let the next case parse it. */
return ARGP_KEY_UNKNOWN;
break;
case ARGP_KEY_ARGS:
remaining_args = state->argv + state->next;
num_remaining_args = state->argc - state->next;
break;
ARGP_KEY_END
ARGP_KEY_NO_ARGS
ARGP_KEY_END (where more general validity checks on
previously parsed arguments can take place).
ARGP_KEY_INIT
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.
ARGP_KEY_SUCCESS
ARGP_KEY_ERROR
ARGP_KEY_SUCCESS is never made).
ARGP_KEY_FINI
ARGP_KEY_SUCCESS and ARGP_KEY_ERROR). Any resources
allocated by ARGP_KEY_INIT may be freed here (although sometimes
certain resources allocated there are to be returned to the caller after
a successful parse; in that case, those particular resources can be
freed in the ARGP_KEY_ERROR case).
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
key):
ARGP_KEY_NO_ARGS ARGP_KEY_END ARGP_KEY_SUCCESS
ARGP_KEY_ARG )... ARGP_KEY_END ARGP_KEY_SUCCESS
ARGP_KEY_ARG )... ARGP_KEY_SUCCESS
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 was passed to
argp_parse, the index of the first unparsed command-line argument
is passed back in it.
If an error occurs (either detected by argp, or because a parser
function returned an error value), then each parser is called with
ARGP_KEY_ERROR, and no further calls are made except the final
call with ARGP_KEY_FINI.
Go to the first, previous, next, last section, table of contents.