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.