GNU Info

(libc.info)Argp Special Keys

---

Next: Argp Parsing State Up: Argp Parser Functions

---

Enter node , (file) or (file)node

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.  In the following example ARG and STATE refer to parser
function arguments.  Note: 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 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 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, 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:

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

`ARGP_KEY_NO_ARGS'
     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.

`ARGP_KEY_INIT'
     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.

`ARGP_KEY_SUCCESS'
     Passed in when parsing has successfully been completed, even if
     arguments remain.

`ARGP_KEY_ERROR'
     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.

`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.  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 `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 did not contain any non-option
     arguments.

( 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 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
with `ARGP_KEY_FINI'.