465 lines
14 KiB
Groff
465 lines
14 KiB
Groff
.TH GETOPT 1 "May 31, 1997" Linux ""
|
|
.SH NAME
|
|
getopt \- parse command options (enhanced)
|
|
.SH SYNOPSIS
|
|
.B getopt
|
|
.I optstring parameters
|
|
.br
|
|
.B getopt
|
|
.RI [ options ]
|
|
.RB [ \-\- ]
|
|
.I optstring parameters
|
|
.br
|
|
.B getopt
|
|
.RI [ options ]
|
|
.BR \-o | \-\-options
|
|
.I optstring
|
|
.RI [ options ]
|
|
.RB [ \-\- ]
|
|
.I parameters
|
|
.SH DESCRIPTION
|
|
.B getopt
|
|
is used to break up
|
|
.RI ( parse )
|
|
options in command lines for easy parsing by
|
|
shell procedures, and to check for legal options.
|
|
It uses the
|
|
.SM GNU
|
|
.BR getopt (3)
|
|
routines to do this.
|
|
|
|
The parameters
|
|
.B getopt
|
|
is called with can be divided into two parts: options
|
|
which modify the way getopt will parse
|
|
.RI ( options
|
|
and
|
|
.BR \-o | \-\-options
|
|
.I optstring
|
|
in the
|
|
.BR SYNOPSIS ),
|
|
and the parameters which are to be
|
|
parsed
|
|
.RI ( parameters
|
|
in the
|
|
.BR SYNOPSIS ).
|
|
The second part will start at the first non\-option parameter
|
|
that is not an option argument, or after the first occurrence of
|
|
.RB ` \-\- '.
|
|
If no
|
|
.RB ` \-o '
|
|
or
|
|
.RB ` \-\-options '
|
|
option is found in the first part, the first
|
|
parameter of the second part is used as the short options string.
|
|
|
|
If the environment variable
|
|
.B GETOPT_COMPATIBLE
|
|
is set, or if its first parameter
|
|
is not an option (does not start with a
|
|
.RB ` \- ',
|
|
this is the first format in the
|
|
.BR SYNOPSIS),
|
|
.B getopt
|
|
will generate output that is compatible with that of other versions of
|
|
.BR getopt (1).
|
|
It will still do parameter shuffling and recognize optional
|
|
arguments (see section
|
|
.B COMPATIBILITY
|
|
for more information).
|
|
|
|
Traditional implementations of
|
|
.BR getopt (1)
|
|
are unable to cope with whitespace and other (shell\-specific) special characters
|
|
in arguments and non\-option parameters. To solve this problem, this
|
|
implementation can generate
|
|
quoted output which must once again be interpreted by the shell (usually
|
|
by using the
|
|
.B eval
|
|
command). This has the effect of preserving those characters, but
|
|
you must call
|
|
.B getopt
|
|
in a way that is no longer compatible with other versions (the second
|
|
or third format in the
|
|
.BR SYNOPSIS ).
|
|
To determine whether this enhanced version of
|
|
.BR getopt (1)
|
|
is installed, a special test option
|
|
.RB ( \-T )
|
|
can be used.
|
|
.SH OPTIONS
|
|
.TP
|
|
.BR \-a , " \-\-alternative"
|
|
Allow long options to start with a single
|
|
.RB ` \- '.
|
|
.TP
|
|
.BR \-h , " \-\-help"
|
|
Output a small usage guide and exit successfully. No other output is generated.
|
|
.TP
|
|
.BR \-l , " \-\-longoptions \fIlongopts\fP"
|
|
The long (multi\-character) options to be recognized.
|
|
More than one option name
|
|
may be specified at once, by separating the names with commas. This option
|
|
may be given more than once, the
|
|
.I longopts
|
|
are cumulative.
|
|
Each long option name
|
|
in
|
|
.I longopts
|
|
may be followed by one colon to indicate it has a required argument, and by two colons to indicate it has an optional argument.
|
|
.TP
|
|
.BR \-n , " \-\-name \fIprogname\fP"
|
|
The name that will be used by the
|
|
.BR getopt (3)
|
|
routines when it reports errors. Note that errors of
|
|
.BR getopt (1)
|
|
are still reported as coming from getopt.
|
|
.TP
|
|
.BR \-o , " \-\-options \fIshortopts\fP"
|
|
The short (one\-character) options to be recognized. If this option is not
|
|
found, the first parameter of
|
|
.B getopt
|
|
that does not start with
|
|
a
|
|
.RB ` \- '
|
|
(and is not an option argument) is used as the short options string.
|
|
Each short option character
|
|
in
|
|
.I shortopts
|
|
may be followed by one colon to indicate it has a required argument,
|
|
and by two colons to indicate it has an optional argument.
|
|
The first character of shortopts may be
|
|
.RB ` + '
|
|
or
|
|
.RB ` \- '
|
|
to influence the way
|
|
options are parsed and output is generated (see section
|
|
.B SCANNING MODES
|
|
for details).
|
|
.TP
|
|
.BR \-q , " \-\-quiet"
|
|
Disable error reporting by getopt(3).
|
|
.TP
|
|
.BR \-Q , " \-\-quiet\-output"
|
|
Do not generate normal output. Errors are still reported by
|
|
.BR getopt (3),
|
|
unless you also use
|
|
.IR \-q .
|
|
.TP
|
|
.BR \-s , " \-\-shell \fIshell\fP"
|
|
Set quoting conventions to those of shell. If no \-s argument is found,
|
|
the
|
|
.SM BASH
|
|
conventions are used. Valid arguments are currently
|
|
.RB ` sh '
|
|
.RB ` bash ',
|
|
.RB ` csh ',
|
|
and
|
|
.RB ` tcsh '.
|
|
.TP
|
|
.BR \-u , " \-\-unquoted"
|
|
Do not quote the output. Note that whitespace and special (shell\-dependent)
|
|
characters can cause havoc in this mode (like they do with other
|
|
.BR getopt (1)
|
|
implementations).
|
|
.TP
|
|
.BR \-T , " \-\-test"
|
|
Test if your
|
|
.BR getopt (1)
|
|
is this enhanced version or an old version. This generates no output,
|
|
and sets the error status to 4. Other implementations of
|
|
.BR getopt (1),
|
|
and this version if the environment variable
|
|
.B GETOPT_COMPATIBLE
|
|
is set,
|
|
will return
|
|
.RB ` \-\- '
|
|
and error status 0.
|
|
.TP
|
|
.BR \-V , " \-\-version"
|
|
Output version information and exit successfully. No other output is generated.
|
|
.SH PARSING
|
|
This section specifies the format of the second part of the parameters of
|
|
.B getopt
|
|
(the
|
|
.I parameters
|
|
in the
|
|
.BR SYNOPSIS ).
|
|
The next section
|
|
.RB ( OUTPUT )
|
|
describes the output that is
|
|
generated. These parameters were typically the parameters a shell function
|
|
was called with.
|
|
Care must be taken that each parameter the shell function was
|
|
called with corresponds to exactly one parameter in the parameter list of
|
|
.B getopt
|
|
(see the
|
|
.BR EXAMPLES ).
|
|
All parsing is done by the GNU
|
|
.BR getopt (3)
|
|
routines.
|
|
|
|
The parameters are parsed from left to right. Each parameter is classified as a
|
|
short option, a long option, an argument to an option,
|
|
or a non\-option parameter.
|
|
|
|
A simple short option is a
|
|
.RB ` \- '
|
|
followed by a short option character. If
|
|
the option has a required argument, it may be written directly after the option
|
|
character or as the next parameter (ie. separated by whitespace on the
|
|
command line). If the
|
|
option has an optional argument, it must be written directly after the
|
|
option character if present.
|
|
|
|
It is possible to specify several short options after one
|
|
.RB ` \- ',
|
|
as long as all (except possibly the last) do not have required or optional
|
|
arguments.
|
|
|
|
A long option normally begins with
|
|
.RB ` \-\- '
|
|
followed by the long option name.
|
|
If the option has a required argument, it may be written directly after
|
|
the long option name, separated by
|
|
.RB ` = ',
|
|
or as the next argument (ie. separated by whitespace on the command line).
|
|
If the option has an optional argument, it must
|
|
be written directly after the long option name, separated by
|
|
.RB ` = ',
|
|
if present (if you add the
|
|
.RB ` = '
|
|
but nothing behind it, it is interpreted
|
|
as if no argument was present; this is a slight bug, see the
|
|
.BR BUGS ).
|
|
Long options may be abbreviated, as long as the abbreviation is not
|
|
ambiguous.
|
|
|
|
Each parameter not starting with a
|
|
.RB ` \- ',
|
|
and not a required argument of
|
|
a previous option, is a non\-option parameter. Each parameter after
|
|
a
|
|
.RB ` \-\- '
|
|
parameter is always interpreted as a non\-option parameter.
|
|
If the environment variable
|
|
.B POSIXLY_CORRECT
|
|
is set, or if the short
|
|
option string started with a
|
|
.RB ` + ',
|
|
all remaining parameters are interpreted
|
|
as non\-option parameters as soon as the first non\-option parameter is
|
|
found.
|
|
.SH OUTPUT
|
|
Output is generated for each element described in the previous section.
|
|
Output is done
|
|
in the same order as the elements are specified in the input, except
|
|
for non\-option parameters. Output can be done in
|
|
.I compatible
|
|
.RI ( unquoted )
|
|
mode, or in such way that whitespace and other special characters within
|
|
arguments and non\-option parameters are preserved (see
|
|
.BR QUOTING ).
|
|
When the output is processed in the shell script, it will seem to be
|
|
composed of distinct elements that can be processed one by one (by using the
|
|
shift command in most shell languages). This is imperfect in unquoted mode,
|
|
as elements can be split at unexpected places if they contain whitespace
|
|
or special characters.
|
|
|
|
If there are problems parsing the parameters, for example because a
|
|
required argument is not found or an option is not recognized, an error
|
|
will be reported on stderr, there will be no output for the offending
|
|
element, and a non\-zero error status is returned.
|
|
|
|
For a short option, a single
|
|
.RB ` \- '
|
|
and the option character are generated
|
|
as one parameter. If the option has an argument, the next
|
|
parameter will be the argument. If the option takes an optional argument,
|
|
but none was found, the next parameter will be generated but be empty in
|
|
quoting mode,
|
|
but no second parameter will be generated in unquoted (compatible) mode.
|
|
Note that many other
|
|
.BR getopt (1)
|
|
implementations do not support optional arguments.
|
|
|
|
If several short options were specified after a single
|
|
.RB ` \- ',
|
|
each will be present in the output as a separate parameter.
|
|
|
|
For a long option,
|
|
.RB ` \-\- '
|
|
and the full option name are generated as one
|
|
parameter. This is done regardless whether the option was abbreviated or
|
|
specified with a single
|
|
.RB ` \- '
|
|
in the input. Arguments are handled as with short options.
|
|
|
|
Normally, no non\-option parameters output is generated until all options
|
|
and their arguments have been generated. Then
|
|
.RB ` \-\- '
|
|
is generated as a
|
|
single parameter, and after it the non\-option parameters in the order
|
|
they were found, each as a separate parameter.
|
|
Only if the first character of the short options string was a
|
|
.RB ` \- ',
|
|
non\-option parameter output is generated at the place they are found in the
|
|
input (this is not supported if the first format of the
|
|
.B SYNOPSIS
|
|
is used; in that case all preceding occurrences of
|
|
.RB ` \- '
|
|
and
|
|
.RB ` + '
|
|
are ignored).
|
|
.SH QUOTING
|
|
In compatible mode, whitespace or 'special' characters in arguments or
|
|
non\-option parameters are not handled correctly. As the output is
|
|
fed to the shell script, the script does not know how it is supposed to break
|
|
the output into separate parameters. To circumvent this
|
|
problem, this implementation offers quoting. The idea is that output
|
|
is generated with quotes around each parameter. When this output is once
|
|
again fed to the shell (usually by a shell
|
|
.B eval
|
|
command), it is split correctly into separate parameters.
|
|
|
|
Quoting is not enabled if the environment variable
|
|
.B GETOPT_COMPATIBLE
|
|
is set, if the first form of the
|
|
.B SYNOPSIS
|
|
is used, or if the option
|
|
.RB ` \-u '
|
|
is found.
|
|
|
|
Different shells use different quoting conventions. You can use the
|
|
.RB ` \-s '
|
|
option to select the shell you are using. The following shells are
|
|
currently supported:
|
|
.RB ` sh ',
|
|
.RB ` bash ',
|
|
.RB ` csh '
|
|
and
|
|
.RB ` tcsh '.
|
|
Actually, only two `flavors' are distinguished: sh\-like quoting conventions
|
|
and csh\-like quoting conventions. Chances are that if you use another shell
|
|
script language, one of these flavors can still be used.
|
|
|
|
.SH "SCANNING MODES"
|
|
The first character of the short options string may be a
|
|
.RB ` \- '
|
|
or a
|
|
.RB ` + '
|
|
to indicate a special scanning mode. If the first calling form
|
|
in the
|
|
.B SYNOPSIS
|
|
is used they are ignored; the environment variable
|
|
.B POSIXLY_CORRECT
|
|
is still examined, though.
|
|
|
|
If the first character is
|
|
.RB ` + ',
|
|
or if the environment variable
|
|
.B POSIXLY_CORRECT
|
|
is set, parsing stops as soon as the first non\-option parameter
|
|
(ie. a parameter that does not start with a
|
|
.RB ` \- ')
|
|
is found that
|
|
is not an option argument. The remaining parameters are all interpreted as
|
|
non\-option parameters.
|
|
|
|
If the first character is a
|
|
.RB ` \- ',
|
|
non\-option parameters are outputted at the place where they are found; in normal
|
|
operation, they are all collected at the end of output after a
|
|
.RB ` \-\- '
|
|
parameter has been generated. Note that this
|
|
.RB ` \-\- '
|
|
parameter is still generated, but it will always be the last parameter in
|
|
this mode.
|
|
.SH COMPATIBILITY
|
|
This version of
|
|
.BR getopt (1)
|
|
is written to be as compatible as possible to
|
|
other versions. Usually you can just replace them with this version
|
|
without any modifications, and with some advantages.
|
|
|
|
If the first character of the first parameter of getopt is not a
|
|
.RB ` \- ',
|
|
getopt goes into compatibility mode. It will interpret its first parameter as
|
|
the string of short options, and all other arguments will be parsed. It
|
|
will still do parameter shuffling (ie. all non\-option parameters are outputted
|
|
at the end), unless the environment variable
|
|
.B POSIXLY_CORRECT
|
|
is set.
|
|
|
|
The environment variable
|
|
.B GETOPT_COMPATIBLE
|
|
forces
|
|
.B getopt
|
|
into compatibility mode. Setting both this environment variable and
|
|
.B POSIXLY_CORRECT
|
|
offers 100% compatibility for `difficult' programs. Usually, though,
|
|
neither is needed.
|
|
|
|
In compatibility mode, leading
|
|
.RB ` \- '
|
|
and
|
|
.RB ` + '
|
|
characters in the short options string are ignored.
|
|
.SH RETURN CODES
|
|
.B getopt
|
|
returns error code
|
|
.B 0
|
|
for successful parsing,
|
|
.B 1
|
|
if
|
|
.BR getopt (3)
|
|
returns errors,
|
|
.B 2
|
|
if it does not understand its own parameters,
|
|
.B 3
|
|
if an internal error occurs like out\-of\-memory, and
|
|
.B 4
|
|
if it is called with
|
|
.BR \-T .
|
|
.SH EXAMPLES
|
|
Example scripts for (ba)sh and (t)csh are provided with the
|
|
.BR getopt (1)
|
|
distribution, and are optionally installed in
|
|
.BR /usr/share/getopt .
|
|
|
|
.SH ENVIRONMENT
|
|
.IP POSIXLY_CORRECT
|
|
This environment variable is examined by the
|
|
.BR getopt (3)
|
|
routines.
|
|
If it is set, parsing stops as soon as a parameter
|
|
is found that is not an option or an option argument. All remaining
|
|
parameters are also interpreted as non\-option parameters, regardless
|
|
whether they start with a
|
|
.RB ` \- '.
|
|
.IP GETOPT_COMPATIBLE
|
|
Forces
|
|
.B getopt
|
|
to use the first calling format as specified in the
|
|
.BR SYNOPSIS .
|
|
.SH BUGS
|
|
.BR getopt (3)
|
|
can parse long options with optional arguments that are given an empty optional
|
|
argument (but can not do this for short options). This
|
|
.BR getopt (1)
|
|
treats optional arguments that are empty as if they were not present.
|
|
|
|
The syntax if you do not want any short option variables at all is
|
|
not very intuitive (you have to set them explicitly to the empty
|
|
string).
|
|
|
|
.SH AUTHOR
|
|
Frodo Looijaard <frodo@frodo.looijaard.name>
|
|
.SH "SEE ALSO"
|
|
.BR getopt (3),
|
|
.BR bash (1),
|
|
.BR tcsh (1).
|
|
.SH AVAILABILITY
|
|
The getopt command is part of the util-linux package and is available from
|
|
ftp://ftp.kernel.org/pub/linux/utils/util-linux/.
|