1997-06-05 13:28:54 +02:00
|
|
|
@ignore
|
|
|
|
Documentation for the argp argument parser
|
|
|
|
|
2000-04-15 21:38:00 +02:00
|
|
|
Copyright (C) 1995, 1996, 1997, 1998, 2000 Free Software Foundation, Inc.
|
1997-06-05 13:28:54 +02:00
|
|
|
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
|
1998-06-11 16:56:10 +02:00
|
|
|
@deftypefun {error_t} argp_parse (const struct argp *@var{argp}, int @var{argc}, char **@var{argv}, unsigned @var{flags}, int *@var{arg_index}, void *@var{input})
|
1998-06-15 20:12:05 +02:00
|
|
|
The @code{argp_parse} function parses the arguments in @var{argv}, of
|
1997-06-05 13:28:54 +02:00
|
|
|
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}.
|
|
|
|
|
2000-04-18 08:24:03 +02:00
|
|
|
If @var{arg_index} is non-null, the index of the first unparsed option
|
2000-04-15 21:38:00 +02:00
|
|
|
in @var{argv} is returned in it.
|
|
|
|
|
2000-04-18 08:24:03 +02:00
|
|
|
The return value is zero for successful parsing, or an error code
|
1997-06-05 13:28:54 +02:00
|
|
|
(@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,
|
1999-08-27 21:06:58 +02:00
|
|
|
@code{argp_program_bug_address} should point to a string that is the
|
1997-06-05 13:28:54 +02:00
|
|
|
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
|
1999-08-27 21:06:58 +02:00
|
|
|
the first are prefixed by @samp{ or: } instead of @samp{Usage:}).
|
1997-06-05 13:28:54 +02:00
|
|
|
|
|
|
|
@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
|
1998-06-15 20:12:05 +02:00
|
|
|
an initialized C variable, only the used fields need be specified in
|
1997-06-05 13:28:54 +02:00
|
|
|
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
|
1997-07-24 03:36:01 +02:00
|
|
|
group, and the groups presented in the order 0, 1, 2, @dots{}, @var{n},
|
|
|
|
@minus{}@var{m}, @dots{}, @minus{}2, @minus{}1. Every entry in an
|
1997-07-07 00:02:42 +02:00
|
|
|
options array with this
|
1997-06-05 13:28:54 +02:00
|
|
|
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
|
1997-07-24 03:36:01 +02:00
|
|
|
@code{key} fields both zero), in which case, the previous entry + 1 is
|
1997-06-05 13:28:54 +02:00
|
|
|
the default. Automagic options such as @samp{--help} are put into group
|
1997-07-24 03:36:01 +02:00
|
|
|
@minus{}1.
|
1997-06-05 13:28:54 +02:00
|
|
|
|
|
|
|
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
|
2000-04-15 21:38:00 +02:00
|
|
|
(@code{@var{key} == ARGP_KEY_ARG}) that they do not wish to handle.
|
1997-06-05 13:28:54 +02:00
|
|
|
@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.
|
|
|
|
|
Update.
1997-06-19 19:38 Ulrich Drepper <drepper@cygnus.com>
* features.h: Define __STDC_IEC_559__ and _STDC_IEC_559_COMPLEX__.
* elf/dl-minimal.c (__dcgettext): Remove assertion.
* inet/rcmd.c: Correct a few typos. Reported by Eric Troan.
* manual/Makefile (distribute): Add dir.
* manual/dir: New file.
* math/Makefile (libm-support): Rename s_rinttol, s_rinttoll,
s_roundtol, and s_roundtoll to s_lrint, s_llrint, s_lround,
and s_llround respectively.
(libm-calls): Add e_gamma_r.
* math/libm-test.c (check_int_exc): New function.
(signbit_test): Remove test for sign of NaN.
(gamma_test): Clear exception after test of existence.
Correct tests and and epsilons.
(lgamma_test): Likewise.
(ilogb_test): Correct all tests.
(scalb_test): Rewrite.
(rinttol_test): Rename to lrint_test and correct tests.
(rinttoll_test): Likewise.
(roundtol_test): Likewise.
(roundtoll_test): Likewise.
(main): Call lrint/lround functions instead of rinttol/roundtol.
* math/math.h: Change prototypes for rinttol/roundtol.
* math/mathcalls.h: Rearrange prototypes according to ISO C9X draft.
* sysdeps/generic/mathbits.h: Define FP_ILOGB0 and FP_ILOGBNAN.
* sysdeps/i386/mathbits.h: Likewise.
* sysdeps/libm-i387/e_scalb.S: Handle special cases correctly.
* sysdeps/libm-i387/e_scalbf.S: Likewise.
* sysdeps/libm-i387/e_scalbl.S: Likewise.
* sysdeps/libm-i387/s_asinh.S: Handle -inf correctly.
* sysdeps/libm-i387/s_asinhf.S: Likewise.
* sysdeps/libm-i387/s_asinhl.S: Likewise.
* sysdeps/libm-i387/s_ilogb.S: Optimize.
* sysdeps/libm-i387/s_ilogbf.S: Likewise.
* sysdeps/libm-i387/s_ilogbl.S: Likewise.
* sysdeps/libm-i387/s_rinttol.S: Rename to...
* sysdeps/libm-i387/s_lrint.S: ...this.
* sysdeps/libm-i387/s_rinttoll.S: Rename to...
* sysdeps/libm-i387/s_llrint.S: ...this.
* sysdeps/libm-i387/s_remquo.S: Correctly set sign of remainder.
* sysdeps/libm-i387/s_remquof.S: Likewise.
* sysdeps/libm-i387/s_remquol.S: Likewise.
* sysdeps/libm-i387/e_gamma_r.c: New file. Implementation of gamma
function according to ISO C.
* sysdeps/libm-i387/e_gammaf_r.c: New file.
* sysdeps/libm-i387/e_gammal_r.c: New file.
* sysdeps/libm-i387/e_lgamma_r.c: Don't let optimize compile the
generation of exceptions away.
* sysdeps/libm-i387/e_lgammaf_r.c: Likewise.
* sysdeps/libm-i387/k_standard.c: Correct return value for infinity
points of gamma function when not SVID mode.
* sysdeps/libm-i387/s_rinttoll.c: Renamed to...
* sysdeps/libm-i387/s_llrint.c: ...this.
* sysdeps/libm-i387/s_rinttol.c: Renamed to...
* sysdeps/libm-i387/s_lrint.c: ...this.
* sysdeps/libm-i387/s_roundtoll.c: Renamed to...
* sysdeps/libm-i387/s_llround.c: ...this.
* sysdeps/libm-i387/s_roundtol.c: Renamed to...
* sysdeps/libm-i387/s_lround.c: ..this.
* sysdeps/libm-i387/s_scalbn.c: Change second parameter according to
ISO C.
* sysdeps/libm-i387/s_scalbnf.c: Likewise.
* sysdeps/libm-i387/s_scalbnl.c: Likewise.
* sysdeps/libm-i387/w_gamma.c: Call __ieee754_gamma_r if library
mode is not _SVID_.
* sysdeps/libm-i387/w_gammaf.c: Likewise.
* sysdeps/libm-i387/w_gammal.c: Likewise.
* sysdeps/m68k/fpu/__math.h: Rename __rinttol to __lrint and
rinttol to lrint.
* sysdeps/m68k/fpu/s_rinttol.c: Renamed to...
* sysdeps/m68k/fpu/s_lrint.c: ...this.
* sysdeps/m68k/fpu/s_rinttoll.c: Renamed to...
* sysdeps/m68k/fpu/s_llrint.c: ...this.
* md5-crypt/Makefile: Link md5test program with md5.o.
* stdio-common/temptest.c: Don't use __stdio_gen_tempname which
is not exported by the libc.so.
* stdio-common/vfscanf.c: Correct scanning of strings after last
change.
* sysdeps/unix/sysv/linux/i386/sysdep.S: Use .comm to define errno.
1997-06-19 07:37 H.J. Lu <hjl@gnu.ai.mit.edu>
* time/tzfile.c (__tzfile_read): Store getc () return in int.
1997-06-13 Miles Bader <miles@gnu.ai.mit.edu>
* argp/argp-parse.c (argp_version_parser): Include `(PROGRAM ERROR)' in
the no-version error text to indicate that something's fucked.
[!_] (N_): New macro.
(argp_default_options, argp_version_options): Wrap doc strings in N_().
1997-06-12 Miles Bader <miles@gnu.ai.mit.edu>
* argp/argp-parse.c (parser_parse_opt): Detect and report unhandled
options here.
(parser_parse_arg): Handle ARGP_KEY_ARGS here.
Adjust NEXT pointer back if we fail to parse anything.
(parser_parse_next): Simplify arg code. Leave state NEXT frobbing
to parser_parse_arg.
1997-06-11 Miles Bader <miles@gnu.ai.mit.edu>
* argp/argp.h (ARGP_KEY_ARGS, ARGP_KEY_FINI): New macros.
* argp/argp-parse.c (parser_finalize): Do another pass over the
parsers with ARGP_KEY_FINI.
1997-06-18 Miles Bader <miles@gnu.ai.mit.edu>
* string/Makefile (routines): Add argz-replace.
1997-06-16 00:16 Miles Bader <miles@gnu.ai.mit.edu>
* manual/string.texi (Argz Functions): Document argz_replace.
1997-06-12 Miles Bader <miles@gnu.ai.mit.edu>
* string/argz.h (__argz_replace, argz_replace): New declarations.
* string/argz-replace.c: New file.
1997-06-11 Miles Bader <miles@gnu.ai.mit.edu>
* manual/argp.texi (Argp Special Keys): Document ARGP_KEY_ARGS.
1997-06-16 23:08 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* Makeconfig (libc-map): Remove definition.
* Makerules (libc-map): Define it here, using the full name.
(load-map-file): Remove case for empty $(..).
($(common-objpfx)libc.so): Revert last change.
1997-06-17 22:18 Mark Kettenis <kettenis@phys.uva.nl>
* login/programs/utmpd.c (main): Improve signal handling.
* login/programs/request.c (do_setutent, do_updwtmp):
Allow arbitrary length filenames.
* login/programs/utmpd.h (setutent_request, updwtmp_request):
Get rid of fixed length file field.
* login/utmp_daemon.c (do_setutent, do_updwtmp):
Allow arbitrary length filenames.
* login/programs/request.c (do_pututline):
Don't fail if connection->position is -1 on entry.
1997-06-15 16:32 Mark Kettenis <kettenis@phys.uva.nl>
* login/utmp_file.c (updwtmp_file): Use the same method for
appending an entry as in pututline_file.
1997-06-11 18:59 Mark Kettenis <kettenis@phys.uva.nl>
* login/utmp_file.c (getutent_r_file):
Use read lock instead of write lock.
(getutline_r_file, internal_getut_r): Lock utmp file.
(updwtmp_file): Use fcntl to lock file instead of flock.
1997-06-18 00:11 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* stdio-common/vfscanf.c (inchar, ungetc): Don't count EOF as
character read in/put back.
* stdio-common/tstscanf.c: Add test case for this.
1997-06-17 22:17 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* libc.map: Add more symbols.
1997-06-18 12:01 Ulrich Drepper <drepper@cygnus.com>
* manual/Makefile (install): Make sure `dir' file exists if we use
install-info.
1997-06-17 19:32 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* manual/Makefile (info): Depend on dir-add.info.
1997-06-17 17:19 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* elf/ldd.bash.in: Fix spacing in message.
1997-06-17 14:28 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* elf/do-rel.h (elf_dynamic_do_rel): Always use version
information if available.
1997-06-17 11:34 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* sunrpc/Makefile ($(rpcsvc:%.x=$(objpfx)rpcsvc/%.h)): Make
command non-empty to force make to recheck modification time.
($(rpcsvc:%.x=$(objpfx)x%.c)): Likewise.
1997-06-17 00:26 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* sysdeps/stub/e_acoshl.c: Set errno to ENOSYS.
* sysdeps/stub/e_acosl.c: Likewise.
* sysdeps/stub/e_asinl.c: Likewise.
* sysdeps/stub/e_atan2l.c: Likewise.
* sysdeps/stub/e_expl.c: Likewise.
* sysdeps/stub/e_fmodl.c: Likewise.
* sysdeps/stub/e_j0l.c: Likewise.
* sysdeps/stub/e_j1l.c: Likewise.
* sysdeps/stub/e_jnl.c: Likewise.
* sysdeps/stub/e_lgammal_r.c: Likewise.
* sysdeps/stub/e_log10l.c: Likewise.
* sysdeps/stub/e_logl.c: Likewise.
* sysdeps/stub/e_powl.c: Likewise.
* sysdeps/stub/e_rem_pio2l.c: Likewise.
* sysdeps/stub/e_sqrtl.c: Likewise.
* sysdeps/stub/k_cosl.c: Likewise.
* sysdeps/stub/k_rem_pio2l.c: Likewise.
* sysdeps/stub/k_sinl.c: Likewise.
* sysdeps/stub/k_tanl.c: Likewise.
* sysdeps/stub/s_atanl.c: Likewise.
* sysdeps/stub/s_erfl.c: Likewise.
* sysdeps/stub/s_exp2.c: Likewise.
* sysdeps/stub/s_exp2f.c: Likewise.
* sysdeps/stub/s_exp2l.c: Likewise.
* sysdeps/stub/s_expm1l.c: Likewise.
* sysdeps/stub/s_log1pl.c: Likewise.
* sysdeps/stub/s_log2l.c: Likewise.
1997-06-18 11:46 Ulrich Drepper <drepper@cygnus.com>
* sysdeps/libm-ieee754/w_gamma.c: If _LIB_VERSION is _SVID_ compute
result as before last change.
* sysdeps/libm-ieee754/w_gammaf.c: Likewise.
* sysdeps/libm-ieee754/w_gammal.c: Likewise.
1997-06-16 23:37 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* sysdeps/libm-ieee754/s_remquo.c: Fix off-by-one when computing
quotient.
* sysdeps/libm-ieee754/s_remquof.c: Likewise.
* sysdeps/libm-ieee754/s_remquol.c: Likewise.
* sysdeps/m68k/fpu/s_remquo.c: Remove FIXME and special case for
quotient.
* sysdeps/libm-ieee754/w_gamma.c: Add missing call to exp
function. Don't use global signgam.
* sysdeps/libm-ieee754/w_gammaf.c: Likewise.
* sysdeps/libm-ieee754/w_gammal.c: Likewise.
* math/Makefile (libm-calls): Remove w_gamma_r.
* sysdeps/libm-ieee754/w_gamma_r.c: Remove file.
* sysdeps/libm-ieee754/w_gammaf_r.c: Remove file.
* sysdeps/libm-ieee754/w_gammal_r.c: Remove file.
* math/libm-test.c (atanh_test): Declare x only if needed.
(signbit_test): Fix typo.
(gamma_test): Check whether function is implemented. Add
epsilons.
(lgamma_test): Likewise.
(fmod_test): Add epsilons.
(exp2_test): Use right function for existence test.
1997-06-07 09:20 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* sysdeps/powerpc/Dist: Add fenv_const.c.
* sysdeps/unix/sysv/linux/Dist: Add net/if_slip.h.
* sysdeps/unix/sysv/linux/powerpc/Dist: Add init-first.h and
syscall.h.
* sysdeps/unix/sysv/linux/sparc/Dist: Add init-first.h.
* string/Makefile (distribute): Add tst-svc.expect.
* nis/Makefile (distribute): Add nis_intern.h and Banner.
* elf/Makefile (distribute): Add dl-hash.h.
* Rules (subdir_echo-distinfo): Add headers from $(distribute).
* login/Makefile (others): Add utmpdump.
* sysdeps/unix/sysv/linux/Makefile (sysdep_headers): Add
net/if_slip.h.
* manual/Makefile (dir-add.texi): Also look in indirectly included
files.
1997-06-16 23:15 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* sysdeps/unix/sysv/linux/configure.in: Remove commands to
generate stdio_lim.h.
* sysdeps/unix/sysv/linux/mk-stdiolim.c: Remove.
* sysdeps/unix/sysv/linux/Makefile: Add rules to generate
stdio_lim.h here.
(common-generated): Add generated files.
(inhibit-stdio_lim): Define.
* sysdeps/posix/Makefile [$(inhibit-stdio_lim)=yes]: Disable rules
to generate stdio_lim.h.
* sysdeps/unix/sysv/linux/Makefile: Suppress inclusion of
dependecy files if no_deps is set.
($(objpfx)syscall-%.d): Add header file as target to dependency
generation.
1997-06-14 19:19 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* sysdeps/unix/sysv/linux/arm/Dist: New file.
1997-06-14 17:59 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* extra-lib.mk (others): Depend on versioned shared library, not
the unversioned one.
* Makerules (build-shlib): Don't make the version link here.
($(common-objpfx)libc.so$(libc.so-version)): New rule for libc
version link.
1997-06-16 03:07 Ulrich Drepper <drepper@cygnus.com>
* sysdeps/libm-ieee754/k_standard.c: Undo change of Tue Aug 6
01:13:56 1996.
* argp/argp-help.c (argp_args_usage): Supply correct argp to
filter_doc.
* argp/argp-help.c (hol_add_cluster): Initialize CL->depth.
* argp/argp-help.c (_help): Supply STATE to argp_args_usage.
* argp/argp.h (ARGP_KEY_HELP_ARGS_DOC): New macro.
* argp/argp-fmtstream.c: Add casts to prevent warnings.
* argp/argp.h (OPTION_NO_USAGE): New macro.
* argp/argp-help.c (usage_long_opt, usage_argful_short_opt,
* argp/argp-fmtstream.c (__argp_fmtstream_update): Account for case
* argp/argp-help.c <stddef.h>: New include.
* argp/argp.h (argp_state_help, __argp_state_help, argp_usage,
* argp/argp.h (argp_program_bug_address): Make const.
* argp/argp-parse.c (argp_default_parser): Set STATE->name for OPT_PROGNAME.
* argp/argp-help.c (__argp_error, __argp_failure, __argp_state_help):
* argp/argp-parse.c (parser_init): Set PARSER->state.flags.
1997-06-19 21:11:22 +02:00
|
|
|
@comment argp.h
|
|
|
|
@comment GNU
|
|
|
|
@item ARGP_KEY_ARGS
|
|
|
|
If a parser function returns @code{ARGP_ERR_UNKNOWN} for
|
|
|
|
@code{ARGP_KEY_ARG}, it is immediately called again with the key
|
|
|
|
@code{ARGP_KEY_ARGS}, which has a similar meaning, but is slightly more
|
|
|
|
convenient for consuming all remaining arguments. @var{arg} is 0, and
|
|
|
|
the tail of the argument vector may be found at @code{@var{state}->argv
|
|
|
|
+ @var{state}->next}. If success is returned for this key, and
|
|
|
|
@code{@var{state}->next} is unchanged, then all remaining arguments are
|
|
|
|
considered to have been consumed, otherwise, the amount by which
|
|
|
|
@code{@var{state}->next} has been adjust indicates how many were used.
|
|
|
|
For instance, here's an example that uses both, for different args:
|
|
|
|
|
|
|
|
@smallexample
|
|
|
|
...
|
|
|
|
case ARGP_KEY_ARG:
|
|
|
|
if (@var{state}->arg_num == 0)
|
|
|
|
/* First argument */
|
|
|
|
first_arg = @var{arg};
|
|
|
|
else
|
1998-03-19 15:32:08 +01:00
|
|
|
/* Let the next case parse it. */
|
|
|
|
return ARGP_KEY_UNKNOWN;
|
Update.
1997-06-19 19:38 Ulrich Drepper <drepper@cygnus.com>
* features.h: Define __STDC_IEC_559__ and _STDC_IEC_559_COMPLEX__.
* elf/dl-minimal.c (__dcgettext): Remove assertion.
* inet/rcmd.c: Correct a few typos. Reported by Eric Troan.
* manual/Makefile (distribute): Add dir.
* manual/dir: New file.
* math/Makefile (libm-support): Rename s_rinttol, s_rinttoll,
s_roundtol, and s_roundtoll to s_lrint, s_llrint, s_lround,
and s_llround respectively.
(libm-calls): Add e_gamma_r.
* math/libm-test.c (check_int_exc): New function.
(signbit_test): Remove test for sign of NaN.
(gamma_test): Clear exception after test of existence.
Correct tests and and epsilons.
(lgamma_test): Likewise.
(ilogb_test): Correct all tests.
(scalb_test): Rewrite.
(rinttol_test): Rename to lrint_test and correct tests.
(rinttoll_test): Likewise.
(roundtol_test): Likewise.
(roundtoll_test): Likewise.
(main): Call lrint/lround functions instead of rinttol/roundtol.
* math/math.h: Change prototypes for rinttol/roundtol.
* math/mathcalls.h: Rearrange prototypes according to ISO C9X draft.
* sysdeps/generic/mathbits.h: Define FP_ILOGB0 and FP_ILOGBNAN.
* sysdeps/i386/mathbits.h: Likewise.
* sysdeps/libm-i387/e_scalb.S: Handle special cases correctly.
* sysdeps/libm-i387/e_scalbf.S: Likewise.
* sysdeps/libm-i387/e_scalbl.S: Likewise.
* sysdeps/libm-i387/s_asinh.S: Handle -inf correctly.
* sysdeps/libm-i387/s_asinhf.S: Likewise.
* sysdeps/libm-i387/s_asinhl.S: Likewise.
* sysdeps/libm-i387/s_ilogb.S: Optimize.
* sysdeps/libm-i387/s_ilogbf.S: Likewise.
* sysdeps/libm-i387/s_ilogbl.S: Likewise.
* sysdeps/libm-i387/s_rinttol.S: Rename to...
* sysdeps/libm-i387/s_lrint.S: ...this.
* sysdeps/libm-i387/s_rinttoll.S: Rename to...
* sysdeps/libm-i387/s_llrint.S: ...this.
* sysdeps/libm-i387/s_remquo.S: Correctly set sign of remainder.
* sysdeps/libm-i387/s_remquof.S: Likewise.
* sysdeps/libm-i387/s_remquol.S: Likewise.
* sysdeps/libm-i387/e_gamma_r.c: New file. Implementation of gamma
function according to ISO C.
* sysdeps/libm-i387/e_gammaf_r.c: New file.
* sysdeps/libm-i387/e_gammal_r.c: New file.
* sysdeps/libm-i387/e_lgamma_r.c: Don't let optimize compile the
generation of exceptions away.
* sysdeps/libm-i387/e_lgammaf_r.c: Likewise.
* sysdeps/libm-i387/k_standard.c: Correct return value for infinity
points of gamma function when not SVID mode.
* sysdeps/libm-i387/s_rinttoll.c: Renamed to...
* sysdeps/libm-i387/s_llrint.c: ...this.
* sysdeps/libm-i387/s_rinttol.c: Renamed to...
* sysdeps/libm-i387/s_lrint.c: ...this.
* sysdeps/libm-i387/s_roundtoll.c: Renamed to...
* sysdeps/libm-i387/s_llround.c: ...this.
* sysdeps/libm-i387/s_roundtol.c: Renamed to...
* sysdeps/libm-i387/s_lround.c: ..this.
* sysdeps/libm-i387/s_scalbn.c: Change second parameter according to
ISO C.
* sysdeps/libm-i387/s_scalbnf.c: Likewise.
* sysdeps/libm-i387/s_scalbnl.c: Likewise.
* sysdeps/libm-i387/w_gamma.c: Call __ieee754_gamma_r if library
mode is not _SVID_.
* sysdeps/libm-i387/w_gammaf.c: Likewise.
* sysdeps/libm-i387/w_gammal.c: Likewise.
* sysdeps/m68k/fpu/__math.h: Rename __rinttol to __lrint and
rinttol to lrint.
* sysdeps/m68k/fpu/s_rinttol.c: Renamed to...
* sysdeps/m68k/fpu/s_lrint.c: ...this.
* sysdeps/m68k/fpu/s_rinttoll.c: Renamed to...
* sysdeps/m68k/fpu/s_llrint.c: ...this.
* md5-crypt/Makefile: Link md5test program with md5.o.
* stdio-common/temptest.c: Don't use __stdio_gen_tempname which
is not exported by the libc.so.
* stdio-common/vfscanf.c: Correct scanning of strings after last
change.
* sysdeps/unix/sysv/linux/i386/sysdep.S: Use .comm to define errno.
1997-06-19 07:37 H.J. Lu <hjl@gnu.ai.mit.edu>
* time/tzfile.c (__tzfile_read): Store getc () return in int.
1997-06-13 Miles Bader <miles@gnu.ai.mit.edu>
* argp/argp-parse.c (argp_version_parser): Include `(PROGRAM ERROR)' in
the no-version error text to indicate that something's fucked.
[!_] (N_): New macro.
(argp_default_options, argp_version_options): Wrap doc strings in N_().
1997-06-12 Miles Bader <miles@gnu.ai.mit.edu>
* argp/argp-parse.c (parser_parse_opt): Detect and report unhandled
options here.
(parser_parse_arg): Handle ARGP_KEY_ARGS here.
Adjust NEXT pointer back if we fail to parse anything.
(parser_parse_next): Simplify arg code. Leave state NEXT frobbing
to parser_parse_arg.
1997-06-11 Miles Bader <miles@gnu.ai.mit.edu>
* argp/argp.h (ARGP_KEY_ARGS, ARGP_KEY_FINI): New macros.
* argp/argp-parse.c (parser_finalize): Do another pass over the
parsers with ARGP_KEY_FINI.
1997-06-18 Miles Bader <miles@gnu.ai.mit.edu>
* string/Makefile (routines): Add argz-replace.
1997-06-16 00:16 Miles Bader <miles@gnu.ai.mit.edu>
* manual/string.texi (Argz Functions): Document argz_replace.
1997-06-12 Miles Bader <miles@gnu.ai.mit.edu>
* string/argz.h (__argz_replace, argz_replace): New declarations.
* string/argz-replace.c: New file.
1997-06-11 Miles Bader <miles@gnu.ai.mit.edu>
* manual/argp.texi (Argp Special Keys): Document ARGP_KEY_ARGS.
1997-06-16 23:08 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* Makeconfig (libc-map): Remove definition.
* Makerules (libc-map): Define it here, using the full name.
(load-map-file): Remove case for empty $(..).
($(common-objpfx)libc.so): Revert last change.
1997-06-17 22:18 Mark Kettenis <kettenis@phys.uva.nl>
* login/programs/utmpd.c (main): Improve signal handling.
* login/programs/request.c (do_setutent, do_updwtmp):
Allow arbitrary length filenames.
* login/programs/utmpd.h (setutent_request, updwtmp_request):
Get rid of fixed length file field.
* login/utmp_daemon.c (do_setutent, do_updwtmp):
Allow arbitrary length filenames.
* login/programs/request.c (do_pututline):
Don't fail if connection->position is -1 on entry.
1997-06-15 16:32 Mark Kettenis <kettenis@phys.uva.nl>
* login/utmp_file.c (updwtmp_file): Use the same method for
appending an entry as in pututline_file.
1997-06-11 18:59 Mark Kettenis <kettenis@phys.uva.nl>
* login/utmp_file.c (getutent_r_file):
Use read lock instead of write lock.
(getutline_r_file, internal_getut_r): Lock utmp file.
(updwtmp_file): Use fcntl to lock file instead of flock.
1997-06-18 00:11 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* stdio-common/vfscanf.c (inchar, ungetc): Don't count EOF as
character read in/put back.
* stdio-common/tstscanf.c: Add test case for this.
1997-06-17 22:17 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* libc.map: Add more symbols.
1997-06-18 12:01 Ulrich Drepper <drepper@cygnus.com>
* manual/Makefile (install): Make sure `dir' file exists if we use
install-info.
1997-06-17 19:32 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* manual/Makefile (info): Depend on dir-add.info.
1997-06-17 17:19 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* elf/ldd.bash.in: Fix spacing in message.
1997-06-17 14:28 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* elf/do-rel.h (elf_dynamic_do_rel): Always use version
information if available.
1997-06-17 11:34 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* sunrpc/Makefile ($(rpcsvc:%.x=$(objpfx)rpcsvc/%.h)): Make
command non-empty to force make to recheck modification time.
($(rpcsvc:%.x=$(objpfx)x%.c)): Likewise.
1997-06-17 00:26 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* sysdeps/stub/e_acoshl.c: Set errno to ENOSYS.
* sysdeps/stub/e_acosl.c: Likewise.
* sysdeps/stub/e_asinl.c: Likewise.
* sysdeps/stub/e_atan2l.c: Likewise.
* sysdeps/stub/e_expl.c: Likewise.
* sysdeps/stub/e_fmodl.c: Likewise.
* sysdeps/stub/e_j0l.c: Likewise.
* sysdeps/stub/e_j1l.c: Likewise.
* sysdeps/stub/e_jnl.c: Likewise.
* sysdeps/stub/e_lgammal_r.c: Likewise.
* sysdeps/stub/e_log10l.c: Likewise.
* sysdeps/stub/e_logl.c: Likewise.
* sysdeps/stub/e_powl.c: Likewise.
* sysdeps/stub/e_rem_pio2l.c: Likewise.
* sysdeps/stub/e_sqrtl.c: Likewise.
* sysdeps/stub/k_cosl.c: Likewise.
* sysdeps/stub/k_rem_pio2l.c: Likewise.
* sysdeps/stub/k_sinl.c: Likewise.
* sysdeps/stub/k_tanl.c: Likewise.
* sysdeps/stub/s_atanl.c: Likewise.
* sysdeps/stub/s_erfl.c: Likewise.
* sysdeps/stub/s_exp2.c: Likewise.
* sysdeps/stub/s_exp2f.c: Likewise.
* sysdeps/stub/s_exp2l.c: Likewise.
* sysdeps/stub/s_expm1l.c: Likewise.
* sysdeps/stub/s_log1pl.c: Likewise.
* sysdeps/stub/s_log2l.c: Likewise.
1997-06-18 11:46 Ulrich Drepper <drepper@cygnus.com>
* sysdeps/libm-ieee754/w_gamma.c: If _LIB_VERSION is _SVID_ compute
result as before last change.
* sysdeps/libm-ieee754/w_gammaf.c: Likewise.
* sysdeps/libm-ieee754/w_gammal.c: Likewise.
1997-06-16 23:37 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* sysdeps/libm-ieee754/s_remquo.c: Fix off-by-one when computing
quotient.
* sysdeps/libm-ieee754/s_remquof.c: Likewise.
* sysdeps/libm-ieee754/s_remquol.c: Likewise.
* sysdeps/m68k/fpu/s_remquo.c: Remove FIXME and special case for
quotient.
* sysdeps/libm-ieee754/w_gamma.c: Add missing call to exp
function. Don't use global signgam.
* sysdeps/libm-ieee754/w_gammaf.c: Likewise.
* sysdeps/libm-ieee754/w_gammal.c: Likewise.
* math/Makefile (libm-calls): Remove w_gamma_r.
* sysdeps/libm-ieee754/w_gamma_r.c: Remove file.
* sysdeps/libm-ieee754/w_gammaf_r.c: Remove file.
* sysdeps/libm-ieee754/w_gammal_r.c: Remove file.
* math/libm-test.c (atanh_test): Declare x only if needed.
(signbit_test): Fix typo.
(gamma_test): Check whether function is implemented. Add
epsilons.
(lgamma_test): Likewise.
(fmod_test): Add epsilons.
(exp2_test): Use right function for existence test.
1997-06-07 09:20 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* sysdeps/powerpc/Dist: Add fenv_const.c.
* sysdeps/unix/sysv/linux/Dist: Add net/if_slip.h.
* sysdeps/unix/sysv/linux/powerpc/Dist: Add init-first.h and
syscall.h.
* sysdeps/unix/sysv/linux/sparc/Dist: Add init-first.h.
* string/Makefile (distribute): Add tst-svc.expect.
* nis/Makefile (distribute): Add nis_intern.h and Banner.
* elf/Makefile (distribute): Add dl-hash.h.
* Rules (subdir_echo-distinfo): Add headers from $(distribute).
* login/Makefile (others): Add utmpdump.
* sysdeps/unix/sysv/linux/Makefile (sysdep_headers): Add
net/if_slip.h.
* manual/Makefile (dir-add.texi): Also look in indirectly included
files.
1997-06-16 23:15 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* sysdeps/unix/sysv/linux/configure.in: Remove commands to
generate stdio_lim.h.
* sysdeps/unix/sysv/linux/mk-stdiolim.c: Remove.
* sysdeps/unix/sysv/linux/Makefile: Add rules to generate
stdio_lim.h here.
(common-generated): Add generated files.
(inhibit-stdio_lim): Define.
* sysdeps/posix/Makefile [$(inhibit-stdio_lim)=yes]: Disable rules
to generate stdio_lim.h.
* sysdeps/unix/sysv/linux/Makefile: Suppress inclusion of
dependecy files if no_deps is set.
($(objpfx)syscall-%.d): Add header file as target to dependency
generation.
1997-06-14 19:19 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* sysdeps/unix/sysv/linux/arm/Dist: New file.
1997-06-14 17:59 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* extra-lib.mk (others): Depend on versioned shared library, not
the unversioned one.
* Makerules (build-shlib): Don't make the version link here.
($(common-objpfx)libc.so$(libc.so-version)): New rule for libc
version link.
1997-06-16 03:07 Ulrich Drepper <drepper@cygnus.com>
* sysdeps/libm-ieee754/k_standard.c: Undo change of Tue Aug 6
01:13:56 1996.
* argp/argp-help.c (argp_args_usage): Supply correct argp to
filter_doc.
* argp/argp-help.c (hol_add_cluster): Initialize CL->depth.
* argp/argp-help.c (_help): Supply STATE to argp_args_usage.
* argp/argp.h (ARGP_KEY_HELP_ARGS_DOC): New macro.
* argp/argp-fmtstream.c: Add casts to prevent warnings.
* argp/argp.h (OPTION_NO_USAGE): New macro.
* argp/argp-help.c (usage_long_opt, usage_argful_short_opt,
* argp/argp-fmtstream.c (__argp_fmtstream_update): Account for case
* argp/argp-help.c <stddef.h>: New include.
* argp/argp.h (argp_state_help, __argp_state_help, argp_usage,
* argp/argp.h (argp_program_bug_address): Make const.
* argp/argp-parse.c (argp_default_parser): Set STATE->name for OPT_PROGNAME.
* argp/argp-help.c (__argp_error, __argp_failure, __argp_state_help):
* argp/argp-parse.c (parser_init): Set PARSER->state.flags.
1997-06-19 21:11:22 +02:00
|
|
|
break;
|
|
|
|
case ARGP_KEY_ARGS:
|
|
|
|
remaining_args = @var{state}->argv + @var{state}->next;
|
|
|
|
num_remaining_args = @var{state}->argc - @var{state}->next;
|
|
|
|
break;
|
|
|
|
@end smallexample
|
|
|
|
|
1997-06-05 13:28:54 +02:00
|
|
|
@comment argp.h
|
|
|
|
@comment GNU
|
|
|
|
@item ARGP_KEY_END
|
2000-07-24 07:41:25 +02:00
|
|
|
There are no more command line arguments at all. The parser functions
|
|
|
|
are called in different order (means children first) for this value
|
|
|
|
which allows each parser to clean up its state for the parent.
|
1997-06-05 13:28:54 +02:00
|
|
|
|
|
|
|
@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}
|
2000-04-18 08:24:03 +02:00
|
|
|
for an argument, in which case parsing stops at that argument. If
|
|
|
|
@var{arg_index} is a null pointer otherwise an error occurs.
|
1997-06-05 13:28:54 +02:00
|
|
|
@end table
|
|
|
|
|
2000-04-18 08:24:03 +02:00
|
|
|
In all cases, if a non-null value for @var{arg_index} was passed to
|
|
|
|
@code{argp_parse}, the index of the first unparsed command-line argument
|
|
|
|
is passed back in it.
|
|
|
|
|
1997-06-05 13:28:54 +02:00
|
|
|
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
|
1998-06-11 16:56:10 +02:00
|
|
|
@deftypefun void argp_error (const struct argp_state *@var{state}, const char *@var{fmt}, @dots{})
|
1997-06-05 13:28:54 +02:00
|
|
|
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
|
1998-06-11 16:56:10 +02:00
|
|
|
@deftypefun void argp_failure (const struct argp_state *@var{state}, int @var{status}, int @var{errnum}, const char *@var{fmt}, @dots{})
|
1997-06-05 13:28:54 +02:00
|
|
|
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
|
1998-06-11 16:56:10 +02:00
|
|
|
@deftypefun void argp_state_help (const struct argp_state *@var{state}, FILE *@var{stream}, unsigned @var{flags})
|
1997-06-05 13:28:54 +02:00
|
|
|
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
|
Update.
1997-06-19 19:38 Ulrich Drepper <drepper@cygnus.com>
* features.h: Define __STDC_IEC_559__ and _STDC_IEC_559_COMPLEX__.
* elf/dl-minimal.c (__dcgettext): Remove assertion.
* inet/rcmd.c: Correct a few typos. Reported by Eric Troan.
* manual/Makefile (distribute): Add dir.
* manual/dir: New file.
* math/Makefile (libm-support): Rename s_rinttol, s_rinttoll,
s_roundtol, and s_roundtoll to s_lrint, s_llrint, s_lround,
and s_llround respectively.
(libm-calls): Add e_gamma_r.
* math/libm-test.c (check_int_exc): New function.
(signbit_test): Remove test for sign of NaN.
(gamma_test): Clear exception after test of existence.
Correct tests and and epsilons.
(lgamma_test): Likewise.
(ilogb_test): Correct all tests.
(scalb_test): Rewrite.
(rinttol_test): Rename to lrint_test and correct tests.
(rinttoll_test): Likewise.
(roundtol_test): Likewise.
(roundtoll_test): Likewise.
(main): Call lrint/lround functions instead of rinttol/roundtol.
* math/math.h: Change prototypes for rinttol/roundtol.
* math/mathcalls.h: Rearrange prototypes according to ISO C9X draft.
* sysdeps/generic/mathbits.h: Define FP_ILOGB0 and FP_ILOGBNAN.
* sysdeps/i386/mathbits.h: Likewise.
* sysdeps/libm-i387/e_scalb.S: Handle special cases correctly.
* sysdeps/libm-i387/e_scalbf.S: Likewise.
* sysdeps/libm-i387/e_scalbl.S: Likewise.
* sysdeps/libm-i387/s_asinh.S: Handle -inf correctly.
* sysdeps/libm-i387/s_asinhf.S: Likewise.
* sysdeps/libm-i387/s_asinhl.S: Likewise.
* sysdeps/libm-i387/s_ilogb.S: Optimize.
* sysdeps/libm-i387/s_ilogbf.S: Likewise.
* sysdeps/libm-i387/s_ilogbl.S: Likewise.
* sysdeps/libm-i387/s_rinttol.S: Rename to...
* sysdeps/libm-i387/s_lrint.S: ...this.
* sysdeps/libm-i387/s_rinttoll.S: Rename to...
* sysdeps/libm-i387/s_llrint.S: ...this.
* sysdeps/libm-i387/s_remquo.S: Correctly set sign of remainder.
* sysdeps/libm-i387/s_remquof.S: Likewise.
* sysdeps/libm-i387/s_remquol.S: Likewise.
* sysdeps/libm-i387/e_gamma_r.c: New file. Implementation of gamma
function according to ISO C.
* sysdeps/libm-i387/e_gammaf_r.c: New file.
* sysdeps/libm-i387/e_gammal_r.c: New file.
* sysdeps/libm-i387/e_lgamma_r.c: Don't let optimize compile the
generation of exceptions away.
* sysdeps/libm-i387/e_lgammaf_r.c: Likewise.
* sysdeps/libm-i387/k_standard.c: Correct return value for infinity
points of gamma function when not SVID mode.
* sysdeps/libm-i387/s_rinttoll.c: Renamed to...
* sysdeps/libm-i387/s_llrint.c: ...this.
* sysdeps/libm-i387/s_rinttol.c: Renamed to...
* sysdeps/libm-i387/s_lrint.c: ...this.
* sysdeps/libm-i387/s_roundtoll.c: Renamed to...
* sysdeps/libm-i387/s_llround.c: ...this.
* sysdeps/libm-i387/s_roundtol.c: Renamed to...
* sysdeps/libm-i387/s_lround.c: ..this.
* sysdeps/libm-i387/s_scalbn.c: Change second parameter according to
ISO C.
* sysdeps/libm-i387/s_scalbnf.c: Likewise.
* sysdeps/libm-i387/s_scalbnl.c: Likewise.
* sysdeps/libm-i387/w_gamma.c: Call __ieee754_gamma_r if library
mode is not _SVID_.
* sysdeps/libm-i387/w_gammaf.c: Likewise.
* sysdeps/libm-i387/w_gammal.c: Likewise.
* sysdeps/m68k/fpu/__math.h: Rename __rinttol to __lrint and
rinttol to lrint.
* sysdeps/m68k/fpu/s_rinttol.c: Renamed to...
* sysdeps/m68k/fpu/s_lrint.c: ...this.
* sysdeps/m68k/fpu/s_rinttoll.c: Renamed to...
* sysdeps/m68k/fpu/s_llrint.c: ...this.
* md5-crypt/Makefile: Link md5test program with md5.o.
* stdio-common/temptest.c: Don't use __stdio_gen_tempname which
is not exported by the libc.so.
* stdio-common/vfscanf.c: Correct scanning of strings after last
change.
* sysdeps/unix/sysv/linux/i386/sysdep.S: Use .comm to define errno.
1997-06-19 07:37 H.J. Lu <hjl@gnu.ai.mit.edu>
* time/tzfile.c (__tzfile_read): Store getc () return in int.
1997-06-13 Miles Bader <miles@gnu.ai.mit.edu>
* argp/argp-parse.c (argp_version_parser): Include `(PROGRAM ERROR)' in
the no-version error text to indicate that something's fucked.
[!_] (N_): New macro.
(argp_default_options, argp_version_options): Wrap doc strings in N_().
1997-06-12 Miles Bader <miles@gnu.ai.mit.edu>
* argp/argp-parse.c (parser_parse_opt): Detect and report unhandled
options here.
(parser_parse_arg): Handle ARGP_KEY_ARGS here.
Adjust NEXT pointer back if we fail to parse anything.
(parser_parse_next): Simplify arg code. Leave state NEXT frobbing
to parser_parse_arg.
1997-06-11 Miles Bader <miles@gnu.ai.mit.edu>
* argp/argp.h (ARGP_KEY_ARGS, ARGP_KEY_FINI): New macros.
* argp/argp-parse.c (parser_finalize): Do another pass over the
parsers with ARGP_KEY_FINI.
1997-06-18 Miles Bader <miles@gnu.ai.mit.edu>
* string/Makefile (routines): Add argz-replace.
1997-06-16 00:16 Miles Bader <miles@gnu.ai.mit.edu>
* manual/string.texi (Argz Functions): Document argz_replace.
1997-06-12 Miles Bader <miles@gnu.ai.mit.edu>
* string/argz.h (__argz_replace, argz_replace): New declarations.
* string/argz-replace.c: New file.
1997-06-11 Miles Bader <miles@gnu.ai.mit.edu>
* manual/argp.texi (Argp Special Keys): Document ARGP_KEY_ARGS.
1997-06-16 23:08 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* Makeconfig (libc-map): Remove definition.
* Makerules (libc-map): Define it here, using the full name.
(load-map-file): Remove case for empty $(..).
($(common-objpfx)libc.so): Revert last change.
1997-06-17 22:18 Mark Kettenis <kettenis@phys.uva.nl>
* login/programs/utmpd.c (main): Improve signal handling.
* login/programs/request.c (do_setutent, do_updwtmp):
Allow arbitrary length filenames.
* login/programs/utmpd.h (setutent_request, updwtmp_request):
Get rid of fixed length file field.
* login/utmp_daemon.c (do_setutent, do_updwtmp):
Allow arbitrary length filenames.
* login/programs/request.c (do_pututline):
Don't fail if connection->position is -1 on entry.
1997-06-15 16:32 Mark Kettenis <kettenis@phys.uva.nl>
* login/utmp_file.c (updwtmp_file): Use the same method for
appending an entry as in pututline_file.
1997-06-11 18:59 Mark Kettenis <kettenis@phys.uva.nl>
* login/utmp_file.c (getutent_r_file):
Use read lock instead of write lock.
(getutline_r_file, internal_getut_r): Lock utmp file.
(updwtmp_file): Use fcntl to lock file instead of flock.
1997-06-18 00:11 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* stdio-common/vfscanf.c (inchar, ungetc): Don't count EOF as
character read in/put back.
* stdio-common/tstscanf.c: Add test case for this.
1997-06-17 22:17 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* libc.map: Add more symbols.
1997-06-18 12:01 Ulrich Drepper <drepper@cygnus.com>
* manual/Makefile (install): Make sure `dir' file exists if we use
install-info.
1997-06-17 19:32 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* manual/Makefile (info): Depend on dir-add.info.
1997-06-17 17:19 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* elf/ldd.bash.in: Fix spacing in message.
1997-06-17 14:28 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* elf/do-rel.h (elf_dynamic_do_rel): Always use version
information if available.
1997-06-17 11:34 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* sunrpc/Makefile ($(rpcsvc:%.x=$(objpfx)rpcsvc/%.h)): Make
command non-empty to force make to recheck modification time.
($(rpcsvc:%.x=$(objpfx)x%.c)): Likewise.
1997-06-17 00:26 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* sysdeps/stub/e_acoshl.c: Set errno to ENOSYS.
* sysdeps/stub/e_acosl.c: Likewise.
* sysdeps/stub/e_asinl.c: Likewise.
* sysdeps/stub/e_atan2l.c: Likewise.
* sysdeps/stub/e_expl.c: Likewise.
* sysdeps/stub/e_fmodl.c: Likewise.
* sysdeps/stub/e_j0l.c: Likewise.
* sysdeps/stub/e_j1l.c: Likewise.
* sysdeps/stub/e_jnl.c: Likewise.
* sysdeps/stub/e_lgammal_r.c: Likewise.
* sysdeps/stub/e_log10l.c: Likewise.
* sysdeps/stub/e_logl.c: Likewise.
* sysdeps/stub/e_powl.c: Likewise.
* sysdeps/stub/e_rem_pio2l.c: Likewise.
* sysdeps/stub/e_sqrtl.c: Likewise.
* sysdeps/stub/k_cosl.c: Likewise.
* sysdeps/stub/k_rem_pio2l.c: Likewise.
* sysdeps/stub/k_sinl.c: Likewise.
* sysdeps/stub/k_tanl.c: Likewise.
* sysdeps/stub/s_atanl.c: Likewise.
* sysdeps/stub/s_erfl.c: Likewise.
* sysdeps/stub/s_exp2.c: Likewise.
* sysdeps/stub/s_exp2f.c: Likewise.
* sysdeps/stub/s_exp2l.c: Likewise.
* sysdeps/stub/s_expm1l.c: Likewise.
* sysdeps/stub/s_log1pl.c: Likewise.
* sysdeps/stub/s_log2l.c: Likewise.
1997-06-18 11:46 Ulrich Drepper <drepper@cygnus.com>
* sysdeps/libm-ieee754/w_gamma.c: If _LIB_VERSION is _SVID_ compute
result as before last change.
* sysdeps/libm-ieee754/w_gammaf.c: Likewise.
* sysdeps/libm-ieee754/w_gammal.c: Likewise.
1997-06-16 23:37 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* sysdeps/libm-ieee754/s_remquo.c: Fix off-by-one when computing
quotient.
* sysdeps/libm-ieee754/s_remquof.c: Likewise.
* sysdeps/libm-ieee754/s_remquol.c: Likewise.
* sysdeps/m68k/fpu/s_remquo.c: Remove FIXME and special case for
quotient.
* sysdeps/libm-ieee754/w_gamma.c: Add missing call to exp
function. Don't use global signgam.
* sysdeps/libm-ieee754/w_gammaf.c: Likewise.
* sysdeps/libm-ieee754/w_gammal.c: Likewise.
* math/Makefile (libm-calls): Remove w_gamma_r.
* sysdeps/libm-ieee754/w_gamma_r.c: Remove file.
* sysdeps/libm-ieee754/w_gammaf_r.c: Remove file.
* sysdeps/libm-ieee754/w_gammal_r.c: Remove file.
* math/libm-test.c (atanh_test): Declare x only if needed.
(signbit_test): Fix typo.
(gamma_test): Check whether function is implemented. Add
epsilons.
(lgamma_test): Likewise.
(fmod_test): Add epsilons.
(exp2_test): Use right function for existence test.
1997-06-07 09:20 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* sysdeps/powerpc/Dist: Add fenv_const.c.
* sysdeps/unix/sysv/linux/Dist: Add net/if_slip.h.
* sysdeps/unix/sysv/linux/powerpc/Dist: Add init-first.h and
syscall.h.
* sysdeps/unix/sysv/linux/sparc/Dist: Add init-first.h.
* string/Makefile (distribute): Add tst-svc.expect.
* nis/Makefile (distribute): Add nis_intern.h and Banner.
* elf/Makefile (distribute): Add dl-hash.h.
* Rules (subdir_echo-distinfo): Add headers from $(distribute).
* login/Makefile (others): Add utmpdump.
* sysdeps/unix/sysv/linux/Makefile (sysdep_headers): Add
net/if_slip.h.
* manual/Makefile (dir-add.texi): Also look in indirectly included
files.
1997-06-16 23:15 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* sysdeps/unix/sysv/linux/configure.in: Remove commands to
generate stdio_lim.h.
* sysdeps/unix/sysv/linux/mk-stdiolim.c: Remove.
* sysdeps/unix/sysv/linux/Makefile: Add rules to generate
stdio_lim.h here.
(common-generated): Add generated files.
(inhibit-stdio_lim): Define.
* sysdeps/posix/Makefile [$(inhibit-stdio_lim)=yes]: Disable rules
to generate stdio_lim.h.
* sysdeps/unix/sysv/linux/Makefile: Suppress inclusion of
dependecy files if no_deps is set.
($(objpfx)syscall-%.d): Add header file as target to dependency
generation.
1997-06-14 19:19 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* sysdeps/unix/sysv/linux/arm/Dist: New file.
1997-06-14 17:59 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* extra-lib.mk (others): Depend on versioned shared library, not
the unversioned one.
* Makerules (build-shlib): Don't make the version link here.
($(common-objpfx)libc.so$(libc.so-version)): New rule for libc
version link.
1997-06-16 03:07 Ulrich Drepper <drepper@cygnus.com>
* sysdeps/libm-ieee754/k_standard.c: Undo change of Tue Aug 6
01:13:56 1996.
* argp/argp-help.c (argp_args_usage): Supply correct argp to
filter_doc.
* argp/argp-help.c (hol_add_cluster): Initialize CL->depth.
* argp/argp-help.c (_help): Supply STATE to argp_args_usage.
* argp/argp.h (ARGP_KEY_HELP_ARGS_DOC): New macro.
* argp/argp-fmtstream.c: Add casts to prevent warnings.
* argp/argp.h (OPTION_NO_USAGE): New macro.
* argp/argp-help.c (usage_long_opt, usage_argful_short_opt,
* argp/argp-fmtstream.c (__argp_fmtstream_update): Account for case
* argp/argp-help.c <stddef.h>: New include.
* argp/argp.h (argp_state_help, __argp_state_help, argp_usage,
* argp/argp.h (argp_program_bug_address): Make const.
* argp/argp-parse.c (argp_default_parser): Set STATE->name for OPT_PROGNAME.
* argp/argp-help.c (__argp_error, __argp_failure, __argp_state_help):
* argp/argp-parse.c (parser_init): Set PARSER->state.flags.
1997-06-19 21:11:22 +02:00
|
|
|
Use the gnu getopt `long-only' rules for parsing arguments. This
|
|
|
|
allows long-options to be recognized with only a single @samp{-} (for
|
|
|
|
instances, @samp{-help}), but results in a generally somewhat less
|
|
|
|
useful interface, that conflicts with the way most GNU programs work.
|
|
|
|
For this reason, its use is discouraged.
|
1997-06-05 13:28:54 +02:00
|
|
|
|
|
|
|
@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
|
|
|
|
|
1998-06-15 20:12:05 +02:00
|
|
|
The @code{help_filter} field in a @code{struct argp} is a pointer to a
|
1997-06-05 13:28:54 +02:00
|
|
|
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
|
1998-06-11 16:56:10 +02:00
|
|
|
@deftypefun void argp_help (const struct argp *@var{argp}, FILE *@var{stream}, unsigned @var{flags}, char *@var{name})
|
1997-06-05 13:28:54 +02:00
|
|
|
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
|