Special Keys for Argp Parser Functions

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

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 (due to argp parsers being combined), it's impossible to know which one wants to handle an argument, so each is called in turn, until one returns 0 or an error other than 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

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, 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

There are no more command line arguments at all. The parser functions are called in different order (means children first) for this value which allows each parser to clean up its state for the parent.

ARGP_KEY_NO_ARGS

Because it's common to want 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. Called just before ARGP_KEY_END (where more general validity checks on previously parsed arguments can take place).

ARGP_KEY_INIT

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.

ARGP_KEY_SUCCESS

Passed in when parsing has successfully been completed (even if there are still arguments remaining).

ARGP_KEY_ERROR

Passed in if an error has occurred, and parsing terminated (in which case a call with a key of ARGP_KEY_SUCCESS is never made).

ARGP_KEY_FINI

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 (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):

opt... ARGP_KEY_NO_ARGS ARGP_KEY_END ARGP_KEY_SUCCESS

The arguments being parsed contained no non-option arguments at all.

( opt | ARGP_KEY_ARG )... ARGP_KEY_END ARGP_KEY_SUCCESS

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 was 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 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.