Update.
1997-06-04 05:09 Miles Bader <miles@gnu.ai.mit.edu> * argp/argp-help.c (_help): Use uparams.usage_indent instead of the USAGE_INDENT macro. * manual/summary.awk: Strip trailing commas from node-names. * manual/.cvsignore: Ignore chapters-incl[12] rather than chapters-incl. * manual/Makefile (%.c.texi): Deal with multiple @-commands on a single line. * manual/string.texi (Argz Functions, Envz Functions): Add magic comments for generating summary.texi. 1997-06-02 22:18 Miles Bader <miles@gnu.ai.mit.edu> * manual/argp.texi: New file. * manual/examples/argp-ex1.c, manual/examples/argp-ex2.c, manual/examples/argp-ex3.c, manual/examples/argp-ex4.c: New files. * manual/Makefile [chapters] (chapters-incl1): New rule & include. [chapters-incl1] (chapters-incl2): New rule & include. (chapters-incl): Set based on $(chapters-incl1) & $(chapters-incl2). * manual/maint.texi (Contributors): Give myself credit. 1997-06-01 15:01 Miles Bader <miles@gnu.ai.mit.edu> * manual/getopt.texi: New file. * manual/startup.texi: Mention argp_parse in places that previously mentioned only getopt. Include getopt.texi (now containing all the getopt nodes that used to be here) and argp.texi. (Program Arguments): Move parsing bits into the new Parsing Program Arguments node. (Parsing Program Arguments): New node. (Parsing Options, Example of Getopt, Long Options, Long Option Example): Nodes removed. * manual/libc.texinfo: (Program Arguments): Menu updated. (Parsing Program Arguments): New menu.
This commit is contained in:
parent
5649a1d60d
commit
b0de3e9e30
41
ChangeLog
41
ChangeLog
|
@ -1,3 +1,44 @@
|
||||||
|
1997-06-04 05:09 Miles Bader <miles@gnu.ai.mit.edu>
|
||||||
|
|
||||||
|
* argp/argp-help.c (_help): Use uparams.usage_indent instead of
|
||||||
|
the USAGE_INDENT macro.
|
||||||
|
|
||||||
|
* manual/summary.awk: Strip trailing commas from node-names.
|
||||||
|
|
||||||
|
* manual/.cvsignore: Ignore chapters-incl[12] rather than
|
||||||
|
chapters-incl.
|
||||||
|
|
||||||
|
* manual/Makefile (%.c.texi): Deal with multiple @-commands on a
|
||||||
|
single line.
|
||||||
|
|
||||||
|
* manual/string.texi (Argz Functions, Envz Functions): Add magic
|
||||||
|
comments for generating summary.texi.
|
||||||
|
|
||||||
|
1997-06-02 22:18 Miles Bader <miles@gnu.ai.mit.edu>
|
||||||
|
|
||||||
|
* manual/argp.texi: New file.
|
||||||
|
* manual/examples/argp-ex1.c, manual/examples/argp-ex2.c,
|
||||||
|
manual/examples/argp-ex3.c, manual/examples/argp-ex4.c: New files.
|
||||||
|
* manual/Makefile [chapters] (chapters-incl1): New rule & include.
|
||||||
|
[chapters-incl1] (chapters-incl2): New rule & include.
|
||||||
|
(chapters-incl): Set based on $(chapters-incl1) & $(chapters-incl2).
|
||||||
|
* manual/maint.texi (Contributors): Give myself credit.
|
||||||
|
|
||||||
|
1997-06-01 15:01 Miles Bader <miles@gnu.ai.mit.edu>
|
||||||
|
|
||||||
|
* manual/getopt.texi: New file.
|
||||||
|
* manual/startup.texi: Mention argp_parse in places that
|
||||||
|
previously mentioned only getopt.
|
||||||
|
Include getopt.texi (now containing all the getopt nodes that used
|
||||||
|
to be here) and argp.texi.
|
||||||
|
(Program Arguments): Move parsing bits into the new Parsing
|
||||||
|
Program Arguments node.
|
||||||
|
(Parsing Program Arguments): New node.
|
||||||
|
(Parsing Options, Example of Getopt, Long Options, Long Option
|
||||||
|
Example): Nodes removed.
|
||||||
|
* manual/libc.texinfo: (Program Arguments): Menu updated.
|
||||||
|
(Parsing Program Arguments): New menu.
|
||||||
|
|
||||||
1997-06-04 20:57 Ulrich Drepper <drepper@cygnus.com>
|
1997-06-04 20:57 Ulrich Drepper <drepper@cygnus.com>
|
||||||
|
|
||||||
* manual/string.texi: Add comments to discourage use of index and
|
* manual/string.texi: Add comments to discourage use of index and
|
||||||
|
|
|
@ -1499,7 +1499,7 @@ _help (const struct argp *argp, const struct argp_state *state, FILE *stream,
|
||||||
do
|
do
|
||||||
{
|
{
|
||||||
int old_lm;
|
int old_lm;
|
||||||
int old_wm = __argp_fmtstream_set_wmargin (fs, USAGE_INDENT);
|
int old_wm = __argp_fmtstream_set_wmargin (fs, uparams.usage_indent);
|
||||||
char *levels = pattern_levels;
|
char *levels = pattern_levels;
|
||||||
|
|
||||||
__argp_fmtstream_printf (fs, "%s %s",
|
__argp_fmtstream_printf (fs, "%s %s",
|
||||||
|
@ -1508,7 +1508,7 @@ _help (const struct argp *argp, const struct argp_state *state, FILE *stream,
|
||||||
|
|
||||||
/* We set the lmargin as well as the wmargin, because hol_usage
|
/* We set the lmargin as well as the wmargin, because hol_usage
|
||||||
manually wraps options with newline to avoid annoying breaks. */
|
manually wraps options with newline to avoid annoying breaks. */
|
||||||
old_lm = __argp_fmtstream_set_lmargin (fs, USAGE_INDENT);
|
old_lm = __argp_fmtstream_set_lmargin (fs, uparams.usage_indent);
|
||||||
|
|
||||||
if (flags & ARGP_HELP_SHORT_USAGE)
|
if (flags & ARGP_HELP_SHORT_USAGE)
|
||||||
/* Just show where the options go. */
|
/* Just show where the options go. */
|
||||||
|
|
|
@ -8,5 +8,5 @@ glibc-*
|
||||||
*.toc *.aux *.log
|
*.toc *.aux *.log
|
||||||
*.cp *.cps *.fn *.fns *.vr *.vrs *.tp *.tps *.ky *.kys *.pg *.pgs
|
*.cp *.cps *.fn *.fns *.vr *.vrs *.tp *.tps *.ky *.kys *.pg *.pgs
|
||||||
|
|
||||||
chapters chapters-incl summary.texi stamp-*
|
chapters chapters-incl1 chapters-incl2 summary.texi stamp-*
|
||||||
distinfo
|
distinfo
|
||||||
|
|
|
@ -39,11 +39,20 @@ endif
|
||||||
chapters: libc.texinfo
|
chapters: libc.texinfo
|
||||||
$(find-includes)
|
$(find-includes)
|
||||||
ifdef chapters
|
ifdef chapters
|
||||||
-include chapters-incl
|
# @includes in chapter files
|
||||||
chapters-incl: $(chapters)
|
-include chapters-incl1
|
||||||
|
chapters-incl1: $(chapters)
|
||||||
$(find-includes)
|
$(find-includes)
|
||||||
chapters-incl := $(filter-out summary.texi,$(chapters-incl))
|
chapters-incl1 := $(filter-out summary.texi,$(chapters-incl1))
|
||||||
endif
|
endif
|
||||||
|
ifdef chapters-incl1
|
||||||
|
# @includes in files included by chapter files, if any
|
||||||
|
-include chapters-incl2
|
||||||
|
chapters-incl2: $(chapters-incl1)
|
||||||
|
$(find-includes)
|
||||||
|
endif
|
||||||
|
|
||||||
|
chapters-incl := $(chapters-incl1) $(chapters-incl2)
|
||||||
|
|
||||||
define find-includes
|
define find-includes
|
||||||
(echo '$(@F) :=' \\ ;\
|
(echo '$(@F) :=' \\ ;\
|
||||||
|
@ -75,7 +84,7 @@ dir-add.texi: xtract-typefun.awk $(chapters)
|
||||||
sed -e 's,[{}],@&,g' \
|
sed -e 's,[{}],@&,g' \
|
||||||
-e 's,/\*\(@.*\)\*/,\1,g' \
|
-e 's,/\*\(@.*\)\*/,\1,g' \
|
||||||
-e 's,/\* *,/* @r{,g' -e 's, *\*/,} */,' \
|
-e 's,/\* *,/* @r{,g' -e 's, *\*/,} */,' \
|
||||||
-e 's/\(@[a-z][a-z]*\)@{\([^}]*\)@}/\1{\2}/'\
|
-e 's/\(@[a-z][a-z]*\)@{\([^}]*\)@}/\1{\2}/g'\
|
||||||
$< | expand > $@.new
|
$< | expand > $@.new
|
||||||
mv -f $@.new $@
|
mv -f $@.new $@
|
||||||
|
|
||||||
|
|
File diff suppressed because it is too large
Load Diff
|
@ -0,0 +1,257 @@
|
||||||
|
@node Getopt, Argp, , Parsing Program Arguments
|
||||||
|
@section Parsing program options using @code{getopt}
|
||||||
|
|
||||||
|
The @code{getopt} and @code{getopt_long} functions automate some of the
|
||||||
|
chore involved in parsing typical unix command line options.
|
||||||
|
|
||||||
|
@menu
|
||||||
|
* Using Getopt:: Using the @code{getopt} function.
|
||||||
|
* Example of Getopt:: An example of parsing options with @code{getopt}.
|
||||||
|
* Getopt Long Options:: GNU suggests utilities accept long-named
|
||||||
|
options; here is one way to do.
|
||||||
|
* Getopt Long Option Example:: An example of using @code{getopt_long}.
|
||||||
|
@end menu
|
||||||
|
|
||||||
|
@node Using Getopt, Example of Getopt, , Getopt
|
||||||
|
@subsection Using the @code{getopt} function
|
||||||
|
|
||||||
|
Here are the details about how to call the @code{getopt} function. To
|
||||||
|
use this facility, your program must include the header file
|
||||||
|
@file{unistd.h}.
|
||||||
|
@pindex unistd.h
|
||||||
|
|
||||||
|
@comment unistd.h
|
||||||
|
@comment POSIX.2
|
||||||
|
@deftypevar int opterr
|
||||||
|
If the value of this variable is nonzero, then @code{getopt} prints an
|
||||||
|
error message to the standard error stream if it encounters an unknown
|
||||||
|
option character or an option with a missing required argument. This is
|
||||||
|
the default behavior. If you set this variable to zero, @code{getopt}
|
||||||
|
does not print any messages, but it still returns the character @code{?}
|
||||||
|
to indicate an error.
|
||||||
|
@end deftypevar
|
||||||
|
|
||||||
|
@comment unistd.h
|
||||||
|
@comment POSIX.2
|
||||||
|
@deftypevar int optopt
|
||||||
|
When @code{getopt} encounters an unknown option character or an option
|
||||||
|
with a missing required argument, it stores that option character in
|
||||||
|
this variable. You can use this for providing your own diagnostic
|
||||||
|
messages.
|
||||||
|
@end deftypevar
|
||||||
|
|
||||||
|
@comment unistd.h
|
||||||
|
@comment POSIX.2
|
||||||
|
@deftypevar int optind
|
||||||
|
This variable is set by @code{getopt} to the index of the next element
|
||||||
|
of the @var{argv} array to be processed. Once @code{getopt} has found
|
||||||
|
all of the option arguments, you can use this variable to determine
|
||||||
|
where the remaining non-option arguments begin. The initial value of
|
||||||
|
this variable is @code{1}.
|
||||||
|
@end deftypevar
|
||||||
|
|
||||||
|
@comment unistd.h
|
||||||
|
@comment POSIX.2
|
||||||
|
@deftypevar {char *} optarg
|
||||||
|
This variable is set by @code{getopt} to point at the value of the
|
||||||
|
option argument, for those options that accept arguments.
|
||||||
|
@end deftypevar
|
||||||
|
|
||||||
|
@comment unistd.h
|
||||||
|
@comment POSIX.2
|
||||||
|
@deftypefun int getopt (int @var{argc}, char **@var{argv}, const char *@var{options})
|
||||||
|
The @code{getopt} function gets the next option argument from the
|
||||||
|
argument list specified by the @var{argv} and @var{argc} arguments.
|
||||||
|
Normally these values come directly from the arguments received by
|
||||||
|
@code{main}.
|
||||||
|
|
||||||
|
The @var{options} argument is a string that specifies the option
|
||||||
|
characters that are valid for this program. An option character in this
|
||||||
|
string can be followed by a colon (@samp{:}) to indicate that it takes a
|
||||||
|
required argument.
|
||||||
|
|
||||||
|
If the @var{options} argument string begins with a hyphen (@samp{-}), this
|
||||||
|
is treated specially. It permits arguments that are not options to be
|
||||||
|
returned as if they were associated with option character @samp{\0}.
|
||||||
|
|
||||||
|
The @code{getopt} function returns the option character for the next
|
||||||
|
command line option. When no more option arguments are available, it
|
||||||
|
returns @code{-1}. There may still be more non-option arguments; you
|
||||||
|
must compare the external variable @code{optind} against the @var{argc}
|
||||||
|
parameter to check this.
|
||||||
|
|
||||||
|
If the option has an argument, @code{getopt} returns the argument by
|
||||||
|
storing it in the variable @var{optarg}. You don't ordinarily need to
|
||||||
|
copy the @code{optarg} string, since it is a pointer into the original
|
||||||
|
@var{argv} array, not into a static area that might be overwritten.
|
||||||
|
|
||||||
|
If @code{getopt} finds an option character in @var{argv} that was not
|
||||||
|
included in @var{options}, or a missing option argument, it returns
|
||||||
|
@samp{?} and sets the external variable @code{optopt} to the actual
|
||||||
|
option character. If the first character of @var{options} is a colon
|
||||||
|
(@samp{:}), then @code{getopt} returns @samp{:} instead of @samp{?} to
|
||||||
|
indicate a missing option argument. In addition, if the external
|
||||||
|
variable @code{opterr} is nonzero (which is the default), @code{getopt}
|
||||||
|
prints an error message.
|
||||||
|
@end deftypefun
|
||||||
|
|
||||||
|
@node Example of Getopt
|
||||||
|
@subsection Example of Parsing Arguments with @code{getopt}
|
||||||
|
|
||||||
|
Here is an example showing how @code{getopt} is typically used. The
|
||||||
|
key points to notice are:
|
||||||
|
|
||||||
|
@itemize @bullet
|
||||||
|
@item
|
||||||
|
Normally, @code{getopt} is called in a loop. When @code{getopt} returns
|
||||||
|
@code{-1}, indicating no more options are present, the loop terminates.
|
||||||
|
|
||||||
|
@item
|
||||||
|
A @code{switch} statement is used to dispatch on the return value from
|
||||||
|
@code{getopt}. In typical use, each case just sets a variable that
|
||||||
|
is used later in the program.
|
||||||
|
|
||||||
|
@item
|
||||||
|
A second loop is used to process the remaining non-option arguments.
|
||||||
|
@end itemize
|
||||||
|
|
||||||
|
@smallexample
|
||||||
|
@include testopt.c.texi
|
||||||
|
@end smallexample
|
||||||
|
|
||||||
|
Here are some examples showing what this program prints with different
|
||||||
|
combinations of arguments:
|
||||||
|
|
||||||
|
@smallexample
|
||||||
|
% testopt
|
||||||
|
aflag = 0, bflag = 0, cvalue = (null)
|
||||||
|
|
||||||
|
% testopt -a -b
|
||||||
|
aflag = 1, bflag = 1, cvalue = (null)
|
||||||
|
|
||||||
|
% testopt -ab
|
||||||
|
aflag = 1, bflag = 1, cvalue = (null)
|
||||||
|
|
||||||
|
% testopt -c foo
|
||||||
|
aflag = 0, bflag = 0, cvalue = foo
|
||||||
|
|
||||||
|
% testopt -cfoo
|
||||||
|
aflag = 0, bflag = 0, cvalue = foo
|
||||||
|
|
||||||
|
% testopt arg1
|
||||||
|
aflag = 0, bflag = 0, cvalue = (null)
|
||||||
|
Non-option argument arg1
|
||||||
|
|
||||||
|
% testopt -a arg1
|
||||||
|
aflag = 1, bflag = 0, cvalue = (null)
|
||||||
|
Non-option argument arg1
|
||||||
|
|
||||||
|
% testopt -c foo arg1
|
||||||
|
aflag = 0, bflag = 0, cvalue = foo
|
||||||
|
Non-option argument arg1
|
||||||
|
|
||||||
|
% testopt -a -- -b
|
||||||
|
aflag = 1, bflag = 0, cvalue = (null)
|
||||||
|
Non-option argument -b
|
||||||
|
|
||||||
|
% testopt -a -
|
||||||
|
aflag = 1, bflag = 0, cvalue = (null)
|
||||||
|
Non-option argument -
|
||||||
|
@end smallexample
|
||||||
|
|
||||||
|
@node Getopt Long Options
|
||||||
|
@subsection Parsing Long Options with @code{getopt_long}
|
||||||
|
|
||||||
|
To accept GNU-style long options as well as single-character options,
|
||||||
|
use @code{getopt_long} instead of @code{getopt}. This function is
|
||||||
|
declared in @file{getopt.h}, not @file{unistd.h}. You should make every
|
||||||
|
program accept long options if it uses any options, for this takes
|
||||||
|
little extra work and helps beginners remember how to use the program.
|
||||||
|
|
||||||
|
@comment getopt.h
|
||||||
|
@comment GNU
|
||||||
|
@deftp {Data Type} {struct option}
|
||||||
|
This structure describes a single long option name for the sake of
|
||||||
|
@code{getopt_long}. The argument @var{longopts} must be an array of
|
||||||
|
these structures, one for each long option. Terminate the array with an
|
||||||
|
element containing all zeros.
|
||||||
|
|
||||||
|
The @code{struct option} structure has these fields:
|
||||||
|
|
||||||
|
@table @code
|
||||||
|
@item const char *name
|
||||||
|
This field is the name of the option. It is a string.
|
||||||
|
|
||||||
|
@item int has_arg
|
||||||
|
This field says whether the option takes an argument. It is an integer,
|
||||||
|
and there are three legitimate values: @w{@code{no_argument}},
|
||||||
|
@code{required_argument} and @code{optional_argument}.
|
||||||
|
|
||||||
|
@item int *flag
|
||||||
|
@itemx int val
|
||||||
|
These fields control how to report or act on the option when it occurs.
|
||||||
|
|
||||||
|
If @code{flag} is a null pointer, then the @code{val} is a value which
|
||||||
|
identifies this option. Often these values are chosen to uniquely
|
||||||
|
identify particular long options.
|
||||||
|
|
||||||
|
If @code{flag} is not a null pointer, it should be the address of an
|
||||||
|
@code{int} variable which is the flag for this option. The value in
|
||||||
|
@code{val} is the value to store in the flag to indicate that the option
|
||||||
|
was seen.
|
||||||
|
@end table
|
||||||
|
@end deftp
|
||||||
|
|
||||||
|
@comment getopt.h
|
||||||
|
@comment GNU
|
||||||
|
@deftypefun int getopt_long (int @var{argc}, char **@var{argv}, const char *@var{shortopts}, struct option *@var{longopts}, int *@var{indexptr})
|
||||||
|
Decode options from the vector @var{argv} (whose length is @var{argc}).
|
||||||
|
The argument @var{shortopts} describes the short options to accept, just as
|
||||||
|
it does in @code{getopt}. The argument @var{longopts} describes the long
|
||||||
|
options to accept (see above).
|
||||||
|
|
||||||
|
When @code{getopt_long} encounters a short option, it does the same
|
||||||
|
thing that @code{getopt} would do: it returns the character code for the
|
||||||
|
option, and stores the options argument (if it has one) in @code{optarg}.
|
||||||
|
|
||||||
|
When @code{getopt_long} encounters a long option, it takes actions based
|
||||||
|
on the @code{flag} and @code{val} fields of the definition of that
|
||||||
|
option.
|
||||||
|
|
||||||
|
If @code{flag} is a null pointer, then @code{getopt_long} returns the
|
||||||
|
contents of @code{val} to indicate which option it found. You should
|
||||||
|
arrange distinct values in the @code{val} field for options with
|
||||||
|
different meanings, so you can decode these values after
|
||||||
|
@code{getopt_long} returns. If the long option is equivalent to a short
|
||||||
|
option, you can use the short option's character code in @code{val}.
|
||||||
|
|
||||||
|
If @code{flag} is not a null pointer, that means this option should just
|
||||||
|
set a flag in the program. The flag is a variable of type @code{int}
|
||||||
|
that you define. Put the address of the flag in the @code{flag} field.
|
||||||
|
Put in the @code{val} field the value you would like this option to
|
||||||
|
store in the flag. In this case, @code{getopt_long} returns @code{0}.
|
||||||
|
|
||||||
|
For any long option, @code{getopt_long} tells you the index in the array
|
||||||
|
@var{longopts} of the options definition, by storing it into
|
||||||
|
@code{*@var{indexptr}}. You can get the name of the option with
|
||||||
|
@code{@var{longopts}[*@var{indexptr}].name}. So you can distinguish among
|
||||||
|
long options either by the values in their @code{val} fields or by their
|
||||||
|
indices. You can also distinguish in this way among long options that
|
||||||
|
set flags.
|
||||||
|
|
||||||
|
When a long option has an argument, @code{getopt_long} puts the argument
|
||||||
|
value in the variable @code{optarg} before returning. When the option
|
||||||
|
has no argument, the value in @code{optarg} is a null pointer. This is
|
||||||
|
how you can tell whether an optional argument was supplied.
|
||||||
|
|
||||||
|
When @code{getopt_long} has no more options to handle, it returns
|
||||||
|
@code{-1}, and leaves in the variable @code{optind} the index in
|
||||||
|
@var{argv} of the next remaining argument.
|
||||||
|
@end deftypefun
|
||||||
|
|
||||||
|
@node Getopt Long Option Example
|
||||||
|
@subsection Example of Parsing Long Options with @code{getopt_long}
|
||||||
|
|
||||||
|
@smallexample
|
||||||
|
@include longopt.c.texi
|
||||||
|
@end smallexample
|
|
@ -745,11 +745,14 @@ Process Startup and Termination
|
||||||
Program Arguments
|
Program Arguments
|
||||||
|
|
||||||
* Argument Syntax:: By convention, options start with a hyphen.
|
* Argument Syntax:: By convention, options start with a hyphen.
|
||||||
* Parsing Options:: The @code{getopt} function.
|
* Parsing Program Arguments:: Ways to parse program options and arguments.
|
||||||
* Example of Getopt:: An example of parsing options with @code{getopt}.
|
|
||||||
* Long Options:: GNU utilities should accept long-named options.
|
Parsing Program Arguments
|
||||||
Here is how to do that.
|
|
||||||
* Long Option Example:: An example of using @code{getopt_long}.
|
* Getopt:: Parsing program options using @code{getopt}.
|
||||||
|
* Argp:: Parsing program options using @code{argp_parse}.
|
||||||
|
* Suboptions:: Some programs need more detailed options.
|
||||||
|
* Suboptions Example:: This shows how it could be done for @code{mount}.
|
||||||
|
|
||||||
Environment Variables
|
Environment Variables
|
||||||
|
|
||||||
|
|
|
@ -901,6 +901,10 @@ support for the Alpha processor.
|
||||||
David Mosberger-Tang contributed the port to Linux/Alpha
|
David Mosberger-Tang contributed the port to Linux/Alpha
|
||||||
(@code{alpha-@var{anything}-linux}).
|
(@code{alpha-@var{anything}-linux}).
|
||||||
|
|
||||||
|
@item
|
||||||
|
Miles Bader wrote the argp argument-parsing package, and the argz/envz
|
||||||
|
interfaces.
|
||||||
|
|
||||||
@item
|
@item
|
||||||
Stephen R. van den Berg contributed a highly-optimized @code{strstr} function.
|
Stephen R. van den Berg contributed a highly-optimized @code{strstr} function.
|
||||||
|
|
||||||
|
|
|
@ -64,12 +64,6 @@ is this null pointer.
|
||||||
For the command @samp{cat foo bar}, @var{argc} is 3 and @var{argv} has
|
For the command @samp{cat foo bar}, @var{argc} is 3 and @var{argv} has
|
||||||
three elements, @code{"cat"}, @code{"foo"} and @code{"bar"}.
|
three elements, @code{"cat"}, @code{"foo"} and @code{"bar"}.
|
||||||
|
|
||||||
If the syntax for the command line arguments to your program is simple
|
|
||||||
enough, you can simply pick the arguments off from @var{argv} by hand.
|
|
||||||
But unless your program takes a fixed number of arguments, or all of the
|
|
||||||
arguments are interpreted in the same way (as file names, for example),
|
|
||||||
you are usually better off using @code{getopt} to do the parsing.
|
|
||||||
|
|
||||||
In Unix systems you can define @code{main} a third way, using three arguments:
|
In Unix systems you can define @code{main} a third way, using three arguments:
|
||||||
|
|
||||||
@smallexample
|
@smallexample
|
||||||
|
@ -84,13 +78,7 @@ allow this three-argument form, so to be portable it is best to write
|
||||||
|
|
||||||
@menu
|
@menu
|
||||||
* Argument Syntax:: By convention, options start with a hyphen.
|
* Argument Syntax:: By convention, options start with a hyphen.
|
||||||
* Parsing Options:: The @code{getopt} function.
|
* Parsing Program Arguments:: Ways to parse program options and arguments.
|
||||||
* Example of Getopt:: An example of parsing options with @code{getopt}.
|
|
||||||
* Long Options:: GNU suggests utilities accept long-named options.
|
|
||||||
Here is how to do that.
|
|
||||||
* Long Option Example:: An example of using @code{getopt_long}.
|
|
||||||
* Suboptions:: Some programs need more detailed options.
|
|
||||||
* Suboptions Example:: This shows how it could be done for @code{mount}.
|
|
||||||
@end menu
|
@end menu
|
||||||
|
|
||||||
@node Argument Syntax
|
@node Argument Syntax
|
||||||
|
@ -100,7 +88,8 @@ allow this three-argument form, so to be portable it is best to write
|
||||||
@cindex command argument syntax
|
@cindex command argument syntax
|
||||||
|
|
||||||
POSIX recommends these conventions for command line arguments.
|
POSIX recommends these conventions for command line arguments.
|
||||||
@code{getopt} (@pxref{Parsing Options}) makes it easy to implement them.
|
@code{getopt} (@pxref{Getopt}) and @code{argp_parse} (@pxref{Argp}) make
|
||||||
|
it easy to implement them.
|
||||||
|
|
||||||
@itemize @bullet
|
@itemize @bullet
|
||||||
@item
|
@item
|
||||||
|
@ -127,14 +116,14 @@ other words, the whitespace separating them is optional.) Thus,
|
||||||
@item
|
@item
|
||||||
Options typically precede other non-option arguments.
|
Options typically precede other non-option arguments.
|
||||||
|
|
||||||
The implementation of @code{getopt} in the GNU C library normally makes
|
The implementations of @code{getopt} and @code{argp_parse} in the GNU C
|
||||||
it appear as if all the option arguments were specified before all the
|
library normally make it appear as if all the option arguments were
|
||||||
non-option arguments for the purposes of parsing, even if the user of
|
specified before all the non-option arguments for the purposes of
|
||||||
your program intermixed option and non-option arguments. It does this
|
parsing, even if the user of your program intermixed option and
|
||||||
by reordering the elements of the @var{argv} array. This behavior is
|
non-option arguments. They do this by reordering the elements of the
|
||||||
nonstandard; if you want to suppress it, define the
|
@var{argv} array. This behavior is nonstandard; if you want to suppress
|
||||||
@code{_POSIX_OPTION_ORDER} environment variable. @xref{Standard
|
it, define the @code{_POSIX_OPTION_ORDER} environment variable.
|
||||||
Environment}.
|
@xref{Standard Environment}.
|
||||||
|
|
||||||
@item
|
@item
|
||||||
The argument @samp{--} terminates all options; any following arguments
|
The argument @samp{--} terminates all options; any following arguments
|
||||||
|
@ -164,255 +153,41 @@ accept an argument that is itself optional.
|
||||||
Eventually, the GNU system will provide completion for long option names
|
Eventually, the GNU system will provide completion for long option names
|
||||||
in the shell.
|
in the shell.
|
||||||
|
|
||||||
@node Parsing Options
|
@node Parsing Program Arguments
|
||||||
@subsection Parsing Program Options
|
@subsection Parsing Program Arguments
|
||||||
|
|
||||||
@cindex program arguments, parsing
|
@cindex program arguments, parsing
|
||||||
@cindex command arguments, parsing
|
@cindex command arguments, parsing
|
||||||
@cindex parsing program arguments
|
@cindex parsing program arguments
|
||||||
|
If the syntax for the command line arguments to your program is simple
|
||||||
|
enough, you can simply pick the arguments off from @var{argv} by hand.
|
||||||
|
But unless your program takes a fixed number of arguments, or all of the
|
||||||
|
arguments are interpreted in the same way (as file names, for example),
|
||||||
|
you are usually better off using @code{getopt} (@pxref{Getopt}) or
|
||||||
|
@code{argp_parse} (@pxref{Argp}) to do the parsing.
|
||||||
|
|
||||||
Here are the details about how to call the @code{getopt} function. To
|
@code{getopt} is more standard (the short-option only version of it is a
|
||||||
use this facility, your program must include the header file
|
part of the POSIX standard), but using @code{argp_parse} is often
|
||||||
@file{unistd.h}.
|
easier, both for very simple and very complex option structures, because
|
||||||
@pindex unistd.h
|
it does more of the dirty work for you.
|
||||||
|
|
||||||
@comment unistd.h
|
@menu
|
||||||
@comment POSIX.2
|
* Getopt:: Parsing program options using @code{getopt}.
|
||||||
@deftypevar int opterr
|
* Argp:: Parsing program options using @code{argp_parse}.
|
||||||
If the value of this variable is nonzero, then @code{getopt} prints an
|
* Suboptions:: Some programs need more detailed options.
|
||||||
error message to the standard error stream if it encounters an unknown
|
* Suboptions Example:: This shows how it could be done for @code{mount}.
|
||||||
option character or an option with a missing required argument. This is
|
@end menu
|
||||||
the default behavior. If you set this variable to zero, @code{getopt}
|
|
||||||
does not print any messages, but it still returns the character @code{?}
|
|
||||||
to indicate an error.
|
|
||||||
@end deftypevar
|
|
||||||
|
|
||||||
@comment unistd.h
|
@c Getopt and argp start at the @section level so that there's
|
||||||
@comment POSIX.2
|
@c enough room for their internal hierarchy (mostly a problem with
|
||||||
@deftypevar int optopt
|
@c argp). -Miles
|
||||||
When @code{getopt} encounters an unknown option character or an option
|
|
||||||
with a missing required argument, it stores that option character in
|
|
||||||
this variable. You can use this for providing your own diagnostic
|
|
||||||
messages.
|
|
||||||
@end deftypevar
|
|
||||||
|
|
||||||
@comment unistd.h
|
@include getopt.texi
|
||||||
@comment POSIX.2
|
@include argp.texi
|
||||||
@deftypevar int optind
|
|
||||||
This variable is set by @code{getopt} to the index of the next element
|
|
||||||
of the @var{argv} array to be processed. Once @code{getopt} has found
|
|
||||||
all of the option arguments, you can use this variable to determine
|
|
||||||
where the remaining non-option arguments begin. The initial value of
|
|
||||||
this variable is @code{1}.
|
|
||||||
@end deftypevar
|
|
||||||
|
|
||||||
@comment unistd.h
|
@node Suboptions, Suboptions Example, Argp, Parsing Program Arguments
|
||||||
@comment POSIX.2
|
@c This is a @section so that it's at the same level as getopt and argp
|
||||||
@deftypevar {char *} optarg
|
@section Parsing of Suboptions
|
||||||
This variable is set by @code{getopt} to point at the value of the
|
|
||||||
option argument, for those options that accept arguments.
|
|
||||||
@end deftypevar
|
|
||||||
|
|
||||||
@comment unistd.h
|
|
||||||
@comment POSIX.2
|
|
||||||
@deftypefun int getopt (int @var{argc}, char **@var{argv}, const char *@var{options})
|
|
||||||
The @code{getopt} function gets the next option argument from the
|
|
||||||
argument list specified by the @var{argv} and @var{argc} arguments.
|
|
||||||
Normally these values come directly from the arguments received by
|
|
||||||
@code{main}.
|
|
||||||
|
|
||||||
The @var{options} argument is a string that specifies the option
|
|
||||||
characters that are valid for this program. An option character in this
|
|
||||||
string can be followed by a colon (@samp{:}) to indicate that it takes a
|
|
||||||
required argument.
|
|
||||||
|
|
||||||
If the @var{options} argument string begins with a hyphen (@samp{-}), this
|
|
||||||
is treated specially. It permits arguments that are not options to be
|
|
||||||
returned as if they were associated with option character @samp{\0}.
|
|
||||||
|
|
||||||
The @code{getopt} function returns the option character for the next
|
|
||||||
command line option. When no more option arguments are available, it
|
|
||||||
returns @code{-1}. There may still be more non-option arguments; you
|
|
||||||
must compare the external variable @code{optind} against the @var{argc}
|
|
||||||
parameter to check this.
|
|
||||||
|
|
||||||
If the option has an argument, @code{getopt} returns the argument by
|
|
||||||
storing it in the variable @var{optarg}. You don't ordinarily need to
|
|
||||||
copy the @code{optarg} string, since it is a pointer into the original
|
|
||||||
@var{argv} array, not into a static area that might be overwritten.
|
|
||||||
|
|
||||||
If @code{getopt} finds an option character in @var{argv} that was not
|
|
||||||
included in @var{options}, or a missing option argument, it returns
|
|
||||||
@samp{?} and sets the external variable @code{optopt} to the actual
|
|
||||||
option character. If the first character of @var{options} is a colon
|
|
||||||
(@samp{:}), then @code{getopt} returns @samp{:} instead of @samp{?} to
|
|
||||||
indicate a missing option argument. In addition, if the external
|
|
||||||
variable @code{opterr} is nonzero (which is the default), @code{getopt}
|
|
||||||
prints an error message.
|
|
||||||
@end deftypefun
|
|
||||||
|
|
||||||
@node Example of Getopt
|
|
||||||
@subsection Example of Parsing Arguments with @code{getopt}
|
|
||||||
|
|
||||||
Here is an example showing how @code{getopt} is typically used. The
|
|
||||||
key points to notice are:
|
|
||||||
|
|
||||||
@itemize @bullet
|
|
||||||
@item
|
|
||||||
Normally, @code{getopt} is called in a loop. When @code{getopt} returns
|
|
||||||
@code{-1}, indicating no more options are present, the loop terminates.
|
|
||||||
|
|
||||||
@item
|
|
||||||
A @code{switch} statement is used to dispatch on the return value from
|
|
||||||
@code{getopt}. In typical use, each case just sets a variable that
|
|
||||||
is used later in the program.
|
|
||||||
|
|
||||||
@item
|
|
||||||
A second loop is used to process the remaining non-option arguments.
|
|
||||||
@end itemize
|
|
||||||
|
|
||||||
@smallexample
|
|
||||||
@include testopt.c.texi
|
|
||||||
@end smallexample
|
|
||||||
|
|
||||||
Here are some examples showing what this program prints with different
|
|
||||||
combinations of arguments:
|
|
||||||
|
|
||||||
@smallexample
|
|
||||||
% testopt
|
|
||||||
aflag = 0, bflag = 0, cvalue = (null)
|
|
||||||
|
|
||||||
% testopt -a -b
|
|
||||||
aflag = 1, bflag = 1, cvalue = (null)
|
|
||||||
|
|
||||||
% testopt -ab
|
|
||||||
aflag = 1, bflag = 1, cvalue = (null)
|
|
||||||
|
|
||||||
% testopt -c foo
|
|
||||||
aflag = 0, bflag = 0, cvalue = foo
|
|
||||||
|
|
||||||
% testopt -cfoo
|
|
||||||
aflag = 0, bflag = 0, cvalue = foo
|
|
||||||
|
|
||||||
% testopt arg1
|
|
||||||
aflag = 0, bflag = 0, cvalue = (null)
|
|
||||||
Non-option argument arg1
|
|
||||||
|
|
||||||
% testopt -a arg1
|
|
||||||
aflag = 1, bflag = 0, cvalue = (null)
|
|
||||||
Non-option argument arg1
|
|
||||||
|
|
||||||
% testopt -c foo arg1
|
|
||||||
aflag = 0, bflag = 0, cvalue = foo
|
|
||||||
Non-option argument arg1
|
|
||||||
|
|
||||||
% testopt -a -- -b
|
|
||||||
aflag = 1, bflag = 0, cvalue = (null)
|
|
||||||
Non-option argument -b
|
|
||||||
|
|
||||||
% testopt -a -
|
|
||||||
aflag = 1, bflag = 0, cvalue = (null)
|
|
||||||
Non-option argument -
|
|
||||||
@end smallexample
|
|
||||||
|
|
||||||
@node Long Options
|
|
||||||
@subsection Parsing Long Options
|
|
||||||
|
|
||||||
To accept GNU-style long options as well as single-character options,
|
|
||||||
use @code{getopt_long} instead of @code{getopt}. This function is
|
|
||||||
declared in @file{getopt.h}, not @file{unistd.h}. You should make every
|
|
||||||
program accept long options if it uses any options, for this takes
|
|
||||||
little extra work and helps beginners remember how to use the program.
|
|
||||||
|
|
||||||
@comment getopt.h
|
|
||||||
@comment GNU
|
|
||||||
@deftp {Data Type} {struct option}
|
|
||||||
This structure describes a single long option name for the sake of
|
|
||||||
@code{getopt_long}. The argument @var{longopts} must be an array of
|
|
||||||
these structures, one for each long option. Terminate the array with an
|
|
||||||
element containing all zeros.
|
|
||||||
|
|
||||||
The @code{struct option} structure has these fields:
|
|
||||||
|
|
||||||
@table @code
|
|
||||||
@item const char *name
|
|
||||||
This field is the name of the option. It is a string.
|
|
||||||
|
|
||||||
@item int has_arg
|
|
||||||
This field says whether the option takes an argument. It is an integer,
|
|
||||||
and there are three legitimate values: @w{@code{no_argument}},
|
|
||||||
@code{required_argument} and @code{optional_argument}.
|
|
||||||
|
|
||||||
@item int *flag
|
|
||||||
@itemx int val
|
|
||||||
These fields control how to report or act on the option when it occurs.
|
|
||||||
|
|
||||||
If @code{flag} is a null pointer, then the @code{val} is a value which
|
|
||||||
identifies this option. Often these values are chosen to uniquely
|
|
||||||
identify particular long options.
|
|
||||||
|
|
||||||
If @code{flag} is not a null pointer, it should be the address of an
|
|
||||||
@code{int} variable which is the flag for this option. The value in
|
|
||||||
@code{val} is the value to store in the flag to indicate that the option
|
|
||||||
was seen.
|
|
||||||
@end table
|
|
||||||
@end deftp
|
|
||||||
|
|
||||||
@comment getopt.h
|
|
||||||
@comment GNU
|
|
||||||
@deftypefun int getopt_long (int @var{argc}, char **@var{argv}, const char *@var{shortopts}, struct option *@var{longopts}, int *@var{indexptr})
|
|
||||||
Decode options from the vector @var{argv} (whose length is @var{argc}).
|
|
||||||
The argument @var{shortopts} describes the short options to accept, just as
|
|
||||||
it does in @code{getopt}. The argument @var{longopts} describes the long
|
|
||||||
options to accept (see above).
|
|
||||||
|
|
||||||
When @code{getopt_long} encounters a short option, it does the same
|
|
||||||
thing that @code{getopt} would do: it returns the character code for the
|
|
||||||
option, and stores the options argument (if it has one) in @code{optarg}.
|
|
||||||
|
|
||||||
When @code{getopt_long} encounters a long option, it takes actions based
|
|
||||||
on the @code{flag} and @code{val} fields of the definition of that
|
|
||||||
option.
|
|
||||||
|
|
||||||
If @code{flag} is a null pointer, then @code{getopt_long} returns the
|
|
||||||
contents of @code{val} to indicate which option it found. You should
|
|
||||||
arrange distinct values in the @code{val} field for options with
|
|
||||||
different meanings, so you can decode these values after
|
|
||||||
@code{getopt_long} returns. If the long option is equivalent to a short
|
|
||||||
option, you can use the short option's character code in @code{val}.
|
|
||||||
|
|
||||||
If @code{flag} is not a null pointer, that means this option should just
|
|
||||||
set a flag in the program. The flag is a variable of type @code{int}
|
|
||||||
that you define. Put the address of the flag in the @code{flag} field.
|
|
||||||
Put in the @code{val} field the value you would like this option to
|
|
||||||
store in the flag. In this case, @code{getopt_long} returns @code{0}.
|
|
||||||
|
|
||||||
For any long option, @code{getopt_long} tells you the index in the array
|
|
||||||
@var{longopts} of the options definition, by storing it into
|
|
||||||
@code{*@var{indexptr}}. You can get the name of the option with
|
|
||||||
@code{@var{longopts}[*@var{indexptr}].name}. So you can distinguish among
|
|
||||||
long options either by the values in their @code{val} fields or by their
|
|
||||||
indices. You can also distinguish in this way among long options that
|
|
||||||
set flags.
|
|
||||||
|
|
||||||
When a long option has an argument, @code{getopt_long} puts the argument
|
|
||||||
value in the variable @code{optarg} before returning. When the option
|
|
||||||
has no argument, the value in @code{optarg} is a null pointer. This is
|
|
||||||
how you can tell whether an optional argument was supplied.
|
|
||||||
|
|
||||||
When @code{getopt_long} has no more options to handle, it returns
|
|
||||||
@code{-1}, and leaves in the variable @code{optind} the index in
|
|
||||||
@var{argv} of the next remaining argument.
|
|
||||||
@end deftypefun
|
|
||||||
|
|
||||||
@node Long Option Example
|
|
||||||
@subsection Example of Parsing Long Options
|
|
||||||
|
|
||||||
@smallexample
|
|
||||||
@include longopt.c.texi
|
|
||||||
@end smallexample
|
|
||||||
|
|
||||||
@node Suboptions
|
|
||||||
@subsection Parsing of Suboptions
|
|
||||||
|
|
||||||
Having a single level of options is sometimes not enough. There might
|
Having a single level of options is sometimes not enough. There might
|
||||||
be too many options which have to be available or a set of options is
|
be too many options which have to be available or a set of options is
|
||||||
|
@ -452,7 +227,7 @@ possible value is returned in @var{valuep} and the return value of the
|
||||||
function is @samp{-1}.
|
function is @samp{-1}.
|
||||||
@end deftypefun
|
@end deftypefun
|
||||||
|
|
||||||
@node Suboptions Example
|
@node Suboptions Example, , Suboptions, Parsing Program Arguments
|
||||||
@subsection Parsing of Suboptions Example
|
@subsection Parsing of Suboptions Example
|
||||||
|
|
||||||
The code which might appear in the @code{mount}(8) program is a perfect
|
The code which might appear in the @code{mount}(8) program is a perfect
|
||||||
|
@ -699,7 +474,8 @@ This specifies what locale to use for formatting date/time values.
|
||||||
@cindex _POSIX_OPTION_ORDER environment variable.
|
@cindex _POSIX_OPTION_ORDER environment variable.
|
||||||
|
|
||||||
If this environment variable is defined, it suppresses the usual
|
If this environment variable is defined, it suppresses the usual
|
||||||
reordering of command line arguments by @code{getopt}. @xref{Argument Syntax}.
|
reordering of command line arguments by @code{getopt} and
|
||||||
|
@code{argp_parse}. @xref{Argument Syntax}.
|
||||||
|
|
||||||
@c !!! GNU also has COREFILE, CORESERVER, EXECSERVERS
|
@c !!! GNU also has COREFILE, CORESERVER, EXECSERVERS
|
||||||
@end table
|
@end table
|
||||||
|
|
|
@ -1,6 +1,6 @@
|
||||||
# awk script to create summary.texinfo from the library texinfo files.
|
# awk script to create summary.texinfo from the library texinfo files.
|
||||||
|
|
||||||
# Copyright (C) 1992, 1993 Free Software Foundation, Inc.
|
# Copyright (C) 1992, 1993, 1997 Free Software Foundation, Inc.
|
||||||
# This file is part of the GNU C Library.
|
# This file is part of the GNU C Library.
|
||||||
|
|
||||||
# The GNU C Library is free software; you can redistribute it and/or
|
# The GNU C Library is free software; you can redistribute it and/or
|
||||||
|
@ -86,6 +86,7 @@ print "@c This file is generated by summary.awk from the Texinfo sources."
|
||||||
$1 == "@node" { node=$2;
|
$1 == "@node" { node=$2;
|
||||||
for (i = 3; i <= NF; ++i)
|
for (i = 3; i <= NF; ++i)
|
||||||
{ node=node " " $i; if ( $i ~ /,/ ) break; }
|
{ node=node " " $i; if ( $i ~ /,/ ) break; }
|
||||||
|
sub (/,[, ]*$/, "", node);
|
||||||
}
|
}
|
||||||
|
|
||||||
$1 == "@comment" && $2 ~ /\.h$/ { header="@file{" $2 "}";
|
$1 == "@comment" && $2 ~ /\.h$/ { header="@file{" $2 "}";
|
||||||
|
|
|
@ -1,5 +1,5 @@
|
||||||
%% TeX macros to handle Texinfo files.
|
%% TeX macros to handle Texinfo files.
|
||||||
%% $Id: texinfo.tex,v 2.200 1997/05/26 22:19:32 drepper Exp $
|
%% $Id: texinfo.tex,v 2.201 1997/06/05 11:28:54 drepper Exp $
|
||||||
|
|
||||||
% Copyright (C) 1985, 86, 88, 90, 91, 92, 93,
|
% Copyright (C) 1985, 86, 88, 90, 91, 92, 93,
|
||||||
% 94, 95, 96, 97 Free Software Foundation, Inc.
|
% 94, 95, 96, 97 Free Software Foundation, Inc.
|
||||||
|
@ -36,7 +36,7 @@
|
||||||
|
|
||||||
% This automatically updates the version number based on RCS.
|
% This automatically updates the version number based on RCS.
|
||||||
\def\deftexinfoversion$#1: #2 ${\def\texinfoversion{#2}}
|
\def\deftexinfoversion$#1: #2 ${\def\texinfoversion{#2}}
|
||||||
\deftexinfoversion$Revision: 2.200 $
|
\deftexinfoversion$Revision: 2.201 $
|
||||||
\message{Loading texinfo package [Version \texinfoversion]:}
|
\message{Loading texinfo package [Version \texinfoversion]:}
|
||||||
|
|
||||||
% If in a .fmt file, print the version number
|
% If in a .fmt file, print the version number
|
||||||
|
@ -1041,8 +1041,9 @@ where each line of input produces a line of output.}
|
||||||
% We don't need math for this one.
|
% We don't need math for this one.
|
||||||
\def\ttsl{\tenttsl}
|
\def\ttsl{\tenttsl}
|
||||||
|
|
||||||
%% Try out Computer Modern fonts at \magstephalf
|
% Use Computer Modern fonts at \magstephalf (11pt).
|
||||||
\let\mainmagstep=\magstephalf
|
\newcount\mainmagstep
|
||||||
|
\mainmagstep=\magstephalf
|
||||||
|
|
||||||
% Set the font macro #1 to the font named #2, adding on the
|
% Set the font macro #1 to the font named #2, adding on the
|
||||||
% specified font prefix (normally `cm').
|
% specified font prefix (normally `cm').
|
||||||
|
@ -1337,8 +1338,9 @@ where each line of input produces a line of output.}
|
||||||
\else{\tclose{\ttsl\look}}\fi
|
\else{\tclose{\ttsl\look}}\fi
|
||||||
\else{\tclose{\ttsl\look}}\fi}
|
\else{\tclose{\ttsl\look}}\fi}
|
||||||
|
|
||||||
% @url, @email. Quotes do not seem necessary.
|
% @url, @uref, @email. Quotes do not seem necessary.
|
||||||
\let\url=\code % perhaps include a hypertex \special eventually
|
\let\url=\code % perhaps include a hypertex \special eventually
|
||||||
|
\let\uref=\code
|
||||||
% rms does not like the angle brackets --karl, 17may97.
|
% rms does not like the angle brackets --karl, 17may97.
|
||||||
%\def\email#1{$\langle${\tt #1}$\rangle$}
|
%\def\email#1{$\langle${\tt #1}$\rangle$}
|
||||||
\let\email=\code
|
\let\email=\code
|
||||||
|
|
|
@ -0,0 +1 @@
|
||||||
|
#include <stdlib/monetary.h>
|
|
@ -0,0 +1 @@
|
||||||
|
#include <misc/sysexits.h>
|
Loading…
Reference in New Issue