GNU Info

(libc.info)Argp Parser Functions

---

Next: Argp Children Prev: Argp Option Vectors Up: Argp Parsers

---

Enter node , (file) or (file)node

Argp Parser Functions
---------------------

   The function pointed to by the `parser' field in a `struct argp'
(Note: Argp Parsers) defines what actions take place in response to
each option or argument parsed.  It is also used as a hook, allowing a
parser to perform tasks at certain other points during parsing.

   Argp parser functions have the following type signature:

     error_t PARSER (int KEY, char *ARG, struct argp_state *STATE)

where the arguments are as follows:

KEY
     For each option that is parsed, PARSER is called with a value of
     KEY from that option's `key' field in the option vector.  Note:
     Argp Option Vectors.  PARSER is also called at other times with
     special reserved keys, such as `ARGP_KEY_ARG' for non-option
     arguments.  Note: Argp Special Keys.

ARG
     If KEY is an option, ARG is its given value.  This defaults to
     zero if no value is specified.  Only options that have a non-zero
     `arg' field can ever have a value.  These must _always_ have a
     value unless the `OPTION_ARG_OPTIONAL' flag is specified.  If the
     input being parsed specifies a value for an option that doesn't
     allow one, an error results before PARSER ever gets called.

     If KEY is `ARGP_KEY_ARG', ARG is a non-option argument.  Other
     special keys always have a zero ARG.

STATE
     STATE points to a `struct argp_state', containing useful
     information about the current parsing state for use by PARSER.
     Note: Argp Parsing State.

   When PARSER is called, it should perform whatever action is
appropriate for KEY, and return `0' for success, `ARGP_ERR_UNKNOWN' if
the value of KEY is not handled by this parser function, or a unix
error code if a real error occurred.  Note: Error Codes.

 - Macro: int ARGP_ERR_UNKNOWN
     Argp parser functions should return `ARGP_ERR_UNKNOWN' for any KEY
     value they do not recognize, or for non-option arguments (`KEY ==
     ARGP_KEY_ARG') that they are not equipped to handle.

   A typical parser function uses a switch statement on KEY:

     error_t
     parse_opt (int key, char *arg, struct argp_state *state)
     {
       switch (key)
         {
         case OPTION_KEY:
           ACTION
           break;
         ...
         default:
           return ARGP_ERR_UNKNOWN;
         }
       return 0;
     }

Keys

Argp Special Keys. Special values for the KEY argument.

State

Argp Parsing State. What the STATE argument refers to.

Functions

Argp Helper Functions. Functions to help during argp parsing.