   This file documents the GNU C library.

   This is Edition 0.10, last updated 2001-07-06, of `The GNU C Library
Reference Manual', for Version 2.2.x.

   Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002
Free Software Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Free Software Needs Free Documentation" and
"GNU Lesser General Public License", the Front-Cover texts being (a)
(see below), and with the Back-Cover Texts being (b) (see below).  A
copy of the license is included in the section entitled "GNU Free
Documentation License".

   (a) The FSF's Front-Cover Text is:

   A GNU Manual

   (b) The FSF's Back-Cover Text is:

   You have freedom to copy and modify this GNU Manual, like GNU
software.  Copies published by the Free Software Foundation raise
funds for GNU development.

Specifying Argp Parsers
-----------------------

   The first argument to the `argp_parse' function is a pointer to a
`struct argp', which is known as an "argp parser":

 - Data Type: struct argp
     This structure specifies how to parse a given set of options and
     arguments, perhaps in conjunction with other argp parsers.  It has
     the following fields:

    `const struct argp_option *options'
          A pointer to a vector of `argp_option' structures specifying
          which options this argp parser understands; it may be zero if
          there are no options at all.  See Argp Option Vectors.

    `argp_parser_t parser'
          A pointer to a function that defines actions for this parser;
          it is called for each option parsed, and at other
          well-defined points in the parsing process.  A value of zero
          is the same as a pointer to a function that always returns
          `ARGP_ERR_UNKNOWN'.  See Argp Parser Functions.

    `const char *args_doc'
          If non-zero, a string describing what non-option arguments
          are called by this parser.  This is only used to print the
          `Usage:' message.  If it contains newlines, the strings
          separated by them are considered alternative usage patterns
          and printed on separate lines.  Lines after the first are
          prefixed by ` or: ' instead of `Usage:'.

    `const char *doc'
          If non-zero, a string containing extra text to be printed
          before and after the options in a long help message, with the
          two sections separated by a vertical tab (`'\v'', `'\013'')
          character.  By convention, the documentation before the
          options is just a short string explaining what the program
          does.  Documentation printed after the options describe
          behavior in more detail.

    `const struct argp_child *children'
          A pointer to a vector of `argp_children' structures.  This
          pointer specifies which additional argp parsers should be
          combined with this one.  See Argp Children.

    `char *(*help_filter)(int KEY, const char *TEXT, void *INPUT)'
          If non-zero, a pointer to a function that filters the output
          of help messages.  See Argp Help Filtering.

    `const char *argp_domain'
          If non-zero, the strings used in the argp library are
          translated using the domain described by this string.  If
          zero, the current default domain is used.

   Of the above group, `options', `parser', `args_doc', and the `doc'
fields are usually all that are needed.  If an argp parser is defined
as an initialized C variable, only the fields used need be specified in
the initializer.  The rest will default to zero due to the way C
structure initialization works.  This design is exploited in most argp
structures; the most-used fields are grouped near the beginning, the
unused fields left unspecified.

Specifying Options in an Argp Parser
------------------------------------

   The `options' field in a `struct argp' points to a vector of `struct
argp_option' structures, each of which specifies an option that the
argp parser supports.  Multiple entries may be used for a single option
provided it has multiple names.  This should be terminated by an entry
with zero in all fields.  Note that when using an initialized C array
for options, writing `{ 0 }' is enough to achieve this.

 - Data Type: struct argp_option
     This structure specifies a single option that an argp parser
     understands, as well as how to parse and document that option.  It
     has the following fields:

    `const char *name'
          The long name for this option, corresponding to the long
          option `--NAME'; this field may be zero if this option _only_
          has a short name.  To specify multiple names for an option,
          additional entries may follow this one, with the
          `OPTION_ALIAS' flag set.  See Argp Option Flags.

    `int key'
          The integer key provided by the current option to the option
          parser.  If KEY has a value that is a printable ASCII
          character (i.e., `isascii (KEY)' is true), it _also_
          specifies a short option `-CHAR', where CHAR is the ASCII
          character with the code KEY.

    `const char *arg'
          If non-zero, this is the name of an argument associated with
          this option, which must be provided (e.g., with the
          `--NAME=VALUE' or `-CHAR VALUE' syntaxes), unless the
          `OPTION_ARG_OPTIONAL' flag (see Argp Option Flags) is
          set, in which case it _may_ be provided.

    `int flags'
          Flags associated with this option, some of which are referred
          to above.  See Argp Option Flags.

    `const char *doc'
          A documentation string for this option, for printing in help
          messages.

          If both the `name' and `key' fields are zero, this string
          will be printed tabbed left from the normal option column,
          making it useful as a group header.  This will be the first
          thing printed in its group.  In this usage, it's conventional
          to end the string with a `:' character.

    `int group'
          Group identity for this option.

          In a long help message, options are sorted alphabetically
          within each group, and the groups presented in the order 0,
          1, 2, ..., N, -M, ..., -2, -1.

          Every entry in an options array with this field 0 will
          inherit the group number of the previous entry, or zero if
          it's the first one.  If it's a group header with `name' and
          `key' fields both zero, the previous entry + 1 is the
          default.  Automagic options such as `--help' are put into
          group -1.

          Note that because of C structure initialization rules, this
          field often need not be specified, because 0 is the correct
          value.

Flags for Argp Options
......................

   The following flags may be or'd together in the `flags' field of a
