--- /dev/null
+@ignore
+ Documentation for the argp argument parser
+
+ Copyright (C) 1995, 1996, 1997 Free Software Foundation, Inc.
+ This file is part of the GNU C Library.
+ Written by Miles Bader <miles@gnu.ai.mit.edu>.
+
+ The GNU C Library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Library General Public License as
+ published by the Free Software Foundation; either version 2 of the
+ License, or (at your option) any later version.
+
+ The GNU C Library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Library General Public License for more details.
+
+ You should have received a copy of the GNU Library General Public
+ License along with the GNU C Library; see the file COPYING.LIB. If not,
+ write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ Boston, MA 02111-1307, USA. */
+@end ignore
+
+@node Argp, Suboptions, Getopt, Parsing Program Arguments
+@need 5000
+@section Parsing Program Options with Argp
+@cindex argp (program argument parser)
+@cindex argument parsing with argp
+@cindex option parsing with argp
+
+@dfn{Argp} is an interface for parsing unix-style argument vectors
+(@pxref{Program Arguments}).
+
+Unlike the more common @code{getopt} interface, it provides many related
+convenience features in addition to parsing options, such as
+automatically producing output in response to @samp{--help} and
+@samp{--version} options (as defined by the GNU coding standards).
+Doing these things in argp results in a more consistent look for
+programs that use it, and makes less likely that implementors will
+neglect to implement them or keep them up-to-date.
+
+Argp also provides the ability to merge several independently defined
+option parsers into one, mediating conflicts between them, and making
+the result appear seamless. A library can export an argp option parser,
+which programs can easily use in conjunction with their own option
+parser. This results in less work for user programs (indeed, some may
+use only argument parsers exported by libraries, and have no options of
+their own), and more consistent option-parsing for the abstractions
+implemented by the library.
+
+@pindex argp.h
+The header file @file{<argp.h>} should be included to use argp.
+
+@subsection The @code{argp_parse} Function
+
+The main interface to argp is the @code{argp_parse} function; often, a
+call to @code{argp_parse} is the only argument-parsing code needed in
+@code{main} (@pxref{Program Arguments}).
+
+@comment argp.h
+@comment GNU
+@deftypefun {error_t} argp_parse (const struct argp *@var{argp}, @w{int @var{argc}, char **@var{argv}}, @w{unsigned @var{flags}}, @w{int *@var{arg_index}}, @w{void *@var{input}})
+The @code{argp_parse} function parses the arguments in in @var{argv}, of
+length @var{argc}, using the argp parser @var{argp} (@pxref{Argp
+Parsers}); a value of zero is the same as a @code{struct argp}
+containing all zeros. @var{flags} is a set of flag bits that modify the
+parsing behavior (@pxref{Argp Flags}). @var{input} is passed through to
+the argp parser @var{argp}, and has meaning defined by it; a typical
+usage is to pass a pointer to a structure which can be used for
+specifying parameters to the parser and passing back results from it.
+
+Unless the @code{ARGP_NO_EXIT} or @code{ARGP_NO_HELP} flags are included
+in @var{flags}, calling @code{argp_parse} may result in the program
+exiting---for instance when an unknown option is encountered.
+@xref{Program Termination}.
+
+The return value is zero for successful parsing, or a unix error code
+(@pxref{Error Codes}) if an error was detected. Different argp parsers
+may return arbitrary error codes, but standard ones are @code{ENOMEM} if
+a memory allocation error occurred, or @code{EINVAL} if an unknown option
+or option argument was encountered.
+@end deftypefun
+
+@menu
+* Globals: Argp Global Variables. Global argp parameters.
+* Parsers: Argp Parsers. Defining parsers for use with @code{argp_parse}.
+* Flags: Argp Flags. Flags that modify the behavior of @code{argp_parse}.
+* Help: Argp Help. Printing help messages when not parsing.
+* Examples: Argp Examples. Simple examples of programs using argp.
+* Customization: Argp User Customization.
+ Users may control the @samp{--help} output format.
+@end menu
+
+@node Argp Global Variables, Argp Parsers, , Argp
+@subsection Argp Global Variables
+
+These variables make it very easy for every user program to implement
+the @samp{--version} option and provide a bug-reporting address in the
+@samp{--help} output (which is implemented by argp regardless).
+
+@comment argp.h
+@comment GNU
+@deftypevar {const char *} argp_program_version
+If defined or set by the user program to a non-zero value, then a
+@samp{--version} option is added when parsing with @code{argp_parse}
+(unless the @code{ARGP_NO_HELP} flag is used), which will print this
+string followed by a newline and exit (unless the @code{ARGP_NO_EXIT}
+flag is used).
+@end deftypevar
+
+@comment argp.h
+@comment GNU
+@deftypevar {const char *} argp_program_bug_address
+If defined or set by the user program to a non-zero value,
+@code{argp_program_bug_address} should point to string that is the
+bug-reporting address for the program. It will be printed at the end of
+the standard output for the @samp{--help} option, embedded in a sentence
+that says something like @samp{Report bugs to @var{address}.}.
+@end deftypevar
+
+@need 1500
+@comment argp.h
+@comment GNU
+@defvar argp_program_version_hook
+If defined or set by the user program to a non-zero value, then a
+@samp{--version} option is added when parsing with @code{argp_parse}
+(unless the @code{ARGP_NO_HELP} flag is used), which calls this function
+to print the version, and then exits with a status of 0 (unless the
+@code{ARGP_NO_EXIT} flag is used). It should point to a function with
+the following type signature:
+
+@smallexample
+void @var{print-version} (FILE *@var{stream}, struct argp_state *@var{state})
+@end smallexample
+
+@noindent
+@xref{Argp Parsing State}, for an explanation of @var{state}.
+
+This variable takes precedent over @code{argp_program_version}, and is
+useful if a program has version information that cannot be easily
+specified as a simple string.
+@end defvar
+
+@comment argp.h
+@comment GNU
+@deftypevar error_t argp_err_exit_status
+The exit status that argp will use when exiting due to a parsing error.
+If not defined or set by the user program, this defaults to
+@code{EX_USAGE} from @file{<sysexits.h>}.
+@end deftypevar
+
+@node Argp Parsers, Argp Flags, Argp Global Variables, Argp
+@subsection Specifying Argp Parsers
+
+The first argument to the @code{argp_parse} function is a pointer to a
+@code{struct argp}, which known as an @dfn{argp parser}:
+
+@comment argp.h
+@comment GNU
+@deftp {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:
+
+@table @code
+@item const struct argp_option *options
+A pointer to a vector of @code{argp_option} structures specifying which
+options this argp parser understands; it may be zero if there are no
+options at all. @xref{Argp Option Vectors}.
+
+@item 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 @code{ARGP_ERR_UNKNOWN}.
+@xref{Argp Parser Functions}.
+
+@item const char *args_doc
+If non-zero, a string describing what non-option arguments are wanted by
+this parser; it is only used to print the @samp{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 prefix by @samp{ or: } instead of @samp{Usage:}).
+
+@item 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 (@code{'\v'}, @code{'\013'}) character. By
+convention, the documentation before the options is just a short string
+saying what the program does, and that afterwards is longer, describing
+the behavior in more detail.
+
+@item const struct argp_child *children
+A pointer to a vector of @code{argp_children} structures specifying
+additional argp parsers that should be combined with this one.
+@xref{Argp Children}.
+
+@item char *(*help_filter)(int @var{key}, const char *@var{text}, void *@var{input})
+If non-zero, a pointer to a function to filter the output of help
+messages. @xref{Argp Help Filtering}.
+@end table
+@end deftp
+
+The @code{options}, @code{parser}, @code{args_doc}, and @code{doc}
+fields are usually all that are needed. If an argp parser is defined as
+an initialized C variable, only the used fields need be specified in in
+the initializer---the rest will default to zero due to the way C
+structure initialization works (this fact is exploited for most argp
+structures, grouping the most-used fields near the beginning, so that
+unused fields can simply be left unspecified).
+
+@menu
+* Options: Argp Option Vectors. Specifying options in an argp parser.
+* Argp Parser Functions:: Defining actions for an argp parser.
+* Children: Argp Children. Combining multiple argp parsers.
+* Help Filtering: Argp Help Filtering. Customizing help output for an argp parser.
+@end menu
+
+@node Argp Option Vectors, Argp Parser Functions, Argp Parsers, Argp Parsers
+@subsection Specifying Options in an Argp Parser
+
+The @code{options} field in a @code{struct argp} points to a vector of
+@code{struct argp_option} structures, each of which specifies an option
+that argp parser supports (actually, sometimes multiple entries may used
+for a single option if it has many names). It should be terminated by
+an entry with zero in all fields (note that when using an initialized C
+array for options, writing @code{@{ 0 @}} is enough to achieve this).
+
+@comment argp.h
+@comment GNU
+@deftp {Data Type} {struct argp_option}
+This structure specifies a single option that an argp parser
+understands, and how to parse and document it. It has the following fields:
+
+@table @code
+@item const char *name
+The long name for this option, corresponding to the long option
+@samp{--@var{name}}; this field can 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 @code{OPTION_ALIAS} flag set (@pxref{Argp
+Option Flags}).
+
+@item int key
+The integer key that is provided to the argp parser's parsing function
+when this option is being parsed. Also, if @var{key} has a value that
+is a printable @sc{ascii} character (i.e., @code{isascii (@var{key})} is
+true), it @emph{also} specifies a short option @samp{-@var{char}}, where
+@var{char} is the @sc{ascii} character with the code @var{key}.
+
+@item 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
+@samp{--@var{name}=@var{value}} or @samp{-@var{char} @var{value}}
+syntaxes) unless the @code{OPTION_ARG_OPTIONAL} flag (@pxref{Argp Option
+Flags}) is set, in which case it @emph{may} be provided.
+
+@item int flags
+Flags associated with this option (some of which are referred to above).
+@xref{Argp Option Flags}.
+
+@item const char *doc
+A documentation string for this option, for printing in help messages.
+
+If both the @code{name} and @code{key} fields are zero, this string
+will be printed out-dented from the normal option column, making it
+useful as a group header (it will be the first thing printed in its
+group); in this usage, it's conventional to end the string with a
+@samp{:} character.
+
+@item int group
+The group this option is in.
+
+In a long help message, options are sorted alphabetically within each
+group, and the groups presented in the order 0, 1, 2, @dots{}, @var{n},
+-@var{m}, @dots{}, -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, unless its a group header (@code{name} and
+@code{key} fields both zero), in which case, the previous entry + 1 is
+the default. Automagic options such as @samp{--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 right value.
+@end table
+@end deftp
+
+@menu
+* Flags: Argp Option Flags. Flags for options.
+@end menu
+
+@node Argp Option Flags, , , Argp Option Vectors
+@subsubsection Flags for Argp Options
+
+The following flags may be or'd together in the @code{flags} field of a
+@code{struct argp_option}, and control various aspects of how that
+option is parsed or displayed in help messages:
+
+@vtable @code
+@comment argp.h
+@comment GNU
+@item OPTION_ARG_OPTIONAL
+The argument associated with this option is optional.
+
+@comment argp.h
+@comment GNU
+@item OPTION_HIDDEN
+This option isn't displayed in any help messages.
+
+@comment argp.h
+@comment GNU
+@item 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 @code{name} and @code{key} from the aliased option.
+
+@comment argp.h
+@comment GNU
+@item OPTION_DOC
+This option isn't actually an option (and so should be ignored by the
+actual option parser), but rather an arbitrary piece of documentation
+that should be displayed in much the same manner as the options (known
+as a @dfn{documentation option}).
+
+If this flag is set, then the option @code{name} field is displayed
+unmodified (e.g., no @samp{--} prefix is added) at the left-margin
+(where a @emph{short} option would normally be displayed), and the
+documentation string in the normal place. For purposes of sorting, any
+leading whitespace and punctuation is ignored, except that if the first
+non-whitespace character is not @samp{-}, this entry is displayed after
+all options (and @code{OPTION_DOC} entries with a leading @samp{-}) in
+the same group.
+
+@comment argp.h
+@comment GNU
+@item OPTION_NO_USAGE
+This option shouldn't be included in `long' usage messages (but is still
+included in help messages). This is mainly intended for options that
+are completely documented in an argp's @code{args_doc} field
+(@pxref{Argp Parsers}), in which case including the option
+in the generic usage list would be redundant.
+
+For instance, if @code{args_doc} is @code{"FOO BAR\n-x BLAH"}, and the
+@samp{-x} option's purpose is to distinguish these two cases, @samp{-x}
+should probably be marked @code{OPTION_NO_USAGE}.
+@end vtable
+
+@node Argp Parser Functions, Argp Children, Argp Option Vectors, Argp Parsers
+@subsection Argp Parser Functions
+
+The function pointed to by the @code{parser} field in a @code{struct
+argp} (@pxref{Argp Parsers}) defines what actions take place in response
+to each option or argument that is parsed, and is also used as a hook,
+to allow a parser to do something at certain other points during
+parsing.
+
+@need 2000
+Argp parser functions have the following type signature:
+
+@cindex argp parser functions
+@smallexample
+error_t @var{parser} (int @var{key}, char *@var{arg}, struct argp_state *@var{state})
+@end smallexample
+
+@noindent
+where the arguments are as follows:
+
+@table @var
+@item key
+For each option that is parsed, @var{parser} is called with a value of
+@var{key} from that option's @code{key} field in the option vector
+(@pxref{Argp Option Vectors}). @var{parser} is also called at other
+times with special reserved keys, such as @code{ARGP_KEY_ARG} for
+non-option arguments. @xref{Argp Special Keys}.
+
+@item arg
+If @var{key} is an option, @var{arg} is the value given for it, or zero
+if no value was specified. Only options that have a non-zero @code{arg}
+field can ever have a value, and those must @emph{always} have a value,
+unless the @code{OPTION_ARG_OPTIONAL} flag was specified (if the input
+being parsed specifies a value for an option that doesn't allow one, an
+error results before @var{parser} ever gets called).
+
+If @var{key} is @code{ARGP_KEY_ARG}, @var{arg} is a non-option argument;
+other special keys always have a zero @var{arg}.
+
+@item state
+@var{state} points to a @code{struct argp_state}, containing useful
+information about the current parsing state for use by @var{parser}.
+@xref{Argp Parsing State}.
+@end table
+
+When @var{parser} is called, it should perform whatever action is
+appropriate for @var{key}, and return either @code{0} for success,
+@code{ARGP_ERR_UNKNOWN}, if the value of @var{key} is not handled by
+this parser function, or a unix error code if a real error occurred
+(@pxref{Error Codes}).
+
+@comment argp.h
+@comment GNU
+@deftypevr Macro int ARGP_ERR_UNKNOWN
+Argp parser functions should return @code{ARGP_ERR_UNKNOWN} for any
+@var{key} value they do not recognize, or for non-option arguments
+(@code{@var{key} == ARGP_KEY_ARG}) that they do not which to handle.
+@end deftypevr
+
+@need 3000
+A typical parser function uses a switch statement on @var{key}:
+
+@smallexample
+error_t
+parse_opt (int key, char *arg, struct argp_state *state)
+@{
+ switch (key)
+ @{
+ case @var{option_key}:
+ @var{action}
+ break;
+ @dots{}
+ default:
+ return ARGP_ERR_UNKNOWN;
+ @}
+ return 0;
+@}
+@end smallexample
+
+@menu
+* Keys: Argp Special Keys. Special values for the @var{key} argument.
+* State: Argp Parsing State. What the @var{state} argument refers to.
+* Functions: Argp Helper Functions. Functions to help during argp parsing.
+@end menu
+
+@node Argp Special Keys, Argp Parsing State, , Argp Parser Functions
+@subsubsection Special Keys for Argp Parser Functions
+
+In addition to key values corresponding to user options, the @var{key}
+argument to argp parser functions may have a number of other special
+values (@var{arg} and @var{state} refer to parser function arguments;
+@pxref{Argp Parser Functions}):
+
+@vtable @code
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_ARG
+This is not an option at all, but rather a command line argument, whose
+value is pointed to by @var{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 @code{ARGP_ERR_UNKNOWN}; if an argument is handled by no one,
+@code{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 @code{ARGP_KEY_NO_ARGS} case won't be used.
+@emph{However}, if while processing the argument, a parser function
+decrements the @code{next} field of its @var{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.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_END
+There are no more command line arguments at all.
+
+@comment argp.h
+@comment GNU
+@item 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 @code{ARGP_KEY_END} (where more general validity checks on
+previously parsed arguments can take place).
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_INIT
+Passed in before any parsing is done. Afterwards, the values of each
+element of the @code{child_input} field of @var{state}, if any, are
+copied to each child's state to be the initial value of the @code{input}
+when @emph{their} parsers are called.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_SUCCESS
+Passed in when parsing has successfully been completed (even if there are
+still arguments remaining).
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_ERROR
+Passed in if an error has occurred, and parsing terminated (in which case
+a call with a key of @code{ARGP_KEY_SUCCESS} is never made).
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_FINI
+The final key ever seen by any parser (even after
+@code{ARGP_KEY_SUCCESS} and @code{ARGP_KEY_ERROR}). Any resources
+allocated by @code{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 @code{ARGP_KEY_ERROR} case).
+@end vtable
+
+In all cases, @code{ARGP_KEY_INIT} is the first key seen by parser
+functions, and @code{ARGP_KEY_FINI} the last (unless an error was
+returned by the parser for @code{ARGP_KEY_INIT}). Other keys can occur
+in one the following orders (@var{opt} refers to an arbitrary option
+key):
+
+@table @asis
+@item @var{opt}@dots{} @code{ARGP_KEY_NO_ARGS} @code{ARGP_KEY_END} @code{ARGP_KEY_SUCCESS}
+The arguments being parsed contained no non-option arguments at all.
+
+@item ( @var{opt} | @code{ARGP_KEY_ARG} )@dots{} @code{ARGP_KEY_END} @code{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).
+
+@item ( @var{opt} | @code{ARGP_KEY_ARG} )@dots{} @code{ARGP_KEY_SUCCESS}
+Some non-option argument was unrecognized.
+
+This occurs when every parser function returns @code{ARGP_KEY_UNKNOWN}
+for an argument, in which case parsing stops at that argument. If a
+non-zero value for @var{arg_index} was passed to @code{argp_parse}, the
+index of this argument is returned in it, otherwise an error occurs.
+@end table
+
+If an error occurs (either detected by argp, or because a parser
+function returned an error value), then each parser is called with
+@code{ARGP_KEY_ERROR}, and no further calls are made except the final
+call with @code{ARGP_KEY_FINI}.
+
+@node Argp Helper Functions, , Argp Parsing State, Argp Parser Functions
+@subsubsection Functions For Use in Argp Parsers
+
+Argp provides a number of functions for the user of argp parser
+functions (@pxref{Argp Parser Functions}), mostly for producing error
+messages. These take as their first argument the @var{state} argument
+to the parser function (@pxref{Argp Parsing State}).
+
+@cindex usage messages, in argp
+@comment argp.h
+@comment GNU
+@deftypefun void argp_usage (const struct argp_state *@var{state})
+Output the standard usage message for the argp parser referred to by
+@var{state} to @code{@var{state}->err_stream} and terminate the program
+with @code{exit (argp_err_exit_status)} (@pxref{Argp Global Variables}).
+@end deftypefun
+
+@cindex syntax error messages, in argp
+@comment argp.h
+@comment GNU
+@deftypefun void argp_error (const struct argp_state *@var{state}, @w{const char *@var{fmt}, @dots{}})
+Print the printf format string @var{fmt} and following args, preceded by
+the program name and @samp{:}, and followed by a @w{@samp{Try @dots{}
+--help}} message, and terminate the program with an exit status of
+@code{argp_err_exit_status} (@pxref{Argp Global Variables}).
+@end deftypefun
+
+@cindex error messages, in argp
+@comment argp.h
+@comment GNU
+@deftypefun void argp_failure (const struct argp_state *@var{state}, @w{int @var{status}, int @var{errnum},} @w{const char *@var{fmt}, @dots{}})
+Similarly to the standard gnu error-reporting function @code{error},
+print the printf format string @var{fmt} and following args, preceded by
+the program name and @samp{:}, and followed by the standard unix error
+text for @var{errnum} if it is non-zero; then if @var{status} is
+non-zero, terminate the program with that as its exit status.
+
+The difference between this function and @code{argp_error} is that
+@code{argp_error} is for @emph{parsing errors}, whereas
+@code{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.
+@end deftypefun
+
+@comment argp.h
+@comment GNU
+@deftypefun void argp_state_help (const struct argp_state *@var{state}, @w{FILE *@var{stream}}, @w{unsigned @var{flags}})
+Output a help message for the argp parser referred to by @var{state} to
+@var{stream}. The @var{flags} argument determines what sort of help
+message is produced. @xref{Argp Help Flags}.
+@end deftypefun
+
+Error output is sent to @code{@var{state}->err_stream}, and the program
+name printed is @code{@var{state}->name}.
+
+The output or program termination behavior of these functions may be
+suppressed if the @code{ARGP_NO_EXIT} or @code{ARGP_NO_ERRS} flags,
+respectively, were passed to @code{argp_parse}. @xref{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, calls to any of these
+functions should be followed by code return of an appropriate error code
+for the case where the program @emph{doesn't} terminate; for example:
+
+@smallexample
+if (@var{bad argument syntax})
+ @{
+ argp_usage (@var{state});
+ return EINVAL;
+ @}
+@end smallexample
+
+@noindent
+If it's known that a parser function will only be used when
+@code{ARGP_NO_EXIT} is not set, the return may be omitted.
+
+@node Argp Parsing State, Argp Helper Functions, Argp Special Keys, Argp Parser Functions
+@subsubsection Argp Parsing State
+
+The third argument to argp parser functions (@pxref{Argp Parser
+Functions}) is a pointer to a @code{struct argp_state}, which contains
+information about the state of the option parsing.
+
+@comment argp.h
+@comment GNU
+@deftp {Data Type} {struct argp_state}
+This structure has the following fields, which may be modified as noted:
+
+@table @code
+@item const struct argp *const root_argp
+The top level argp parser being parsed. Note that this is often
+@emph{not} the same @code{struct argp} passed into @code{argp_parse} by
+the invoking program (@pxref{Argp}), but instead an internal argp parser
+that contains options implemented by @code{argp_parse} itself (such as
+@samp{--help}).
+
+@item int argc
+@itemx char **argv
+The argument vector being parsed. May be modified.
+
+@item int next
+The index in @code{argv} of the next argument to be parsed. May be modified.
+
+One way to consume all remaining arguments in the input is to set
+@code{@var{state}->next = @var{state}->argc} (perhaps after recording
+the value of the @code{next} field to find the consumed arguments).
+Also, you can cause the current option to be re-parsed by decrementing
+this field, and then modifying
+@code{@var{state}->argv[@var{state}->next]} to be the option that should
+be reexamined.
+
+@item unsigned flags
+The flags supplied to @code{argp_parse}. May be modified, although some
+flags may only take effect when @code{argp_parse} is first invoked.
+@xref{Argp Flags}.
+
+@item unsigned arg_num
+While calling a parsing function with the @var{key} argument
+@code{ARGP_KEY_ARG}, this is the number of the current arg, starting at
+0, and incremented after each such call returns. At all other times,
+this is the number of such arguments that have been processed.
+
+@item int quoted
+If non-zero, the index in @code{argv} of the first argument following a
+special @samp{--} argument (which prevents anything following being
+interpreted as an option). Only set once argument parsing has proceeded
+past this point.
+
+@item void *input
+An arbitrary pointer passed in from the caller of @code{argp_parse}, in
+the @var{input} argument.
+
+@item void **child_inputs
+Values to pass to child parsers. This vector will be the same length as
+the number of children in the current parser, and each child parser will
+be given the value of @code{@var{state}->child_inputs[@var{i}]} as
+@emph{its} @code{@var{state}->input} field, where @var{i} is the index
+of the child in the this parser's @code{children} field. @xref{Argp
+Children}.
+
+@item void *hook
+For the parser function's use. Initialized to 0, but otherwise ignored
+by argp.
+
+@item char *name
+The name used when printing messages. This is initialized to
+@code{argv[0]}, or @code{program_invocation_name} if that is
+unavailable.
+
+@item FILE *err_stream
+@itemx FILE *out_stream
+Stdio streams used when argp prints something; error messages are
+printed to @code{err_stream}, and all other output (such as
+@samp{--help} output) to @code{out_stream}. These are initialized to
+@code{stderr} and @code{stdout} respectively (@pxref{Standard Streams}).
+
+@item void *pstate
+Private, for use by the argp implementation.
+@end table
+@end deftp
+
+@node Argp Children, Argp Help Filtering, Argp Parser Functions, Argp Parsers
+@subsection Combining Multiple Argp Parsers
+
+The @code{children} field in a @code{struct argp} allows other argp
+parsers to be combined with the referencing one to parse a single set of
+arguments. It should point to a vector of @code{struct argp_child},
+terminated by an entry having a value of zero in the @code{argp} field.
+
+Where conflicts between combined parsers arise (for instance, if two
+specify an option with the same name), they are resolved in favor of
+the parent argp parsers, or earlier argp parsers in the list of children.
+
+@comment argp.h
+@comment GNU
+@deftp {Data Type} {struct argp_child}
+An entry in the list of subsidiary argp parsers pointed to by the
+@code{children} field in a @code{struct argp}. The fields are as follows:
+
+@table @code
+@item const struct argp *argp
+The child argp parser, or zero to end the list.
+
+@item int flags
+Flags for this child.
+
+@item const char *header
+If non-zero, an optional header to be printed in 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 @code{""}. As with header
+strings specified in an option entry, the value conventionally has
+@samp{:} as the last character. @xref{Argp Option Vectors}.
+
+@item int group
+Where to group the child options relative to the other (`consolidated')
+options in the parent argp parser. The values are the same as the
+@code{group} field in @code{struct argp_option} (@pxref{Argp Option
+Vectors}), but all child-groupings follow parent options at a particular
+group level. If both this field and @code{header} are zero, then the
+child's options aren't grouped together at all, but rather merged with
+the parent options (merging the child's grouping levels with the
+parents).
+@end table
+@end deftp
+
+@node Argp Flags, Argp Help, Argp Parsers, Argp
+@subsection Flags for @code{argp_parse}
+
+The default behavior of @code{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
+@var{flags} argument to @code{argp_parse}:
+
+@vtable @code
+@comment argp.h
+@comment GNU
+@item ARGP_PARSE_ARGV0
+Don't ignore the first element of the @var{argv} argument to
+@code{argp_parse}. Normally (and always unless @code{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.
+
+@comment argp.h
+@comment GNU
+@item ARGP_NO_ERRS
+Don't print error messages for unknown options to @code{stderr}; unless
+this flag is set, @code{ARGP_PARSE_ARGV0} is ignored, as @code{argv[0]}
+is used as the program name in the error messages. This flag implies
+@code{ARGP_NO_EXIT} (on the assumption that silent exiting upon errors
+is bad behaviour).
+
+@comment argp.h
+@comment GNU
+@item ARGP_NO_ARGS
+Don't parse any non-option args. Normally non-option args are parsed by
+calling the parse functions with a key of @code{ARGP_KEY_ARG}, and the
+actual arg as the value. This flag needn't normally be set, as the
+normal behavior is to stop parsing as soon as some argument isn't
+accepted by a parsing function. @xref{Argp Parser Functions}.
+
+@comment argp.h
+@comment GNU
+@item 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
+
+@comment argp.h
+@comment GNU
+@item ARGP_NO_HELP
+Don't provide the standard long option @samp{--help}, which ordinarily
+causes usage and option help information to be output to @code{stdout},
+and @code{exit (0)} called.
+
+@comment argp.h
+@comment GNU
+@item ARGP_NO_EXIT
+Don't exit on errors (they may still result in error messages).
+
+@comment argp.h
+@comment GNU
+@item ARGP_LONG_ONLY
+Use the gnu getopt `long-only' rules for parsing arguments.
+
+@comment argp.h
+@comment GNU
+@item ARGP_SILENT
+Turns off any message-printing/exiting options, specifically
+@code{ARGP_NO_EXIT}, @code{ARGP_NO_ERRS}, and @code{ARGP_NO_HELP}.
+@end vtable
+
+@node Argp Help Filtering, , Argp Children, Argp Parsers
+@need 2000
+@subsection Customizing Argp Help Output
+
+The @code{help_filter} field in a a @code{struct argp} is a pointer to a
+function to filter the text of help messages before displaying them.
+They have a function signature like:
+
+@smallexample
+char *@var{help-filter} (int @var{key}, const char *@var{text}, void *@var{input})
+@end smallexample
+
+@noindent
+where @var{key} is either a key from an option, in which case @var{text}
+is that option's help text (@pxref{Argp Option Vectors}), or one of the
+special keys with names beginning with @samp{ARGP_KEY_HELP_}, describing
+which other help text @var{text} is (@pxref{Argp Help Filter Keys}).
+
+The function should return either @var{text}, if it should be used
+as-is, a replacement string, which should be allocated using
+@code{malloc}, and will be freed by argp, or zero, meaning `print
+nothing'. The value of @var{text} supplied is @emph{after} any
+translation has been done, so if any of the replacement text also needs
+translation, that should be done by the filter function. @var{input} is
+either the input supplied to @code{argp_parse}, or zero, if
+@code{argp_help} was called directly by the user.
+
+@menu
+* Keys: Argp Help Filter Keys. Special @var{key} values for help filter functions.
+@end menu
+
+@node Argp Help Filter Keys, , , Argp Help Filtering
+@subsubsection 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, and specify which help text the @var{text} argument contains:
+
+@vtable @code
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_HELP_PRE_DOC
+Help text preceding options.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_HELP_POST_DOC
+Help text following options.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_HELP_HEADER
+Option header string.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_HELP_EXTRA
+After all other documentation; @var{text} is zero for this key.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_HELP_DUP_ARGS_NOTE
+The explanatory note emitted when duplicate option arguments have been
+suppressed.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_HELP_ARGS_DOC
+The argument doc string (the @code{args_doc} field from the argp parser;
+@pxref{Argp Parsers}).
+@end vtable
+
+@node Argp Help, Argp Examples, Argp Flags, Argp
+@subsection The @code{argp_help} Function
+
+Normally programs using argp need not worry too much about printing
+argument-usage-type help messages, because the standard @samp{--help}
+option is handled automatically by argp, and the typical error cases can
+be handled using @code{argp_usage} and @code{argp_error} (@pxref{Argp
+Helper Functions}).
+
+However, if it's desirable to print a standard help message in some
+context other than parsing the program options, argp offers the
+@code{argp_help} interface.
+
+@comment argp.h
+@comment GNU
+@deftypefun void argp_help (const struct argp *@var{argp}, @w{FILE *@var{stream}}, @w{unsigned @var{flags}}, @w{char *@var{name}})
+Output a help message for the argp parser @var{argp} to @var{stream}.
+What sort of messages is printed is determined by @var{flags}.
+
+Any options such as @samp{--help} that are implemented automatically by
+argp itself will @emph{not} be present in the help output; for this
+reason, it is better to use @code{argp_state_help} if calling from
+within an argp parser function. @xref{Argp Helper Functions}.
+@end deftypefun
+
+@menu
+* Flags: Argp Help Flags. Specifying what sort of help message to print.
+@end menu
+
+@node Argp Help Flags, , , Argp Help
+@subsection Flags for the @code{argp_help} Function
+
+When calling @code{argp_help} (@pxref{Argp Help}), or
+@code{argp_state_help} (@pxref{Argp Helper Functions}), exactly what is
+output is determined by the @var{flags} argument, which should consist
+of any of the following flags, or'd together:
+
+@vtable @code
+@item ARGP_HELP_USAGE
+A unix @samp{Usage:} message that explicitly lists all options.
+
+@item ARGP_HELP_SHORT_USAGE
+A unix @samp{Usage:} message that displays only an appropriate
+placeholder to indicate where the options go; useful for showing
+the non-option argument syntax.
+
+@item ARGP_HELP_SEE
+A @samp{Try @dots{} for more help} message; @samp{@dots{}} contains the
+program name and @samp{--help}.
+
+@item ARGP_HELP_LONG
+A verbose option help message that gives each option understood along
+with its documentation string.
+
+@item ARGP_HELP_PRE_DOC
+The part of the argp parser doc string that precedes the verbose option help.
+
+@item ARGP_HELP_POST_DOC
+The part of the argp parser doc string that follows the verbose option help.
+
+@item ARGP_HELP_DOC
+@code{(ARGP_HELP_PRE_DOC | ARGP_HELP_POST_DOC)}
+
+@item ARGP_HELP_BUG_ADDR
+A message saying where to report bugs for this program, if the
+@code{argp_program_bug_address} variable contains one.
+
+@item ARGP_HELP_LONG_ONLY
+Modify any output appropriately to reflect @code{ARGP_LONG_ONLY} mode.
+@end vtable
+
+The following flags are only understood when used with
+@code{argp_state_help}, and control whether the function returns after
+printing its output, or terminates the program:
+
+@vtable @code
+@item ARGP_HELP_EXIT_ERR
+Terminate the program with @code{exit (argp_err_exit_status)}.
+
+@item ARGP_HELP_EXIT_OK
+Terminate the program with @code{exit (0)}.
+@end vtable
+
+The following flags are combinations of the basic ones for printing
+standard messages:
+
+@vtable @code
+@item ARGP_HELP_STD_ERR
+Assuming an error message for a parsing error has already printed,
+prints a note on how to get help, and terminates the program with an
+error.
+
+@item ARGP_HELP_STD_USAGE
+Prints a standard usage message and terminates the program with an
+error. This is used when no more specific error message is appropriate.
+
+@item ARGP_HELP_STD_HELP
+Prints the standard response for a @samp{--help} option, and terminates
+the program successfully.
+@end vtable
+
+@node Argp Examples, Argp User Customization, Argp Help, Argp
+@subsection Argp Examples
+
+These example programs demonstrate the basic usage of argp.
+
+@menu
+* 1: Argp Example 1. A minimal program using argp.
+* 2: Argp Example 2. A program using only default options.
+* 3: Argp Example 3. A simple program with user options.
+* 4: Argp Example 4. Combining multiple argp parsers.
+@end menu
+
+@node Argp Example 1, Argp Example 2, , Argp Examples
+@subsubsection 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) message for @samp{--help}.
+
+@smallexample
+@include argp-ex1.c.texi
+@end smallexample
+
+@node Argp Example 2, Argp Example 3, Argp Example 1, Argp Examples
+@subsubsection A Program Using Argp with Only Default Options
+
+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
+@samp{--help} option, this example will have a @samp{--version} option,
+and will put the given documentation string and bug address in the
+@samp{--help} output, as per GNU standards.
+
+The variable @code{argp} contains the argument parser specification;
+adding fields to this structure is the way most parameters are passed to
+@code{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, @code{argp_program_version} and
+@code{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).
+
+@smallexample
+@include argp-ex2.c.texi
+@end smallexample
+
+@node Argp Example 3, Argp Example 4, Argp Example 2, Argp Examples
+@subsubsection A Program Using Argp with User Options
+
+This program uses the same features as example 2, and adds user options
+and arguments.
+
+We now use the first four fields in @code{argp} (@pxref{Argp Parsers}),
+and specifies @code{parse_opt} as the parser function (@pxref{Argp
+Parser Functions}).
+
+Note that in this example, @code{main} uses a structure to communicate
+with the @code{parse_opt} function, a pointer to which it passes in the
+@code{input} argument to @code{argp_parse} (@pxref{Argp}), and is
+retrieved by @code{parse_opt} through the @code{input} field in its
+@code{state} argument (@pxref{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.
+
+@smallexample
+@include argp-ex3.c.texi
+@end smallexample
+
+@node Argp Example 4, , Argp Example 3, Argp Examples
+@subsubsection A Program Using Multiple Combined Argp Parsers
+
+This program uses the same features as example 3, but has more options,
+and somewhat more structure in the @samp{--help} output. It also shows
+how you can `steal' the remainder of the input arguments past a certain
+point, for programs that accept a list of items, and the special
+@var{key} value @code{ARGP_KEY_NO_ARGS}, which is only given if no
+non-option arguments were supplied to the program (@pxref{Argp Special
+Keys}).
+
+For structuring the help output, two features are used: @emph{headers},
+which are entries in the options vector (@pxref{Argp Option Vectors})
+with the first four fields being zero, and a two part documentation
+string (in the variable @code{doc}), which allows documentation both
+before and after the options (@pxref{Argp Parsers}); the
+two parts of @code{doc} are separated by a vertical-tab character
+(@code{'\v'}, or @code{'\013'}). By convention, the documentation
+before the options is just a short string saying what the program does,
+and that afterwards is longer, describing the behavior in more detail.
+All documentation strings are automatically filled for output, although
+newlines may be included to force a line break at a particular point.
+All documentation strings are also passed to the @code{gettext}
+function, for possible translation into the current locale.
+
+@smallexample
+@include argp-ex4.c.texi
+@end smallexample
+
+@node Argp User Customization, , Argp Examples, Argp
+@subsection Argp User Customization
+
+@cindex ARGP_HELP_FMT environment variable
+The way formatting of argp @samp{--help} output may be controlled to
+some extent by a program's users, by setting the @code{ARGP_HELP_FMT}
+environment variable to a comma-separated list (whitespace is ignored)
+of the following tokens:
+
+@table @samp
+@item dup-args
+@itemx no-dup-args
+Turn @dfn{duplicate-argument-mode} on or off. In duplicate argument
+mode, if an option which accepts an argument has multiple names, the
+argument is shown for each name; otherwise, it is only shown for the
+first long option, and a note is emitted later so the user knows that it
+applies to the other names as well. The default is @samp{no-dup-args},
+which is less consistent, but prettier.
+
+@item dup-args-note
+@item no-dup-args-note
+Enable or disable the note informing the user of suppressed option
+argument duplication. The default is @samp{dup-args-note}.
+
+@item short-opt-col=@var{n}
+Show the first short option in column @var{n} (default 2).
+
+@item long-opt-col=@var{n}
+Show the first long option in column @var{n} (default 6).
+
+@item doc-opt-col=@var{n}
+Show `documentation options' (@pxref{Argp Option Flags}) in column
+@var{n} (default 2).
+
+@item opt-doc-col=@var{n}
+Show the documentation for options starting in column @var{n} (default 29).
+
+@item header-col=@var{n}
+Indent group headers (which document groups of options) to column
+@var{n} (default 1).
+
+@item usage-indent=@var{n}
+Indent continuation lines in @samp{Usage:} messages to column @var{n}
+(default 12).
+
+@item rmargin=@var{n}
+Word wrap help output at or before column @var{n} (default 79).
+@end table
--- /dev/null
+@node Getopt, Argp, , Parsing Program Arguments
+@section Parsing program options using @code{getopt}
+
+The @code{getopt} and @code{getopt_long} functions automate some of the
+chore involved in parsing typical unix command line options.
+
+@menu
+* Using Getopt:: Using the @code{getopt} function.
+* Example of Getopt:: An example of parsing options with @code{getopt}.
+* Getopt Long Options:: GNU suggests utilities accept long-named
+ options; here is one way to do.
+* Getopt Long Option Example:: An example of using @code{getopt_long}.
+@end menu
+
+@node Using Getopt, Example of Getopt, , Getopt
+@subsection Using the @code{getopt} function
+
+Here are the details about how to call the @code{getopt} function. To
+use this facility, your program must include the header file
+@file{unistd.h}.
+@pindex unistd.h
+
+@comment unistd.h
+@comment POSIX.2
+@deftypevar int opterr
+If the value of this variable is nonzero, then @code{getopt} prints an
+error message to the standard error stream if it encounters an unknown
+option character or an option with a missing required argument. This is
+the default behavior. If you set this variable to zero, @code{getopt}
+does not print any messages, but it still returns the character @code{?}
+to indicate an error.
+@end deftypevar
+
+@comment unistd.h
+@comment POSIX.2
+@deftypevar int optopt
+When @code{getopt} encounters an unknown option character or an option
+with a missing required argument, it stores that option character in
+this variable. You can use this for providing your own diagnostic
+messages.
+@end deftypevar
+
+@comment unistd.h
+@comment POSIX.2
+@deftypevar int optind
+This variable is set by @code{getopt} to the index of the next element
+of the @var{argv} array to be processed. Once @code{getopt} has found
+all of the option arguments, you can use this variable to determine
+where the remaining non-option arguments begin. The initial value of
+this variable is @code{1}.
+@end deftypevar
+
+@comment unistd.h
+@comment POSIX.2
+@deftypevar {char *} optarg
+This variable is set by @code{getopt} to point at the value of the
+option argument, for those options that accept arguments.
+@end deftypevar
+
+@comment unistd.h
+@comment POSIX.2
+@deftypefun int getopt (int @var{argc}, char **@var{argv}, const char *@var{options})
+The @code{getopt} function gets the next option argument from the
+argument list specified by the @var{argv} and @var{argc} arguments.
+Normally these values come directly from the arguments received by
+@code{main}.
+
+The @var{options} argument is a string that specifies the option
+characters that are valid for this program. An option character in this
+string can be followed by a colon (@samp{:}) to indicate that it takes a
+required argument.
+
+If the @var{options} argument string begins with a hyphen (@samp{-}), this
+is treated specially. It permits arguments that are not options to be
+returned as if they were associated with option character @samp{\0}.
+
+The @code{getopt} function returns the option character for the next
+command line option. When no more option arguments are available, it
+returns @code{-1}. There may still be more non-option arguments; you
+must compare the external variable @code{optind} against the @var{argc}
+parameter to check this.
+
+If the option has an argument, @code{getopt} returns the argument by
+storing it in the variable @var{optarg}. You don't ordinarily need to
+copy the @code{optarg} string, since it is a pointer into the original
+@var{argv} array, not into a static area that might be overwritten.
+
+If @code{getopt} finds an option character in @var{argv} that was not
+included in @var{options}, or a missing option argument, it returns
+@samp{?} and sets the external variable @code{optopt} to the actual
+option character. If the first character of @var{options} is a colon
+(@samp{:}), then @code{getopt} returns @samp{:} instead of @samp{?} to
+indicate a missing option argument. In addition, if the external
+variable @code{opterr} is nonzero (which is the default), @code{getopt}
+prints an error message.
+@end deftypefun
+
+@node Example of Getopt
+@subsection Example of Parsing Arguments with @code{getopt}
+
+Here is an example showing how @code{getopt} is typically used. The
+key points to notice are:
+
+@itemize @bullet
+@item
+Normally, @code{getopt} is called in a loop. When @code{getopt} returns
+@code{-1}, indicating no more options are present, the loop terminates.
+
+@item
+A @code{switch} statement is used to dispatch on the return value from
+@code{getopt}. In typical use, each case just sets a variable that
+is used later in the program.
+
+@item
+A second loop is used to process the remaining non-option arguments.
+@end itemize
+
+@smallexample
+@include testopt.c.texi
+@end smallexample
+
+Here are some examples showing what this program prints with different
+combinations of arguments:
+
+@smallexample
+% testopt
+aflag = 0, bflag = 0, cvalue = (null)
+
+% testopt -a -b
+aflag = 1, bflag = 1, cvalue = (null)
+
+% testopt -ab
+aflag = 1, bflag = 1, cvalue = (null)
+
+% testopt -c foo
+aflag = 0, bflag = 0, cvalue = foo
+
+% testopt -cfoo
+aflag = 0, bflag = 0, cvalue = foo
+
+% testopt arg1
+aflag = 0, bflag = 0, cvalue = (null)
+Non-option argument arg1
+
+% testopt -a arg1
+aflag = 1, bflag = 0, cvalue = (null)
+Non-option argument arg1
+
+% testopt -c foo arg1
+aflag = 0, bflag = 0, cvalue = foo
+Non-option argument arg1
+
+% testopt -a -- -b
+aflag = 1, bflag = 0, cvalue = (null)
+Non-option argument -b
+
+% testopt -a -
+aflag = 1, bflag = 0, cvalue = (null)
+Non-option argument -
+@end smallexample
+
+@node Getopt Long Options
+@subsection Parsing Long Options with @code{getopt_long}
+
+To accept GNU-style long options as well as single-character options,
+use @code{getopt_long} instead of @code{getopt}. This function is
+declared in @file{getopt.h}, not @file{unistd.h}. You should make every
+program accept long options if it uses any options, for this takes
+little extra work and helps beginners remember how to use the program.
+
+@comment getopt.h
+@comment GNU
+@deftp {Data Type} {struct option}
+This structure describes a single long option name for the sake of
+@code{getopt_long}. The argument @var{longopts} must be an array of
+these structures, one for each long option. Terminate the array with an
+element containing all zeros.
+
+The @code{struct option} structure has these fields:
+
+@table @code
+@item const char *name
+This field is the name of the option. It is a string.
+
+@item int has_arg
+This field says whether the option takes an argument. It is an integer,
+and there are three legitimate values: @w{@code{no_argument}},
+@code{required_argument} and @code{optional_argument}.
+
+@item int *flag
+@itemx int val
+These fields control how to report or act on the option when it occurs.
+
+If @code{flag} is a null pointer, then the @code{val} is a value which
+identifies this option. Often these values are chosen to uniquely
+identify particular long options.
+
+If @code{flag} is not a null pointer, it should be the address of an
+@code{int} variable which is the flag for this option. The value in
+@code{val} is the value to store in the flag to indicate that the option
+was seen.
+@end table
+@end deftp
+
+@comment getopt.h
+@comment GNU
+@deftypefun int getopt_long (int @var{argc}, char **@var{argv}, const char *@var{shortopts}, struct option *@var{longopts}, int *@var{indexptr})
+Decode options from the vector @var{argv} (whose length is @var{argc}).
+The argument @var{shortopts} describes the short options to accept, just as
+it does in @code{getopt}. The argument @var{longopts} describes the long
+options to accept (see above).
+
+When @code{getopt_long} encounters a short option, it does the same
+thing that @code{getopt} would do: it returns the character code for the
+option, and stores the options argument (if it has one) in @code{optarg}.
+
+When @code{getopt_long} encounters a long option, it takes actions based
+on the @code{flag} and @code{val} fields of the definition of that
+option.
+
+If @code{flag} is a null pointer, then @code{getopt_long} returns the
+contents of @code{val} to indicate which option it found. You should
+arrange distinct values in the @code{val} field for options with
+different meanings, so you can decode these values after
+@code{getopt_long} returns. If the long option is equivalent to a short
+option, you can use the short option's character code in @code{val}.
+
+If @code{flag} is not a null pointer, that means this option should just
+set a flag in the program. The flag is a variable of type @code{int}
+that you define. Put the address of the flag in the @code{flag} field.
+Put in the @code{val} field the value you would like this option to
+store in the flag. In this case, @code{getopt_long} returns @code{0}.
+
+For any long option, @code{getopt_long} tells you the index in the array
+@var{longopts} of the options definition, by storing it into
+@code{*@var{indexptr}}. You can get the name of the option with
+@code{@var{longopts}[*@var{indexptr}].name}. So you can distinguish among
+long options either by the values in their @code{val} fields or by their
+indices. You can also distinguish in this way among long options that
+set flags.
+
+When a long option has an argument, @code{getopt_long} puts the argument
+value in the variable @code{optarg} before returning. When the option
+has no argument, the value in @code{optarg} is a null pointer. This is
+how you can tell whether an optional argument was supplied.
+
+When @code{getopt_long} has no more options to handle, it returns
+@code{-1}, and leaves in the variable @code{optind} the index in
+@var{argv} of the next remaining argument.
+@end deftypefun
+
+@node Getopt Long Option Example
+@subsection Example of Parsing Long Options with @code{getopt_long}
+
+@smallexample
+@include longopt.c.texi
+@end smallexample
For the command @samp{cat foo bar}, @var{argc} is 3 and @var{argv} has
three elements, @code{"cat"}, @code{"foo"} and @code{"bar"}.
-If the syntax for the command line arguments to your program is simple
-enough, you can simply pick the arguments off from @var{argv} by hand.
-But unless your program takes a fixed number of arguments, or all of the
-arguments are interpreted in the same way (as file names, for example),
-you are usually better off using @code{getopt} to do the parsing.
-
In Unix systems you can define @code{main} a third way, using three arguments:
@smallexample
@menu
* Argument Syntax:: By convention, options start with a hyphen.
-* Parsing Options:: The @code{getopt} function.
-* Example of Getopt:: An example of parsing options with @code{getopt}.
-* Long Options:: GNU suggests utilities accept long-named options.
- Here is how to do that.
-* Long Option Example:: An example of using @code{getopt_long}.
-* Suboptions:: Some programs need more detailed options.
-* Suboptions Example:: This shows how it could be done for @code{mount}.
+* Parsing Program Arguments:: Ways to parse program options and arguments.
@end menu
@node Argument Syntax
@cindex command argument syntax
POSIX recommends these conventions for command line arguments.
-@code{getopt} (@pxref{Parsing Options}) makes it easy to implement them.
+@code{getopt} (@pxref{Getopt}) and @code{argp_parse} (@pxref{Argp}) make
+it easy to implement them.
@itemize @bullet
@item
@item
Options typically precede other non-option arguments.
-The implementation of @code{getopt} in the GNU C library normally makes
-it appear as if all the option arguments were specified before all the
-non-option arguments for the purposes of parsing, even if the user of
-your program intermixed option and non-option arguments. It does this
-by reordering the elements of the @var{argv} array. This behavior is
-nonstandard; if you want to suppress it, define the
-@code{_POSIX_OPTION_ORDER} environment variable. @xref{Standard
-Environment}.
+The implementations of @code{getopt} and @code{argp_parse} in the GNU C
+library normally make it appear as if all the option arguments were
+specified before all the non-option arguments for the purposes of
+parsing, even if the user of your program intermixed option and
+non-option arguments. They do this by reordering the elements of the
+@var{argv} array. This behavior is nonstandard; if you want to suppress
+it, define the @code{_POSIX_OPTION_ORDER} environment variable.
+@xref{Standard Environment}.
@item
The argument @samp{--} terminates all options; any following arguments
Eventually, the GNU system will provide completion for long option names
in the shell.
-@node Parsing Options
-@subsection Parsing Program Options
+@node Parsing Program Arguments
+@subsection Parsing Program Arguments
+
@cindex program arguments, parsing
@cindex command arguments, parsing
@cindex parsing program arguments
+If the syntax for the command line arguments to your program is simple
+enough, you can simply pick the arguments off from @var{argv} by hand.
+But unless your program takes a fixed number of arguments, or all of the
+arguments are interpreted in the same way (as file names, for example),
+you are usually better off using @code{getopt} (@pxref{Getopt}) or
+@code{argp_parse} (@pxref{Argp}) to do the parsing.
-Here are the details about how to call the @code{getopt} function. To
-use this facility, your program must include the header file
-@file{unistd.h}.
-@pindex unistd.h
-
-@comment unistd.h
-@comment POSIX.2
-@deftypevar int opterr
-If the value of this variable is nonzero, then @code{getopt} prints an
-error message to the standard error stream if it encounters an unknown
-option character or an option with a missing required argument. This is
-the default behavior. If you set this variable to zero, @code{getopt}
-does not print any messages, but it still returns the character @code{?}
-to indicate an error.
-@end deftypevar
-
-@comment unistd.h
-@comment POSIX.2
-@deftypevar int optopt
-When @code{getopt} encounters an unknown option character or an option
-with a missing required argument, it stores that option character in
-this variable. You can use this for providing your own diagnostic
-messages.
-@end deftypevar
-
-@comment unistd.h
-@comment POSIX.2
-@deftypevar int optind
-This variable is set by @code{getopt} to the index of the next element
-of the @var{argv} array to be processed. Once @code{getopt} has found
-all of the option arguments, you can use this variable to determine
-where the remaining non-option arguments begin. The initial value of
-this variable is @code{1}.
-@end deftypevar
-
-@comment unistd.h
-@comment POSIX.2
-@deftypevar {char *} optarg
-This variable is set by @code{getopt} to point at the value of the
-option argument, for those options that accept arguments.
-@end deftypevar
-
-@comment unistd.h
-@comment POSIX.2
-@deftypefun int getopt (int @var{argc}, char **@var{argv}, const char *@var{options})
-The @code{getopt} function gets the next option argument from the
-argument list specified by the @var{argv} and @var{argc} arguments.
-Normally these values come directly from the arguments received by
-@code{main}.
-
-The @var{options} argument is a string that specifies the option
-characters that are valid for this program. An option character in this
-string can be followed by a colon (@samp{:}) to indicate that it takes a
-required argument.
-
-If the @var{options} argument string begins with a hyphen (@samp{-}), this
-is treated specially. It permits arguments that are not options to be
-returned as if they were associated with option character @samp{\0}.
-
-The @code{getopt} function returns the option character for the next
-command line option. When no more option arguments are available, it
-returns @code{-1}. There may still be more non-option arguments; you
-must compare the external variable @code{optind} against the @var{argc}
-parameter to check this.
-
-If the option has an argument, @code{getopt} returns the argument by
-storing it in the variable @var{optarg}. You don't ordinarily need to
-copy the @code{optarg} string, since it is a pointer into the original
-@var{argv} array, not into a static area that might be overwritten.
-
-If @code{getopt} finds an option character in @var{argv} that was not
-included in @var{options}, or a missing option argument, it returns
-@samp{?} and sets the external variable @code{optopt} to the actual
-option character. If the first character of @var{options} is a colon
-(@samp{:}), then @code{getopt} returns @samp{:} instead of @samp{?} to
-indicate a missing option argument. In addition, if the external
-variable @code{opterr} is nonzero (which is the default), @code{getopt}
-prints an error message.
-@end deftypefun
-
-@node Example of Getopt
-@subsection Example of Parsing Arguments with @code{getopt}
-
-Here is an example showing how @code{getopt} is typically used. The
-key points to notice are:
-
-@itemize @bullet
-@item
-Normally, @code{getopt} is called in a loop. When @code{getopt} returns
-@code{-1}, indicating no more options are present, the loop terminates.
-
-@item
-A @code{switch} statement is used to dispatch on the return value from
-@code{getopt}. In typical use, each case just sets a variable that
-is used later in the program.
-
-@item
-A second loop is used to process the remaining non-option arguments.
-@end itemize
-
-@smallexample
-@include testopt.c.texi
-@end smallexample
-
-Here are some examples showing what this program prints with different
-combinations of arguments:
-
-@smallexample
-% testopt
-aflag = 0, bflag = 0, cvalue = (null)
-
-% testopt -a -b
-aflag = 1, bflag = 1, cvalue = (null)
-
-% testopt -ab
-aflag = 1, bflag = 1, cvalue = (null)
-
-% testopt -c foo
-aflag = 0, bflag = 0, cvalue = foo
-
-% testopt -cfoo
-aflag = 0, bflag = 0, cvalue = foo
-
-% testopt arg1
-aflag = 0, bflag = 0, cvalue = (null)
-Non-option argument arg1
-
-% testopt -a arg1
-aflag = 1, bflag = 0, cvalue = (null)
-Non-option argument arg1
-
-% testopt -c foo arg1
-aflag = 0, bflag = 0, cvalue = foo
-Non-option argument arg1
-
-% testopt -a -- -b
-aflag = 1, bflag = 0, cvalue = (null)
-Non-option argument -b
-
-% testopt -a -
-aflag = 1, bflag = 0, cvalue = (null)
-Non-option argument -
-@end smallexample
-
-@node Long Options
-@subsection Parsing Long Options
-
-To accept GNU-style long options as well as single-character options,
-use @code{getopt_long} instead of @code{getopt}. This function is
-declared in @file{getopt.h}, not @file{unistd.h}. You should make every
-program accept long options if it uses any options, for this takes
-little extra work and helps beginners remember how to use the program.
-
-@comment getopt.h
-@comment GNU
-@deftp {Data Type} {struct option}
-This structure describes a single long option name for the sake of
-@code{getopt_long}. The argument @var{longopts} must be an array of
-these structures, one for each long option. Terminate the array with an
-element containing all zeros.
-
-The @code{struct option} structure has these fields:
+@code{getopt} is more standard (the short-option only version of it is a
+part of the POSIX standard), but using @code{argp_parse} is often
+easier, both for very simple and very complex option structures, because
+it does more of the dirty work for you.
-@table @code
-@item const char *name
-This field is the name of the option. It is a string.
-
-@item int has_arg
-This field says whether the option takes an argument. It is an integer,
-and there are three legitimate values: @w{@code{no_argument}},
-@code{required_argument} and @code{optional_argument}.
-
-@item int *flag
-@itemx int val
-These fields control how to report or act on the option when it occurs.
-
-If @code{flag} is a null pointer, then the @code{val} is a value which
-identifies this option. Often these values are chosen to uniquely
-identify particular long options.
-
-If @code{flag} is not a null pointer, it should be the address of an
-@code{int} variable which is the flag for this option. The value in
-@code{val} is the value to store in the flag to indicate that the option
-was seen.
-@end table
-@end deftp
-
-@comment getopt.h
-@comment GNU
-@deftypefun int getopt_long (int @var{argc}, char **@var{argv}, const char *@var{shortopts}, struct option *@var{longopts}, int *@var{indexptr})
-Decode options from the vector @var{argv} (whose length is @var{argc}).
-The argument @var{shortopts} describes the short options to accept, just as
-it does in @code{getopt}. The argument @var{longopts} describes the long
-options to accept (see above).
-
-When @code{getopt_long} encounters a short option, it does the same
-thing that @code{getopt} would do: it returns the character code for the
-option, and stores the options argument (if it has one) in @code{optarg}.
-
-When @code{getopt_long} encounters a long option, it takes actions based
-on the @code{flag} and @code{val} fields of the definition of that
-option.
-
-If @code{flag} is a null pointer, then @code{getopt_long} returns the
-contents of @code{val} to indicate which option it found. You should
-arrange distinct values in the @code{val} field for options with
-different meanings, so you can decode these values after
-@code{getopt_long} returns. If the long option is equivalent to a short
-option, you can use the short option's character code in @code{val}.
-
-If @code{flag} is not a null pointer, that means this option should just
-set a flag in the program. The flag is a variable of type @code{int}
-that you define. Put the address of the flag in the @code{flag} field.
-Put in the @code{val} field the value you would like this option to
-store in the flag. In this case, @code{getopt_long} returns @code{0}.
-
-For any long option, @code{getopt_long} tells you the index in the array
-@var{longopts} of the options definition, by storing it into
-@code{*@var{indexptr}}. You can get the name of the option with
-@code{@var{longopts}[*@var{indexptr}].name}. So you can distinguish among
-long options either by the values in their @code{val} fields or by their
-indices. You can also distinguish in this way among long options that
-set flags.
-
-When a long option has an argument, @code{getopt_long} puts the argument
-value in the variable @code{optarg} before returning. When the option
-has no argument, the value in @code{optarg} is a null pointer. This is
-how you can tell whether an optional argument was supplied.
-
-When @code{getopt_long} has no more options to handle, it returns
-@code{-1}, and leaves in the variable @code{optind} the index in
-@var{argv} of the next remaining argument.
-@end deftypefun
+@menu
+* Getopt:: Parsing program options using @code{getopt}.
+* Argp:: Parsing program options using @code{argp_parse}.
+* Suboptions:: Some programs need more detailed options.
+* Suboptions Example:: This shows how it could be done for @code{mount}.
+@end menu
-@node Long Option Example
-@subsection Example of Parsing Long Options
+@c Getopt and argp start at the @section level so that there's
+@c enough room for their internal hierarchy (mostly a problem with
+@c argp). -Miles
-@smallexample
-@include longopt.c.texi
-@end smallexample
+@include getopt.texi
+@include argp.texi
-@node Suboptions
-@subsection Parsing of Suboptions
+@node Suboptions, Suboptions Example, Argp, Parsing Program Arguments
+@c This is a @section so that it's at the same level as getopt and argp
+@section Parsing of Suboptions
Having a single level of options is sometimes not enough. There might
be too many options which have to be available or a set of options is
function is @samp{-1}.
@end deftypefun
-@node Suboptions Example
+@node Suboptions Example, , Suboptions, Parsing Program Arguments
@subsection Parsing of Suboptions Example
The code which might appear in the @code{mount}(8) program is a perfect
@cindex _POSIX_OPTION_ORDER environment variable.
If this environment variable is defined, it suppresses the usual
-reordering of command line arguments by @code{getopt}. @xref{Argument Syntax}.
+reordering of command line arguments by @code{getopt} and
+@code{argp_parse}. @xref{Argument Syntax}.
@c !!! GNU also has COREFILE, CORESERVER, EXECSERVERS
@end table
projects / external / glibc.git / commitdiff