334 lines
13 KiB
Plaintext
334 lines
13 KiB
Plaintext
@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 *const *@var{argv}, const char *@var{options})
|
|
@safety{@prelim{}@mtunsafe{@mtasurace{:getopt} @mtsenv{}}@asunsafe{@ascuheap{} @ascuintl{} @asulock{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
|
|
@c Swapping elements of passed-in argv may be partial in case of
|
|
@c cancellation. Gettext brings about a whole lot of AS and AC safety
|
|
@c issues. The getopt API involves returning values in the
|
|
@c non-thread-specific optarg variable, which adds another thread-safety
|
|
@c issue. Given print_errors, it may output errors to stderr, which may
|
|
@c self-deadlock, leak locks, or encounter (in a signal handler) or
|
|
@c leave (in case of cancellation) stderr in an inconsistent state.
|
|
@c Various implicit, indirect uses of malloc, in uses of memstream and
|
|
@c asprintf for error-printing, bring about the usual malloc issues.
|
|
@c (The explicit use of malloc in a conditional situation in
|
|
@c _getopt_initialize is never exercised in glibc.)
|
|
@c
|
|
@c _getopt_internal
|
|
@c _getopt_internal_r
|
|
@c gettext
|
|
@c _getopt_initialize
|
|
@c getenv
|
|
@c malloc if USE_NONOPTION_FLAGS, never defined in libc
|
|
@c open_memstream
|
|
@c lockfile, unlockfile, __fxprintf -> stderr
|
|
@c asprintf
|
|
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 an option character is followed by two colons
|
|
(@samp{::}), its argument is optional; this is a GNU extension.
|
|
|
|
@code{getopt} has three ways to deal with options that follow
|
|
non-options @var{argv} elements. The special argument @samp{--} forces
|
|
in all cases the end of option scanning.
|
|
|
|
@itemize @bullet
|
|
@item
|
|
The default is to permute the contents of @var{argv} while scanning it
|
|
so that eventually all the non-options are at the end. This allows
|
|
options to be given in any order, even with programs that were not
|
|
written to expect this.
|
|
|
|
@item
|
|
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{\1}.
|
|
|
|
@item
|
|
POSIX demands the following behavior: The first non-option stops option
|
|
processing. This mode is selected by either setting the environment
|
|
variable @code{POSIXLY_CORRECT} or beginning the @var{options} argument
|
|
string with a plus sign (@samp{+}).
|
|
@end itemize
|
|
|
|
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 *const *@var{argv}, const char *@var{shortopts}, const struct option *@var{longopts}, int *@var{indexptr})
|
|
@safety{@prelim{}@mtunsafe{@mtasurace{:getopt} @mtsenv{}}@asunsafe{@ascuheap{} @ascuintl{} @asulock{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
|
|
@c Same issues as getopt.
|
|
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
|
|
|
|
Since long option names were used before the @code{getopt_long}
|
|
options was invented there are program interfaces which require programs
|
|
to recognize options like @w{@samp{-option value}} instead of
|
|
@w{@samp{--option value}}. To enable these programs to use the GNU
|
|
getopt functionality there is one more function available.
|
|
|
|
@comment getopt.h
|
|
@comment GNU
|
|
@deftypefun int getopt_long_only (int @var{argc}, char *const *@var{argv}, const char *@var{shortopts}, const struct option *@var{longopts}, int *@var{indexptr})
|
|
@safety{@prelim{}@mtunsafe{@mtasurace{:getopt} @mtsenv{}}@asunsafe{@ascuheap{} @ascuintl{} @asulock{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
|
|
@c Same issues as getopt.
|
|
|
|
The @code{getopt_long_only} function is equivalent to the
|
|
@code{getopt_long} function but it allows to specify the user of the
|
|
application to pass long options with only @samp{-} instead of
|
|
@samp{--}. The @samp{--} prefix is still recognized but instead of
|
|
looking through the short options if a @samp{-} is seen it is first
|
|
tried whether this parameter names a long option. If not, it is parsed
|
|
as a short option.
|
|
|
|
Assuming @code{getopt_long_only} is used starting an application with
|
|
|
|
@smallexample
|
|
app -foo
|
|
@end smallexample
|
|
|
|
@noindent
|
|
the @code{getopt_long_only} will first look for a long option named
|
|
@samp{foo}. If this is not found, the short options @samp{f}, @samp{o},
|
|
and again @samp{o} are recognized.
|
|
@end deftypefun
|
|
|
|
@node Getopt Long Option Example
|
|
@subsection Example of Parsing Long Options with @code{getopt_long}
|
|
|
|
@smallexample
|
|
@include longopt.c.texi
|
|
@end smallexample
|