1: @node Argp, Suboptions, Getopt, Parsing Program Arguments
    2: @need 5000
    3: @section Parsing Program Options with Argp
    4: @cindex argp (program argument parser)
    5: @cindex argument parsing with argp
    6: @cindex option parsing with argp
    7: 
    8: @dfn{Argp} is an interface for parsing unix-style argument vectors.
    9: @xref{Program Arguments}.
   10: 
   11: Argp provides features unavailable in the more commonly used
   12: @code{getopt} interface.  These features include automatically producing
   13: output in response to the @samp{--help} and @samp{--version} options, as
   14: described in the GNU coding standards.  Using argp makes it less likely
   15: that programmers will neglect to implement these additional options or
   16: keep them up to date.
   17: 
   18: Argp also provides the ability to merge several independently defined
   19: option parsers into one, mediating conflicts between them and making the
   20: result appear seamless.  A library can export an argp option parser that
   21: user programs might employ in conjunction with their own option parsers,
   22: resulting in less work for the user programs.  Some programs may use only
   23: argument parsers exported by libraries, thereby achieving consistent and
   24: efficient option-parsing for abstractions implemented by the libraries.
   25: 
   26: @pindex argp.h
   27: The header file @file{<argp.h>} should be included to use argp.
   28: 
   29: @subsection The @code{argp_parse} Function
   30: 
   31: The main interface to argp is the @code{argp_parse} function.  In many
   32: cases, calling @code{argp_parse} is the only argument-parsing code
   33: needed in @code{main}.
   34: @xref{Program Arguments}.
   35: 
   36: @comment argp.h
   37: @comment GNU
   38: @deftypefun {error_t} argp_parse (const struct argp *@var{argp}, int @var{argc}, char **@var{argv}, unsigned @var{flags}, int *@var{arg_index}, void *@var{input})
   39: The @code{argp_parse} function parses the arguments in @var{argv}, of
   40: length @var{argc}, using the argp parser @var{argp}.  @xref{Argp
   41: Parsers}.
   42: 
   43: A value of zero is the same as a @code{struct argp}containing all
   44: zeros.  @var{flags} is a set of flag bits that modify the parsing
   45: behavior.  @xref{Argp Flags}.  @var{input} is passed through to the argp
   46: parser @var{argp}, and has meaning defined by @var{argp}.  A typical
   47: usage is to pass a pointer to a structure which is used for specifying
   48: parameters to the parser and passing back the results.
   49: 
   50: Unless the @code{ARGP_NO_EXIT} or @code{ARGP_NO_HELP} flags are included
   51: in @var{flags}, calling @code{argp_parse} may result in the program
   52: exiting.  This behavior is true if an error is detected, or when an
   53: unknown option is encountered.  @xref{Program Termination}.
   54: 
   55: If @var{arg_index} is non-null, the index of the first unparsed option
   56: in @var{argv} is returned as a value.
   57: 
   58: The return value is zero for successful parsing, or an error code
   59: (@pxref{Error Codes}) if an error is detected.  Different argp parsers
   60: may return arbitrary error codes, but the standard error codes are:
   61: @code{ENOMEM} if a memory allocation error occurred, or @code{EINVAL} if
   62: an unknown option or option argument is encountered.
   63: @end deftypefun
   64: 
   65: @menu
   66: * Globals: Argp Global Variables.  Global argp parameters.
   67: * Parsers: Argp Parsers.        Defining parsers for use with @code{argp_parse}.
   68: * Flags: Argp Flags.            Flags that modify the behavior of @code{argp_parse}.
   69: * Help: Argp Help.              Printing help messages when not parsing.
   70: * Examples: Argp Examples.      Simple examples of programs using argp.
   71: * Customization: Argp User Customization.
   72:                                 Users may control the @samp{--help} output format.
   73: @end menu
   74: 
   75: @node Argp Global Variables, Argp Parsers, , Argp
   76: @subsection Argp Global Variables
   77: 
   78: These variables make it easy for user programs to implement the
   79: @samp{--version} option and provide a bug-reporting address in the
   80: @samp{--help} output.  These are implemented in argp by default.
   81: 
   82: @comment argp.h
   83: @comment GNU
   84: @deftypevar {const char *} argp_program_version
   85: If defined or set by the user program to a non-zero value, then a
   86: @samp{--version} option is added when parsing with @code{argp_parse},
   87: which will print the @samp{--version} string followed by a newline and
   88: exit.  The exception to this is if the @code{ARGP_NO_EXIT} flag is used.
   89: @end deftypevar
   90: 
   91: @comment argp.h
   92: @comment GNU
   93: @deftypevar {const char *} argp_program_bug_address
   94: If defined or set by the user program to a non-zero value,
   95: @code{argp_program_bug_address} should point to a string that will be
   96: printed at the end of the standard output for the @samp{--help} option,
   97: embedded in a sentence that says @samp{Report bugs to @var{address}.}.
   98: @end deftypevar
   99: 
  100: @need 1500
  101: @comment argp.h
  102: @comment GNU
  103: @defvar argp_program_version_hook
  104: If defined or set by the user program to a non-zero value, a
  105: @samp{--version} option is added when parsing with @code{arg_parse},
  106: which prints the program version and exits with a status of zero.  This
  107: is not the case if the @code{ARGP_NO_HELP} flag is used.  If the
  108: @code{ARGP_NO_EXIT} flag is set, the exit behavior of the program is
  109: suppressed or modified, as when the argp parser is going to be used by
  110: other programs.
  111: 
  112: It should point to a function with this type of signature:
  113: 
  114: @smallexample
  115: void @var{print-version} (FILE *@var{stream}, struct argp_state *@var{state})
  116: @end smallexample
  117: 
  118: @noindent
  119: @xref{Argp Parsing State}, for an explanation of @var{state}.
  120: 
  121: This variable takes precedence over @code{argp_program_version}, and is
  122: useful if a program has version information not easily expressed in a
  123: simple string.
  124: @end defvar
  125: 
  126: @comment argp.h
  127: @comment GNU
  128: @deftypevar error_t argp_err_exit_status
  129: This is the exit status used when argp exits due to a parsing error.  If
  130: not defined or set by the user program, this defaults to:
  131: @code{EX_USAGE} from @file{<sysexits.h>}.
  132: @end deftypevar
  133: 
  134: @node Argp Parsers, Argp Flags, Argp Global Variables, Argp
  135: @subsection Specifying Argp Parsers
  136: 
  137: The first argument to the @code{argp_parse} function is a pointer to a
  138: @code{struct argp}, which is known as an @dfn{argp parser}:
  139: 
  140: @comment argp.h
  141: @comment GNU
  142: @deftp {Data Type} {struct argp}
  143: This structure specifies how to parse a given set of options and
  144: arguments, perhaps in conjunction with other argp parsers.  It has the
  145: following fields:
  146: 
  147: @table @code
  148: @item const struct argp_option *options
  149: A pointer to a vector of @code{argp_option} structures specifying which
  150: options this argp parser understands; it may be zero if there are no
  151: options at all.  @xref{Argp Option Vectors}.
  152: 
  153: @item argp_parser_t parser
  154: A pointer to a function that defines actions for this parser; it is
  155: called for each option parsed, and at other well-defined points in the
  156: parsing process.  A value of zero is the same as a pointer to a function
  157: that always returns @code{ARGP_ERR_UNKNOWN}.  @xref{Argp Parser
  158: Functions}.
  159: 
  160: @item const char *args_doc
  161: If non-zero, a string describing what non-option arguments are called by
  162: this parser.  This is only used to print the @samp{Usage:} message.  If
  163: it contains newlines, the strings separated by them are considered
  164: alternative usage patterns and printed on separate lines.  Lines after
  165: the first are prefixed by @samp{ or: } instead of @samp{Usage:}.
  166: 
  167: @item const char *doc
  168: If non-zero, a string containing extra text to be printed before and
  169: after the options in a long help message, with the two sections
  170: separated by a vertical tab (@code{'\v'}, @code{'\013'}) character.  By
  171: convention, the documentation before the options is just a short string
  172: explaining what the program does.  Documentation printed after the
  173: options describe behavior in more detail.
  174: 
  175: @item const struct argp_child *children
  176: A pointer to a vector of @code{argp_children} structures.  This pointer
  177: specifies which additional argp parsers should be combined with this
  178: one.  @xref{Argp Children}.
  179: 
  180: @item char *(*help_filter)(int @var{key}, const char *@var{text}, void *@var{input})
  181: If non-zero, a pointer to a function that filters the output of help
  182: messages.  @xref{Argp Help Filtering}.
  183: 
  184: @item const char *argp_domain
  185: If non-zero, the strings used in the argp library are translated using
  186: the domain described by this string.  If zero, the current default domain
  187: is used.
  188: 
  189: @end table
  190: @end deftp
  191: 
  192: Of the above group, @code{options}, @code{parser}, @code{args_doc}, and
  193: the @code{doc} fields are usually all that are needed.  If an argp
  194: parser is defined as an initialized C variable, only the fields used
  195: need be specified in the initializer.  The rest will default to zero due
  196: to the way C structure initialization works.  This design is exploited in
  197: most argp structures; the most-used fields are grouped near the
  198: beginning, the unused fields left unspecified.
  199: 
  200: @menu
  201: * Options: Argp Option Vectors.   Specifying options in an argp parser.
  202: * Argp Parser Functions::         Defining actions for an argp parser.
  203: * Children: Argp Children.        Combining multiple argp parsers.
  204: * Help Filtering: Argp Help Filtering.  Customizing help output for an argp parser.
  205: @end menu
  206: 
  207: @node Argp Option Vectors, Argp Parser Functions, Argp Parsers, Argp Parsers
  208: @subsection Specifying Options in an Argp Parser
  209: 
  210: The @code{options} field in a @code{struct argp} points to a vector of
  211: @code{struct argp_option} structures, each of which specifies an option
  212: that the argp parser supports.  Multiple entries may be used for a single
  213: option provided it has multiple names.  This should be terminated by an
  214: entry with zero in all fields.  Note that when using an initialized C
  215: array for options, writing @code{@{ 0 @}} is enough to achieve this.
  216: 
  217: @comment argp.h
  218: @comment GNU
  219: @deftp {Data Type} {struct argp_option}
  220: This structure specifies a single option that an argp parser
  221: understands, as well as how to parse and document that option.  It has
  222: the following fields:
  223: 
  224: @table @code
  225: @item const char *name
  226: The long name for this option, corresponding to the long option
  227: @samp{--@var{name}}; this field may be zero if this option @emph{only}
  228: has a short name.  To specify multiple names for an option, additional
  229: entries may follow this one, with the @code{OPTION_ALIAS} flag
  230: set.  @xref{Argp Option Flags}.
  231: 
  232: @item int key
  233: The integer key provided by the current option to the option parser.  If
  234: @var{key} has a value that is a printable @sc{ascii} character (i.e.,
  235: @code{isascii (@var{key})} is true), it @emph{also} specifies a short
  236: option @samp{-@var{char}}, where @var{char} is the @sc{ascii} character
  237: with the code @var{key}.
  238: 
  239: @item const char *arg
  240: If non-zero, this is the name of an argument associated with this
  241: option, which must be provided (e.g., with the
  242: @samp{--@var{name}=@var{value}} or @samp{-@var{char} @var{value}}
  243: syntaxes), unless the @code{OPTION_ARG_OPTIONAL} flag (@pxref{Argp
  244: Option Flags}) is set, in which case it @emph{may} be provided.
  245: 
  246: @item int flags
  247: Flags associated with this option, some of which are referred to above.
  248: @xref{Argp Option Flags}.
  249: 
  250: @item const char *doc
  251: A documentation string for this option, for printing in help messages.
  252: 
  253: If both the @code{name} and @code{key} fields are zero, this string
  254: will be printed tabbed left from the normal option column, making it
  255: useful as a group header.  This will be the first thing printed in its
  256: group.  In this usage, it's conventional to end the string with a
  257: @samp{:} character.
  258: 
  259: @item int group
  260: Group identity for this option.
  261: 
  262: In a long help message, options are sorted alphabetically within each
  263: group, and the groups presented in the order 0, 1, 2, @dots{}, @var{n},
  264: @minus{}@var{m}, @dots{}, @minus{}2, @minus{}1.
  265: 
  266: Every entry in an options array with this field 0 will inherit the group
  267: number of the previous entry, or zero if it's the first one.  If it's a
  268: group header with @code{name} and @code{key} fields both zero, the
  269: previous entry + 1 is the default.  Automagic options such as
  270: @samp{--help} are put into group @minus{}1.
  271: 
  272: Note that because of C structure initialization rules, this field often
  273: need not be specified, because 0 is the correct value.
  274: @end table
  275: @end deftp
  276: 
  277: 
  278: @menu
  279: * Flags: Argp Option Flags.     Flags for options.
  280: @end menu
  281: 
  282: @node Argp Option Flags, , , Argp Option Vectors
  283: @subsubsection Flags for Argp Options
  284: 
  285: The following flags may be or'd together in the @code{flags} field of a
  286: @code{struct argp_option}.  These flags control various aspects of how
  287: that option is parsed or displayed in help messages:
  288: 
  289: 
  290: @vtable @code
  291: @comment argp.h
  292: @comment GNU
  293: @item OPTION_ARG_OPTIONAL
  294: The argument associated with this option is optional.
  295: 
  296: @comment argp.h
  297: @comment GNU
  298: @item OPTION_HIDDEN
  299: This option isn't displayed in any help messages.
  300: 
  301: @comment argp.h
  302: @comment GNU
  303: @item OPTION_ALIAS
  304: This option is an alias for the closest previous non-alias option.  This
  305: means that it will be displayed in the same help entry, and will inherit
  306: fields other than @code{name} and @code{key} from the option being
  307: aliased.
  308: 
  309: 
  310: @comment argp.h
  311: @comment GNU
  312: @item OPTION_DOC
  313: This option isn't actually an option and should be ignored by the actual
  314: option parser.  It is an arbitrary section of documentation that should
  315: be displayed in much the same manner as the options.  This is known as a
  316: @dfn{documentation option}.
  317: 
  318: If this flag is set, then the option @code{name} field is displayed
  319: unmodified (e.g., no @samp{--} prefix is added) at the left-margin where
  320: a @emph{short} option would normally be displayed, and this
  321: documentation string is left in it's usual place.  For purposes of
  322: sorting, any leading whitespace and punctuation is ignored, unless the
  323: first non-whitespace character is @samp{-}.  This entry is displayed
  324: after all options, after @code{OPTION_DOC} entries with a leading
  325: @samp{-}, in the same group.
  326: 
  327: @comment argp.h
  328: @comment GNU
  329: @item OPTION_NO_USAGE
  330: This option shouldn't be included in `long' usage messages, but should
  331: still be included in other help messages.  This is intended for options
  332: that are completely documented in an argp's @code{args_doc}
  333: field.  @xref{Argp Parsers}.  Including this option in the generic usage
  334: list would be redundant, and should be avoided.
  335: 
  336: For instance, if @code{args_doc} is @code{"FOO BAR\n-x BLAH"}, and the
  337: @samp{-x} option's purpose is to distinguish these two cases, @samp{-x}
  338: should probably be marked @code{OPTION_NO_USAGE}.
  339: @end vtable
  340: 
  341: @node Argp Parser Functions, Argp Children, Argp Option Vectors, Argp Parsers
  342: @subsection Argp Parser Functions
  343: 
  344: The function pointed to by the @code{parser} field in a @code{struct
  345: argp} (@pxref{Argp Parsers}) defines what actions take place in response
  346: to each option or argument parsed.  It is also used as a hook, allowing a
  347: parser to perform tasks at certain other points during parsing.
  348: 
  349: @need 2000
  350: Argp parser functions have the following type signature:
  351: 
  352: @cindex argp parser functions
  353: @smallexample
  354: error_t @var{parser} (int @var{key}, char *@var{arg}, struct argp_state *@var{state})
  355: @end smallexample
  356: 
  357: @noindent
  358: where the arguments are as follows:
  359: 
  360: @table @var
  361: @item key
  362: For each option that is parsed, @var{parser} is called with a value of
  363: @var{key} from that option's @code{key} field in the option
  364: vector.  @xref{Argp Option Vectors}.  @var{parser} is also called at
  365: other times with special reserved keys, such as @code{ARGP_KEY_ARG} for
  366: non-option arguments.  @xref{Argp Special Keys}.
  367: 
  368: @item arg
  369: If @var{key} is an option, @var{arg} is its given value.  This defaults
  370: to zero if no value is specified.  Only options that have a non-zero
  371: @code{arg} field can ever have a value.  These must @emph{always} have a
  372: value unless the @code{OPTION_ARG_OPTIONAL} flag is specified.  If the
  373: input being parsed specifies a value for an option that doesn't allow
  374: one, an error results before @var{parser} ever gets called.
  375: 
  376: If @var{key} is @code{ARGP_KEY_ARG}, @var{arg} is a non-option
  377: argument.  Other special keys always have a zero @var{arg}.
  378: 
  379: @item state
  380: @var{state} points to a @code{struct argp_state}, containing useful
  381: information about the current parsing state for use by
  382: @var{parser}.  @xref{Argp Parsing State}.
  383: @end table
  384: 
  385: When @var{parser} is called, it should perform whatever action is
  386: appropriate for @var{key}, and return @code{0} for success,
  387: @code{ARGP_ERR_UNKNOWN} if the value of @var{key} is not handled by this
  388: parser function, or a unix error code if a real error
  389: occurred.  @xref{Error Codes}.
  390: 
  391: @comment argp.h
  392: @comment GNU
  393: @deftypevr Macro int ARGP_ERR_UNKNOWN
  394: Argp parser functions should return @code{ARGP_ERR_UNKNOWN} for any
  395: @var{key} value they do not recognize, or for non-option arguments
  396: (@code{@var{key} == ARGP_KEY_ARG}) that they are not equipped to handle.
  397: @end deftypevr
  398: 
  399: @need 3000
  400: A typical parser function uses a switch statement on @var{key}:
  401: 
  402: @smallexample
  403: error_t
  404: parse_opt (int key, char *arg, struct argp_state *state)
  405: @{
  406:   switch (key)
  407:     @{
  408:     case @var{option_key}:
  409:       @var{action}
  410:       break;
  411:     @dots{}
  412:     default:
  413:       return ARGP_ERR_UNKNOWN;
  414:     @}
  415:   return 0;
  416: @}
  417: @end smallexample
  418: 
  419: @menu
  420: * Keys: Argp Special Keys.           Special values for the @var{key} argument.
  421: * State: Argp Parsing State.         What the @var{state} argument refers to.
  422: * Functions: Argp Helper Functions.  Functions to help during argp parsing.
  423: @end menu
  424: 
  425: @node Argp Special Keys, Argp Parsing State, , Argp Parser Functions
  426: @subsubsection Special Keys for Argp Parser Functions
  427: 
  428: In addition to key values corresponding to user options, the @var{key}
  429: argument to argp parser functions may have a number of other special
  430: values.  In the following example @var{arg} and @var{state} refer to
  431: parser function arguments.  @xref{Argp Parser Functions}.
  432: 
  433: @vtable @code
  434: @comment argp.h
  435: @comment GNU
  436: @item ARGP_KEY_ARG
  437: This is not an option at all, but rather a command line argument, whose
  438: value is pointed to by @var{arg}.
  439: 
  440: When there are multiple parser functions in play due to argp parsers
  441: being combined, it's impossible to know which one will handle a specific
  442: argument.  Each is called until one returns 0 or an error other than
  443: @code{ARGP_ERR_UNKNOWN}; if an argument is not handled,
  444: @code{argp_parse} immediately returns success, without parsing any more
  445: arguments.
  446: 
  447: Once a parser function returns success for this key, that fact is
  448: recorded, and the @code{ARGP_KEY_NO_ARGS} case won't be
  449: used.  @emph{However}, if while processing the argument a parser function
  450: decrements the @code{next} field of its @var{state} argument, the option
  451: won't be considered processed; this is to allow you to actually modify
  452: the argument, perhaps into an option, and have it processed again.
  453: 
  454: @comment argp.h
  455: @comment GNU
  456: @item ARGP_KEY_ARGS
  457: If a parser function returns @code{ARGP_ERR_UNKNOWN} for
  458: @code{ARGP_KEY_ARG}, it is immediately called again with the key
  459: @code{ARGP_KEY_ARGS}, which has a similar meaning, but is slightly more
  460: convenient for consuming all remaining arguments.  @var{arg} is 0, and
  461: the tail of the argument vector may be found at @code{@var{state}->argv
  462: + @var{state}->next}.  If success is returned for this key, and
  463: @code{@var{state}->next} is unchanged, all remaining arguments are
  464: considered to have been consumed.  Otherwise, the amount by which
  465: @code{@var{state}->next} has been adjusted indicates how many were used.
  466: Here's an example that uses both, for different args:
  467: 
  468: 
  469: @smallexample
  470: @dots{}
  471: case ARGP_KEY_ARG:
  472:   if (@var{state}->arg_num == 0)
  473:     /* First argument */
  474:     first_arg = @var{arg};
  475:   else
  476:     /* Let the next case parse it.  */
  477:     return ARGP_KEY_UNKNOWN;
  478:   break;
  479: case ARGP_KEY_ARGS:
  480:   remaining_args = @var{state}->argv + @var{state}->next;
  481:   num_remaining_args = @var{state}->argc - @var{state}->next;
  482:   break;
  483: @end smallexample
  484: 
  485: @comment argp.h
  486: @comment GNU
  487: @item ARGP_KEY_END
  488: This indicates that there are no more command line arguments.  Parser
  489: functions are called in a different order, children first.  This allows
  490: each parser to clean up its state for the parent.
  491: 
  492: @comment argp.h
  493: @comment GNU
  494: @item ARGP_KEY_NO_ARGS
  495: Because it's common to do some special processing if there aren't any
  496: non-option args, parser functions are called with this key if they
  497: didn't successfully process any non-option arguments.  This is called
  498: just before @code{ARGP_KEY_END}, where more general validity checks on
  499: previously parsed arguments take place.
  500: 
  501: @comment argp.h
  502: @comment GNU
  503: @item ARGP_KEY_INIT
  504: This is passed in before any parsing is done.  Afterwards, the values of
  505: each element of the @code{child_input} field of @var{state}, if any, are
  506: copied to each child's state to be the initial value of the @code{input}
  507: when @emph{their} parsers are called.
  508: 
  509: @comment argp.h
  510: @comment GNU
  511: @item ARGP_KEY_SUCCESS
  512: Passed in when parsing has successfully been completed, even if
  513: arguments remain.
  514: 
  515: @comment argp.h
  516: @comment GNU
  517: @item ARGP_KEY_ERROR
  518: Passed in if an error has occurred and parsing is terminated.  In this
  519: case a call with a key of @code{ARGP_KEY_SUCCESS} is never made.
  520: 
  521: @comment argp.h
  522: @comment GNU
  523: @item ARGP_KEY_FINI
  524: The final key ever seen by any parser, even after
  525: @code{ARGP_KEY_SUCCESS} and @code{ARGP_KEY_ERROR}.  Any resources
  526: allocated by @code{ARGP_KEY_INIT} may be freed here.  At times, certain
  527: resources allocated are to be returned to the caller after a successful
  528: parse.  In that case, those particular resources can be freed in the
  529: @code{ARGP_KEY_ERROR} case.
  530: @end vtable
  531: 
  532: In all cases, @code{ARGP_KEY_INIT} is the first key seen by parser
  533: functions, and @code{ARGP_KEY_FINI} the last, unless an error was
  534: returned by the parser for @code{ARGP_KEY_INIT}.  Other keys can occur
  535: in one the following orders.  @var{opt} refers to an arbitrary option
  536: key:
  537: 
  538: @table @asis
  539: @item @var{opt}@dots{} @code{ARGP_KEY_NO_ARGS} @code{ARGP_KEY_END} @code{ARGP_KEY_SUCCESS}
  540: The arguments being parsed did not contain any non-option arguments.
  541: 
  542: @item ( @var{opt} | @code{ARGP_KEY_ARG} )@dots{} @code{ARGP_KEY_END} @code{ARGP_KEY_SUCCESS}
  543: All non-option arguments were successfully handled by a parser
  544: function.  There may be multiple parser functions if multiple argp
  545: parsers were combined.
  546: 
  547: @item ( @var{opt} | @code{ARGP_KEY_ARG} )@dots{} @code{ARGP_KEY_SUCCESS}
  548: Some non-option argument went unrecognized.
  549: 
  550: This occurs when every parser function returns @code{ARGP_KEY_UNKNOWN}
  551: for an argument, in which case parsing stops at that argument if
  552: @var{arg_index} is a null pointer.  Otherwise an error occurs.
  553: @end table
  554: 
  555: In all cases, if a non-null value for @var{arg_index} gets passed to
  556: @code{argp_parse}, the index of the first unparsed command-line argument
  557: is passed back in that value.
  558: 
  559: If an error occurs and is either detected by argp or because a parser
  560: function returned an error value, each parser is called with
  561: @code{ARGP_KEY_ERROR}.  No further calls are made, except the final call
  562: with @code{ARGP_KEY_FINI}.
  563: 
  564: @node Argp Helper Functions, , Argp Parsing State, Argp Parser Functions
  565: @subsubsection Functions For Use in Argp Parsers
  566: 
  567: Argp provides a number of functions available to the user of argp
  568: (@pxref{Argp Parser Functions}), mostly for producing error messages.
  569: These take as their first argument the @var{state} argument to the
  570: parser function.  @xref{Argp Parsing State}.
  571: 
  572: 
  573: @cindex usage messages, in argp
  574: @comment argp.h
  575: @comment GNU
  576: @deftypefun void argp_usage (const struct argp_state *@var{state})
  577: Outputs the standard usage message for the argp parser referred to by
  578: @var{state} to @code{@var{state}->err_stream} and terminate the program
  579: with @code{exit (argp_err_exit_status)}.  @xref{Argp Global Variables}.
  580: @end deftypefun
  581: 
  582: @cindex syntax error messages, in argp
  583: @comment argp.h
  584: @comment GNU
  585: @deftypefun void argp_error (const struct argp_state *@var{state}, const char *@var{fmt}, @dots{})
  586: Prints the printf format string @var{fmt} and following args, preceded
  587: by the program name and @samp{:}, and followed by a @w{@samp{Try @dots{}
  588: --help}} message, and terminates the program with an exit status of
  589: @code{argp_err_exit_status}.  @xref{Argp Global Variables}.
  590: @end deftypefun
  591: 
  592: @cindex error messages, in argp
  593: @comment argp.h
  594: @comment GNU
  595: @deftypefun void argp_failure (const struct argp_state *@var{state}, int @var{status}, int @var{errnum}, const char *@var{fmt}, @dots{})
  596: Similar to the standard gnu error-reporting function @code{error}, this
  597: prints the program name and @samp{:}, the printf format string
  598: @var{fmt}, and the appropriate following args.  If it is non-zero, the
  599: standard unix error text for @var{errnum} is printed.  If @var{status} is
  600: non-zero, it terminates the program with that value as its exit status.
  601: 
  602: The difference between @code{argp_failure} and @code{argp_error} is that
  603: @code{argp_error} is for @emph{parsing errors}, whereas
  604: @code{argp_failure} is for other problems that occur during parsing but
  605: don't reflect a syntactic problem with the input, such as illegal values
  606: for options, bad phase of the moon, etc.
  607: @end deftypefun
  608: 
  609: @comment argp.h
  610: @comment GNU
  611: @deftypefun void argp_state_help (const struct argp_state *@var{state}, FILE *@var{stream}, unsigned @var{flags})
  612: Outputs a help message for the argp parser referred to by @var{state},
  613: to @var{stream}.  The @var{flags} argument determines what sort of help
  614: message is produced.  @xref{Argp Help Flags}.
  615: @end deftypefun
  616: 
  617: Error output is sent to @code{@var{state}->err_stream}, and the program
  618: name printed is @code{@var{state}->name}.
  619: 
  620: The output or program termination behavior of these functions may be
  621: suppressed if the @code{ARGP_NO_EXIT} or @code{ARGP_NO_ERRS} flags are
  622: passed to @code{argp_parse}.  @xref{Argp Flags}.
  623: 
  624: This behavior is useful if an argp parser is exported for use by other
  625: programs (e.g., by a library), and may be used in a context where it is
  626: not desirable to terminate the program in response to parsing errors.  In
  627: argp parsers intended for such general use, and for the case where the
  628: program @emph{doesn't} terminate, calls to any of these functions should
  629: be followed by code that returns the appropriate error code:
  630: 
  631: @smallexample
  632: if (@var{bad argument syntax})
  633:   @{
  634:      argp_usage (@var{state});
  635:      return EINVAL;
  636:   @}
  637: @end smallexample
  638: 
  639: @noindent
  640: If a parser function will @emph{only} be used when @code{ARGP_NO_EXIT}
  641: is not set, the return may be omitted.
  642: 
  643: @node Argp Parsing State, Argp Helper Functions, Argp Special Keys, Argp Parser Functions
  644: @subsubsection Argp Parsing State
  645: 
  646: The third argument to argp parser functions (@pxref{Argp Parser
  647: Functions}) is a pointer to a @code{struct argp_state}, which contains
  648: information about the state of the option parsing.
  649: 
  650: @comment argp.h
  651: @comment GNU
  652: @deftp {Data Type} {struct argp_state}
  653: This structure has the following fields, which may be modified as noted:
  654: 
  655: @table @code
  656: @item const struct argp *const root_argp
  657: The top level argp parser being parsed.  Note that this is often
  658: @emph{not} the same @code{struct argp} passed into @code{argp_parse} by
  659: the invoking program.  @xref{Argp}.  It is an internal argp parser that
  660: contains options implemented by @code{argp_parse} itself, such as
  661: @samp{--help}.
  662: 
  663: @item int argc
  664: @itemx char **argv
  665: The argument vector being parsed.  This may be modified.
  666: 
  667: @item int next
  668: The index in @code{argv} of the next argument to be parsed.  This may be
  669: modified.
  670: 
  671: One way to consume all remaining arguments in the input is to set
  672: @code{@var{state}->next = @var{state}->argc}, perhaps after recording
  673: the value of the @code{next} field to find the consumed arguments.  The
  674: current option can be re-parsed immediately by decrementing this field,
  675: then modifying @code{@var{state}->argv[@var{state}->next]} to reflect
  676: the option that should be reexamined.
  677: 
  678: @item unsigned flags
  679: The flags supplied to @code{argp_parse}.  These may be modified, although
  680: some flags may only take effect when @code{argp_parse} is first
  681: invoked.  @xref{Argp Flags}.
  682: 
  683: @item unsigned arg_num
  684: While calling a parsing function with the @var{key} argument
  685: @code{ARGP_KEY_ARG}, this represents the number of the current arg,
  686: starting at 0.  It is incremented after each @code{ARGP_KEY_ARG} call
  687: returns.  At all other times, this is the number of @code{ARGP_KEY_ARG}
  688: arguments that have been processed.
  689: 
  690: @item int quoted
  691: If non-zero, the index in @code{argv} of the first argument following a
  692: special @samp{--} argument.  This prevents anything that follows from
  693: being interpreted as an option.  It is only set after argument parsing
  694: has proceeded past this point.
  695: 
  696: @item void *input
  697: An arbitrary pointer passed in from the caller of @code{argp_parse}, in
  698: the @var{input} argument.
  699: 
  700: @item void **child_inputs
  701: These are values that will be passed to child parsers.  This vector will
  702: be the same length as the number of children in the current parser.  Each
  703: child parser will be given the value of
  704: @code{@var{state}->child_inputs[@var{i}]} as @emph{its}
  705: @code{@var{state}->input} field, where @var{i} is the index of the child
  706: in the this parser's @code{children} field.  @xref{Argp Children}.
  707: 
  708: @item void *hook
  709: For the parser function's use.  Initialized to 0, but otherwise ignored
  710: by argp.
  711: 
  712: @item char *name
  713: The name used when printing messages.  This is initialized to
  714: @code{argv[0]}, or @code{program_invocation_name} if @code{argv[0]} is
  715: unavailable.
  716: 
  717: @item FILE *err_stream
  718: @itemx FILE *out_stream
  719: The stdio streams used when argp prints.  Error messages are printed to
  720: @code{err_stream}, all other output, such as @samp{--help} output) to
  721: @code{out_stream}.  These are initialized to @code{stderr} and
  722: @code{stdout} respectively.  @xref{Standard Streams}.
  723: 
  724: @item void *pstate
  725: Private, for use by the argp implementation.
  726: @end table
  727: @end deftp
  728: 
  729: @node Argp Children, Argp Help Filtering, Argp Parser Functions, Argp Parsers
  730: @subsection Combining Multiple Argp Parsers
  731: 
  732: The @code{children} field in a @code{struct argp} enables other argp
  733: parsers to be combined with the referencing one for the parsing of a
  734: single set of arguments.  This field should point to a vector of
  735: @code{struct argp_child}, which is terminated by an entry having a value
  736: of zero in the @code{argp} field.
  737: 
  738: Where conflicts between combined parsers arise, as when two specify an
  739: option with the same name, the parser conflicts are resolved in favor of
  740: the parent argp parser(s), or the earlier of the argp parsers in the
  741: list of children.
  742: 
  743: @comment argp.h
  744: @comment GNU
  745: @deftp {Data Type} {struct argp_child}
  746: An entry in the list of subsidiary argp parsers pointed to by the
  747: @code{children} field in a @code{struct argp}.  The fields are as
  748: follows:
  749: 
  750: @table @code
  751: @item const struct argp *argp
  752: The child argp parser, or zero to end of the list.
  753: 
  754: @item int flags
  755: Flags for this child.
  756: 
  757: @item const char *header
  758: If non-zero, this is an optional header to be printed within help output
  759: before the child options.  As a side-effect, a non-zero value forces the