`struct argp_option'.  These flags control various aspects of how that
option is parsed or displayed in help messages:

`OPTION_ARG_OPTIONAL'
     The argument associated with this option is optional.

`OPTION_HIDDEN'
     This option isn't displayed in any help messages.

`OPTION_ALIAS'
     This option is an alias for the closest previous non-alias option.
     This means that it will be displayed in the same help entry, and
     will inherit fields other than `name' and `key' from the option
     being aliased.

`OPTION_DOC'
     This option isn't actually an option and should be ignored by the
     actual option parser.  It is an arbitrary section of documentation
     that should be displayed in much the same manner as the options.
     This is known as a "documentation option".

     If this flag is set, then the option `name' field is displayed
     unmodified (e.g., no `--' prefix is added) at the left-margin where
     a _short_ option would normally be displayed, and this
     documentation string is left in it's usual place.  For purposes of
     sorting, any leading whitespace and punctuation is ignored, unless
     the first non-whitespace character is `-'.  This entry is displayed
     after all options, after `OPTION_DOC' entries with a leading `-',
     in the same group.

`OPTION_NO_USAGE'
     This option shouldn't be included in `long' usage messages, but
     should still be included in other help messages.  This is intended
     for options that are completely documented in an argp's `args_doc'
     field.  See Argp Parsers.  Including this option in the
     generic usage list would be redundant, and should be avoided.

     For instance, if `args_doc' is `"FOO BAR\n-x BLAH"', and the `-x'
     option's purpose is to distinguish these two cases, `-x' should
     probably be marked `OPTION_NO_USAGE'.

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

   The function pointed to by the `parser' field in a `struct argp'
(see 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.  See
     Argp Option Vectors.  PARSER is also called at other times with
     special reserved keys, such as `ARGP_KEY_ARG' for non-option
     arguments.  See 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.
     See 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.  See 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;
     }

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

Functions For Use in Argp Parsers
.................................

   Argp provides a number of functions available to the user of argp
(see Argp Parser Functions), mostly for producing error messages.
These take as their first argument the STATE argument to the parser
function.  See Argp Parsing State.

 - Function: void argp_usage (const struct argp_state *STATE)
     Outputs the standard usage message for the argp parser referred to
     by STATE to `STATE->err_stream' and terminate the program with
     `exit (argp_err_exit_status)'.  See Argp Global Variables.

 - Function: void argp_error (const struct argp_state *STATE, const
          char *FMT, ...)
     Prints the printf format string FMT and following args, preceded
     by the program name and `:', and followed by a `Try ... --help'
     message, and terminates the program with an exit status of
     `argp_err_exit_status'.  See Argp Global Variables.

 - Function: void argp_failure (const struct argp_state *STATE, int
          STATUS, int ERRNUM, const char *FMT, ...)
     Similar to the standard gnu error-reporting function `error', this
     prints the program name and `:', the printf format string FMT, and
     the appropriate following args.  If it is non-zero, the standard
     unix error text for ERRNUM is printed.  If STATUS is non-zero, it
     terminates the program with that value as its exit status.

     The difference between `argp_failure' and `argp_error' is that
     `argp_error' is for _parsing errors_, whereas `argp_failure' is
     for other problems that occur during parsing but don't reflect a
     syntactic problem with the input, such as illegal values for
     options, bad phase of the moon, etc.

 - Function: void argp_state_help (const struct argp_state *STATE, FILE
          *STREAM, unsigned FLAGS)
     Outputs a help message for the argp parser referred to by STATE,
     to STREAM.  The FLAGS argument determines what sort of help
     message is produced.  See Argp Help Flags.

   Error output is sent to `STATE->err_stream', and the program name
printed is `STATE->name'.

   The output or program termination behavior of these functions may be
suppressed if the `ARGP_NO_EXIT' or `ARGP_NO_ERRS' flags are passed to
`argp_parse'.  See Argp Flags.

   This behavior is useful if an argp parser is exported for use by
other programs (e.g., by a library), and may be used in a context where
it is not desirable to terminate the program in response to parsing
errors.  In argp parsers intended for such general use, and for the
case where the program _doesn't_ terminate, calls to any of these
functions should be followed by code that returns the appropriate error
code:

     if (BAD ARGUMENT SYNTAX)
       {
          argp_usage (STATE);
          return EINVAL;
       }

If a parser function will _only_ be used when `ARGP_NO_EXIT' is not
set, the return may be omitted.

Argp Parsing State
..................

   The third argument to argp parser functions (see Argp Parser Functions)
is a pointer to a `struct argp_state', which contains
information about the state of the option parsing.

 - Data Type: struct argp_state
     This structure has the following fields, which may be modified as
     noted:

    `const struct argp *const root_argp'
          The top level argp parser being parsed.  Note that this is
          often _not_ the same `struct argp' passed into `argp_parse' by
          the invoking program.  See Argp.  It is an internal argp
          parser that contains options implemented by `argp_parse'
          itself, such as `--help'.

    `int argc'
    `char **argv'
          The argument vector being parsed.  This may be modified.

    `int next'
          The index in `argv' of the next argument to be parsed.  This
          may be modified.

          One way to consume all remaining arguments in the input is to
          set `STATE->next = STATE->argc', perhaps after recording the
          value of the `next' field to find the consumed arguments.  The
          current option can be re-parsed immediately by decrementing
          this field, then modifying `STATE->argv[STATE->next]' to
          reflect the option that should be reexamined.

    `unsigned flags'
          The flags supplied to `argp_parse'.  These may be modified,
          although some flags may only take effect when `argp_parse' is
          first invoked.  See Argp Flags.

    `unsigned arg_num'
          While calling a parsing function with the KEY argument
          `ARGP_KEY_ARG', this represents the number of the current arg,
          starting at 0.  It is incremented after each `ARGP_KEY_ARG'
          call returns.  At all other times, this is the number of
          `ARGP_KEY_ARG' arguments that have been processed.

    `int quoted'
          If non-zero, the index in `argv' of the first argument
          following a special `--' argument.  This prevents anything
          that follows from being interpreted as an option.  It is only
          set after argument parsing has proceeded past this point.

    `void *input'
          An arbitrary pointer passed in from the caller of
          `argp_parse', in the INPUT argument.

    `void **child_inputs'
          These are values that will be passed to child parsers.  This
          vector will be the same length as the number of children in
          the current parser.  Each child parser will be given the
          value of `STATE->child_inputs[I]' as _its_ `STATE->input'
          field, where I is the index of the child in the this parser's
          `children' field.  See Argp Children.

    `void *hook'
          For the parser function's use.  Initialized to 0, but
          otherwise ignored by argp.

    `char *name'
          The name used when printing messages.  This is initialized to
          `argv[0]', or `program_invocation_name' if `argv[0]' is
          unavailable.

    `FILE *err_stream'
    `FILE *out_stream'
          The stdio streams used when argp prints.  Error messages are
          printed to `err_stream', all other output, such as `--help'
          output) to `out_stream'.  These are initialized to `stderr'
          and `stdout' respectively.  See Standard Streams.

    `void *pstate'
          Private, for use by the argp implementation.

Combining Multiple Argp Parsers
-------------------------------

   The `children' field in a `struct argp' enables other argp parsers
to be combined with the referencing one for the parsing of a single set
of arguments.  This field should point to a vector of `struct
argp_child', which is terminated by an entry having a value of zero in
the `argp' field.

   Where conflicts between combined parsers arise, as when two specify
an option with the same name, the parser conflicts are resolved in
favor of the parent argp parser(s), or the earlier of the argp parsers
in the list of children.

 - Data Type: struct argp_child
     An entry in the list of subsidiary argp parsers pointed to by the
     `children' field in a `struct argp'.  The fields are as follows:

    `const struct argp *argp'
          The child argp parser, or zero to end of the list.

    `int flags'
          Flags for this child.

    `const char *header'
          If non-zero, this is an optional header to be printed within
          help output before the child options.  As a side-effect, a
          non-zero value forces the child options to be grouped
          together.  To achieve this effect without actually printing a
          header string, use a value of `""'.  As with header strings
          specified in an option entry, the conventional value of the
          last character is `:'.  See Argp Option Vectors.

    `int group'
          This is where the child options are grouped relative to the
          other `consolidated' options in the parent argp parser.  The
          values are the same as the `group' field in `struct
          argp_option'.  See Argp Option Vectors.  All
          child-groupings follow parent options at a particular group
          level.  If both this field and `header' are zero, then the
          child's options aren't grouped together, they are merged with
          parent options at the parent option group level.

Flags for `argp_parse'
----------------------

   The default behavior of `argp_parse' is designed to be convenient
for the most common case of parsing program command line argument.  To
modify these defaults, the following flags may be or'd together in the
FLAGS argument to `argp_parse':

`ARGP_PARSE_ARGV0'
     Don't ignore the first element of the ARGV argument to
     `argp_parse'.  Unless `ARGP_NO_ERRS' is set, the first element of
     the argument vector is skipped for option parsing purposes, as it
     corresponds to the program name in a command line.

`ARGP_NO_ERRS'
     Don't print error messages for unknown options to `stderr'; unless
     this flag is set, `ARGP_PARSE_ARGV0' is ignored, as `argv[0]' is
     used as the program name in the error messages.  This flag implies
     `ARGP_NO_EXIT'.  This is based on the assumption that silent
     exiting upon errors is bad behavior.

`ARGP_NO_ARGS'
     Don't parse any non-option args.  Normally these are parsed by
     calling the parse functions with a key of `ARGP_KEY_ARG', the
     actual argument being the value.  This flag needn't normally be
     set, as the default behavior is to stop parsing as soon as an
     argument fails to be parsed.  See Argp Parser Functions.

`ARGP_IN_ORDER'
     Parse options and arguments in the same order they occur on the
     command line.  Normally they're rearranged so that all options
     come first.

`ARGP_NO_HELP'
     Don't provide the standard long option `--help', which ordinarily
     causes usage and option help information to be output to `stdout'
     and `exit (0)'.

`ARGP_NO_EXIT'
     Don't exit on errors, although they may still result in error
     messages.

`ARGP_LONG_ONLY'
     Use the gnu getopt `long-only' rules for parsing arguments.  This
     allows long-options to be recognized with only a single `-' (i.e.
     `-help').  This results in a less useful interface, and its use is
     discouraged as it conflicts with the way most GNU programs work as
     well as the GNU coding standards.

`ARGP_SILENT'
     Turns off any message-printing/exiting options, specifically
     `ARGP_NO_EXIT', `ARGP_NO_ERRS', and `ARGP_NO_HELP'.

Customizing Argp Help Output
----------------------------

   The `help_filter' field in a `struct argp' is a pointer to a
function that filters the text of help messages before displaying them.
They have a function signature like:

     char *HELP-FILTER (int KEY, const char *TEXT, void *INPUT)

Where KEY is either a key from an option, in which case TEXT is that
option's help text.  See Argp Option Vectors.  Alternately, one of
the special keys with names beginning with `ARGP_KEY_HELP_' might be
used, describing which other help text TEXT will contain.  See Argp Help Filter Keys.

   The function should return either TEXT if it remains as-is, or a
replacement string allocated using `malloc'.  This will be either be
freed by argp or zero, which prints nothing.  The value of TEXT is
supplied _after_ any translation has been done, so if any of the
replacement text needs translation, it will be done by the filter
function.  INPUT is either the input supplied to `argp_parse' or it is
zero, if `argp_help' was called directly by the user.

Special Keys for Argp Help Filter Functions
...........................................

   The following special values may be passed to an argp help filter
function as the first argument in addition to key values for user
options.  They specify which help text the TEXT argument contains:

`ARGP_KEY_HELP_PRE_DOC'
     The help text preceding options.

`ARGP_KEY_HELP_POST_DOC'
     The help text following options.

`ARGP_KEY_HELP_HEADER'
     The option header string.

`ARGP_KEY_HELP_EXTRA'
     This is used after all other documentation; TEXT is zero for this
     key.

`ARGP_KEY_HELP_DUP_ARGS_NOTE'
     The explanatory note printed when duplicate option arguments have
     been suppressed.

`ARGP_KEY_HELP_ARGS_DOC'
     The argument doc string; formally the `args_doc' field from the
     argp parser.  See Argp Parsers.

The `argp_help' Function
------------------------

   Normally programs using argp need not be written with particular
printing argument-usage-type help messages in mind as the standard
`--help' option is handled automatically by argp.  Typical error cases
can be handled using `argp_usage' and `argp_error'.  See Argp Helper Functions.
However, if it's desirable to print a help message in
some context other than parsing the program options, argp offers the
`argp_help' interface.

 - Function: void argp_help (const struct argp *ARGP, FILE *STREAM,
          unsigned FLAGS, char *NAME)
     This outputs a help message for the argp parser ARGP to STREAM.
     The type of messages printed will be determined by FLAGS.

     Any options such as `--help' that are implemented automatically by
     argp itself will _not_ be present in the help output; for this
     reason it is best to use `argp_state_help' if calling from within
     an argp parser function.  See Argp Helper Functions.

Flags for the `argp_help' Function
----------------------------------

   When calling `argp_help' (see Argp Help) or `argp_state_help'
(see Argp Helper Functions) the exact output is determined by the
FLAGS argument.  This should consist of any of the following flags,
or'd together:

`ARGP_HELP_USAGE'
     A unix `Usage:' message that explicitly lists all options.

`ARGP_HELP_SHORT_USAGE'
     A unix `Usage:' message that displays an appropriate placeholder to
     indicate where the options go; useful for showing the non-option
     argument syntax.

`ARGP_HELP_SEE'
     A `Try ... for more help' message; `...' contains the program name
     and `--help'.

`ARGP_HELP_LONG'
     A verbose option help message that gives each option available
     along with its documentation string.

`ARGP_HELP_PRE_DOC'
     The part of the argp parser doc string preceding the verbose
     option help.

`ARGP_HELP_POST_DOC'
     The part of the argp parser doc string that following the verbose
     option help.

`ARGP_HELP_DOC'
     `(ARGP_HELP_PRE_DOC | ARGP_HELP_POST_DOC)'

`ARGP_HELP_BUG_ADDR'
     A message that prints where to report bugs for this program, if the
     `argp_program_bug_address' variable contains this information.

`ARGP_HELP_LONG_ONLY'
     This will modify any output to reflect the `ARGP_LONG_ONLY' mode.

   The following flags are only understood when used with
`argp_state_help'.  They control whether the function returns after
printing its output, or terminates the program:

`ARGP_HELP_EXIT_ERR'
     This will terminate the program with `exit (argp_err_exit_status)'.

`ARGP_HELP_EXIT_OK'
     This will terminate the program with `exit (0)'.

   The following flags are combinations of the basic flags for printing
standard messages:

`ARGP_HELP_STD_ERR'
     Assuming that an error message for a parsing error has printed,
     this prints a message on how to get help, and terminates the
     program with an error.

`ARGP_HELP_STD_USAGE'
     This prints a standard usage message and terminates the program
     with an error.  This is used when no other specific error messages
     are appropriate or available.

`ARGP_HELP_STD_HELP'
     This prints the standard response for a `--help' option, and
     terminates the program successfully.

Argp Examples
-------------

   These example programs demonstrate the basic usage of argp.

A Minimal Program Using Argp
............................

   This is perhaps the smallest program possible that uses argp.  It
won't do much except give an error messages and exit when there are any
arguments, and prints a rather pointless message for `--help'.

     /* Argp example #1 - a minimal program using argp */

     /* This is (probably) the smallest possible program that
        uses argp.  It won't do much except give an error
        messages and exit when there are any arguments, and print
        a (rather pointless) messages for -help. */

     #include <argp.h>

     int main (int argc, char **argv)
     {
       argp_parse (0, argc, argv, 0, 0, 0);
       exit (0);
     }

A Program Using Argp with Only Default Options
..............................................

   This program doesn't use any options or arguments, it uses argp to be
compliant with the GNU standard command line format.

   In addition to giving no arguments and implementing a `--help'
option, this example has a `--version' option, which will put the given
documentation string and bug address in the `--help' output, as per GNU
standards.

   The variable `argp' contains the argument parser specification.
Adding fields to this structure is the way most parameters are passed
to `argp_parse'.  The first three fields are normally used, but they
are not in this small program.  There are also two global variables
that argp can use defined here, `argp_program_version' and
`argp_program_bug_address'.  They are considered global variables
because they will almost always be constant for a given program, even
if they use different argument parsers for various tasks.

     /* Argp example #2 - a pretty minimal program using argp */

     /* This program doesn't use any options or arguments, but uses
        argp to be compliant with the GNU standard command line
        format.

        In addition to making sure no arguments are given, and
        implementing a -help option, this example will have a
        -version option, and will put the given documentation string
        and bug address in the -help output, as per GNU standards.

        The variable ARGP contains the argument parser specification;
        adding fields to this structure is the way most parameters are
        passed to argp_parse (the first three fields are usually used,
        but not in this small program).  There are also two global
        variables that argp knows about defined here,
        ARGP_PROGRAM_VERSION and ARGP_PROGRAM_BUG_ADDRESS (they are
        global variables because they will almost always be constant
        for a given program, even if it uses different argument
        parsers for various tasks). */

     #include <argp.h>

     const char *argp_program_version =
       "argp-ex2 1.0";
     const char *argp_program_bug_address =
       "<bug-gnu-utils@gnu.org>";

     /* Program documentation. */
     static char doc[] =
       "Argp example #2 -- a pretty minimal program using argp";

     /* Our argument parser.  The `options', `parser', and
        `args_doc' fields are zero because we have neither options or
        arguments; `doc' and `argp_program_bug_address' will be
        used in the output for `--help', and the `--version'
        option will print out `argp_program_version'. */
     static struct argp argp = { 0, 0, 0, doc };

     int main (int argc, char **argv)
     {
       argp_parse (&argp, argc, argv, 0, 0, 0);
       exit (0);
     }

A Program Using Argp with User Options
......................................

   This program uses the same features as example 2, adding user options
and arguments.

   We now use the first four fields in `argp' (see Argp Parsers)
and specify `parse_opt' as the parser function.  See Argp Parser Functions.

   Note that in this example, `main' uses a structure to communicate
with the `parse_opt' function, a pointer to which it passes in the
`input' argument to `argp_parse'.  See Argp.  It is retrieved by
`parse_opt' through the `input' field in its `state' argument.  See
Argp Parsing State.  Of course, it's also possible to use global
variables instead, but using a structure like this is somewhat more
flexible and clean.

     /* Argp example #3 - a program with options and arguments using argp */

     /* This program uses the same features as example 2, and uses options and
        arguments.

        We now use the first four fields in ARGP, so here's a description of them:
          OPTIONS  - A pointer to a vector of struct argp_option (see below)
          PARSER   - A function to parse a single option, called by argp
          ARGS_DOC - A string describing how the non-option arguments should look
          DOC      - A descriptive string about this program; if it contains a
                      vertical tab character (\v), the part after it will be
                      printed *following* the options

        The function PARSER takes the following arguments:
          KEY  - An integer specifying which option this is (taken
                  from the KEY field in each struct argp_option), or
                  a special key specifying something else; the only
                  special keys we use here are ARGP_KEY_ARG, meaning
                  a non-option argument, and ARGP_KEY_END, meaning
                  that all arguments have been parsed
          ARG  - For an option KEY, the string value of its
                  argument, or NULL if it has none
          STATE- A pointer to a struct argp_state, containing
                  various useful information about the parsing state; used here
                  are the INPUT field, which reflects the INPUT argument to
                  argp_parse, and the ARG_NUM field, which is the number of the
                  current non-option argument being parsed
        It should return either 0, meaning success, ARGP_ERR_UNKNOWN, meaning the
        given KEY wasn't recognized, or an errno value indicating some other
        error.

        Note that in this example, main uses a structure to communicate with the
        parse_opt function, a pointer to which it passes in the INPUT argument to
        argp_parse.  Of course, it's also possible to use global variables
        instead, but this is somewhat more flexible.

        The OPTIONS field contains a pointer to a vector of struct argp_option's;
        that structure has the following fields (if you assign your option
        structures using array initialization like this example, unspecified
        fields will be defaulted to 0, and need not be specified):
          NAME   - The name of this option's long option (may be zero)
          KEY    - The KEY to pass to the PARSER function when parsing this option,
                    *and* the name of this option's short option, if it is a
                    printable ascii character
          ARG    - The name of this option's argument, if any
          FLAGS  - Flags describing this option; some of them are:
                      OPTION_ARG_OPTIONAL - The argument to this option is optional
                      OPTION_ALIAS        - This option is an alias for the
                                             previous option
                      OPTION_HIDDEN       - Don't show this option in -help output
          DOC    - A documentation string for this option, shown in -help output

        An options vector should be terminated by an option with all fields zero. */

     #include <argp.h>

     const char *argp_program_version =
       "argp-ex3 1.0";
     const char *argp_program_bug_address =
       "<bug-gnu-utils@gnu.org>";

     /* Program documentation. */
     static char doc[] =
       "Argp example #3 -- a program with options and arguments using argp";

     /* A description of the arguments we accept. */
     static char args_doc[] = "ARG1 ARG2";

     /* The options we understand. */
     static struct argp_option options[] = {
       {"verbose",  'v', 0,      0,  "Produce verbose output" },
       {"quiet",    'q', 0,      0,  "Don't produce any output" },
       {"silent",   's', 0,      OPTION_ALIAS },
       {"output",   'o', "FILE", 0,
        "Output to FILE instead of standard output" },
       { 0 }
     };

     /* Used by `main' to communicate with `parse_opt'. */
     struct arguments
     {
       char *args[2];                /* ARG1 & ARG2 */
       int silent, verbose;
       char *output_file;
     };

     /* Parse a single option. */
     static error_t
     parse_opt (int key, char *arg, struct argp_state *state)
     {
       /* Get the INPUT argument from `argp_parse', which we
          know is a pointer to our arguments structure. */
       struct arguments *arguments = state->input;

       switch (key)
         {
         case 'q': case 's':
           arguments->silent = 1;
           break;
         case 'v':
           arguments->verbose = 1;
           break;
         case 'o':
           arguments->output_file = arg;
           break;

         case ARGP_KEY_ARG:
           if (state->arg_num >= 2)
             /* Too many arguments. */
             argp_usage (state);

           arguments->args[state->arg_num] = arg;

           break;

         case ARGP_KEY_END:
           if (state->arg_num < 2)
             /* Not enough arguments. */
             argp_usage (state);
           break;

         default:
           return ARGP_ERR_UNKNOWN;
         }
       return 0;
     }

     /* Our argp parser. */
     static struct argp argp = { options, parse_opt, args_doc, doc };

     int main (int argc, char **argv)
     {
       struct arguments arguments;

       /* Default values. */
       arguments.silent = 0;
       arguments.verbose = 0;
       arguments.output_file = "-";

       /* Parse our arguments; every option seen by `parse_opt' will
          be reflected in `arguments'. */
       argp_parse (&argp, argc, argv, 0, 0, &arguments);

       printf ("ARG1 = %s\nARG2 = %s\nOUTPUT_FILE = %s\n"
               "VERBOSE = %s\nSILENT = %s\n",
               arguments.args[0], arguments.args[1],
               arguments.output_file,
               arguments.verbose ? "yes" : "no",
               arguments.silent ? "yes" : "no");

       exit (0);
     }