2012-06-02 15:39:40 -05:00
|
|
|
.TH GETOPT "1" "June 2012" "util-linux" "User Commands"
|
2006-12-06 17:25:35 -06:00
|
|
|
.SH NAME
|
|
|
|
getopt \- parse command options (enhanced)
|
|
|
|
.SH SYNOPSIS
|
2012-06-02 15:39:40 -05:00
|
|
|
getopt optstring parameters
|
2009-07-22 04:29:05 -05:00
|
|
|
.br
|
2012-06-02 15:39:40 -05:00
|
|
|
getopt [options] [\-\-] optstring parameters
|
2009-07-22 04:29:05 -05:00
|
|
|
.br
|
2012-06-02 15:39:40 -05:00
|
|
|
getopt [options] \-o|\-\-options optstring [options] [\-\-]
|
2009-07-22 04:29:05 -05:00
|
|
|
.I parameters
|
2006-12-06 17:25:35 -06:00
|
|
|
.SH DESCRIPTION
|
|
|
|
.B getopt
|
2009-07-22 04:29:05 -05:00
|
|
|
is used to break up
|
2006-12-06 17:25:35 -06:00
|
|
|
.RI ( parse )
|
2012-06-02 15:39:40 -05:00
|
|
|
options in command lines for easy parsing by shell procedures, and to
|
|
|
|
check for legal options. It uses the
|
2006-12-06 17:25:35 -06:00
|
|
|
.SM GNU
|
2009-07-22 04:29:05 -05:00
|
|
|
.BR getopt (3)
|
2006-12-06 17:25:35 -06:00
|
|
|
routines to do this.
|
2012-06-02 15:39:40 -05:00
|
|
|
.PP
|
2009-07-22 04:29:05 -05:00
|
|
|
The parameters
|
2006-12-06 17:25:35 -06:00
|
|
|
.B getopt
|
2012-06-02 15:39:40 -05:00
|
|
|
is called with can be divided into two parts: options which modify
|
|
|
|
the way getopt will parse
|
2006-12-06 17:25:35 -06:00
|
|
|
.RI ( options
|
|
|
|
and
|
2009-07-22 04:29:05 -05:00
|
|
|
.BR \-o | \-\-options
|
|
|
|
.I optstring
|
|
|
|
in the
|
|
|
|
.BR SYNOPSIS ),
|
2012-06-02 15:39:40 -05:00
|
|
|
and the parameters which are to be parsed
|
2006-12-06 17:25:35 -06:00
|
|
|
.RI ( parameters
|
2009-07-22 04:29:05 -05:00
|
|
|
in the
|
|
|
|
.BR SYNOPSIS ).
|
2012-06-02 15:39:40 -05:00
|
|
|
The second part will start at the first non\-option parameter that is
|
|
|
|
not an option argument, or after the first occurrence of
|
|
|
|
.RB ' \-\- '.
|
2009-07-22 04:29:05 -05:00
|
|
|
If no
|
2012-06-02 15:39:40 -05:00
|
|
|
.RB ' \-o '
|
2009-07-22 04:29:05 -05:00
|
|
|
or
|
2012-06-02 15:39:40 -05:00
|
|
|
.RB ' \-\-options '
|
|
|
|
option is found in the first part, the first parameter of the second
|
|
|
|
part is used as the short options string.
|
|
|
|
.PP
|
2006-12-06 17:25:35 -06:00
|
|
|
If the environment variable
|
|
|
|
.B GETOPT_COMPATIBLE
|
2012-06-02 15:39:40 -05:00
|
|
|
is set, or if its first parameter is not an option (does not start
|
|
|
|
with a
|
|
|
|
.RB ' \- ',
|
2009-07-22 04:29:05 -05:00
|
|
|
this is the first format in the
|
2012-06-02 15:39:40 -05:00
|
|
|
.BR SYNOPSIS ),
|
2006-12-06 17:25:35 -06:00
|
|
|
.B getopt
|
2009-07-22 04:29:05 -05:00
|
|
|
will generate output that is compatible with that of other versions of
|
|
|
|
.BR getopt (1).
|
2012-06-02 15:39:40 -05:00
|
|
|
It will still do parameter shuffling and recognize optional arguments
|
|
|
|
(see section
|
2006-12-06 17:25:35 -06:00
|
|
|
.B COMPATIBILITY
|
2009-07-22 04:29:05 -05:00
|
|
|
for more information).
|
2012-06-02 15:39:40 -05:00
|
|
|
.PP
|
2006-12-06 17:25:35 -06:00
|
|
|
Traditional implementations of
|
|
|
|
.BR getopt (1)
|
2012-06-02 15:39:40 -05:00
|
|
|
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
|
2006-12-06 17:25:35 -06:00
|
|
|
.B eval
|
2012-06-02 15:39:40 -05:00
|
|
|
command). This has the effect of preserving those characters, but
|
2009-07-22 04:29:05 -05:00
|
|
|
you must call
|
2006-12-06 17:25:35 -06:00
|
|
|
.B getopt
|
2009-07-22 04:29:05 -05:00
|
|
|
in a way that is no longer compatible with other versions (the second
|
|
|
|
or third format in the
|
|
|
|
.BR SYNOPSIS ).
|
2006-12-06 17:25:35 -06:00
|
|
|
To determine whether this enhanced version of
|
|
|
|
.BR getopt (1)
|
|
|
|
is installed, a special test option
|
2009-07-22 04:29:05 -05:00
|
|
|
.RB ( \-T )
|
2006-12-06 17:25:35 -06:00
|
|
|
can be used.
|
|
|
|
.SH OPTIONS
|
2009-07-22 04:29:05 -05:00
|
|
|
.TP
|
|
|
|
.BR \-a , " \-\-alternative"
|
|
|
|
Allow long options to start with a single
|
2012-06-02 15:39:40 -05:00
|
|
|
.RB ' \- '.
|
2009-07-22 04:29:05 -05:00
|
|
|
.TP
|
|
|
|
.BR \-h , " \-\-help"
|
2012-06-02 15:39:40 -05:00
|
|
|
Output a small usage guide and exit successfully. No other output is
|
|
|
|
generated.
|
2009-07-22 04:29:05 -05:00
|
|
|
.TP
|
|
|
|
.BR \-l , " \-\-longoptions \fIlongopts\fP"
|
2012-06-02 15:39:40 -05:00
|
|
|
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
|
2009-07-22 04:29:05 -05:00
|
|
|
.I longopts
|
2012-06-02 15:39:40 -05:00
|
|
|
are cumulative. Each long option name in
|
2009-07-22 04:29:05 -05:00
|
|
|
.I longopts
|
2012-06-02 15:39:40 -05:00
|
|
|
may be followed by one colon to indicate it has a required argument,
|
|
|
|
and by two colons to indicate it has an optional argument.
|
2009-07-22 04:29:05 -05:00
|
|
|
.TP
|
|
|
|
.BR \-n , " \-\-name \fIprogname\fP"
|
|
|
|
The name that will be used by the
|
2006-12-06 17:25:35 -06:00
|
|
|
.BR getopt (3)
|
2012-06-02 15:39:40 -05:00
|
|
|
routines when it reports errors. Note that errors of
|
2006-12-06 17:25:35 -06:00
|
|
|
.BR getopt (1)
|
|
|
|
are still reported as coming from getopt.
|
2009-07-22 04:29:05 -05:00
|
|
|
.TP
|
|
|
|
.BR \-o , " \-\-options \fIshortopts\fP"
|
2012-06-02 15:39:40 -05:00
|
|
|
The short (one\-character) options to be recognized. If this option
|
|
|
|
is not found, the first parameter of
|
2009-07-22 04:29:05 -05:00
|
|
|
.B getopt
|
2012-06-02 15:39:40 -05:00
|
|
|
that does not start with a
|
|
|
|
.RB ' \- '
|
2006-12-06 17:25:35 -06:00
|
|
|
(and is not an option argument) is used as the short options string.
|
2012-06-02 15:39:40 -05:00
|
|
|
Each short option character in
|
2009-07-22 04:29:05 -05:00
|
|
|
.I shortopts
|
2006-12-06 17:25:35 -06:00
|
|
|
may be followed by one colon to indicate it has a required argument,
|
2012-06-02 15:39:40 -05:00
|
|
|
and by two colons to indicate it has an optional argument. The first
|
|
|
|
character of shortopts may be
|
|
|
|
.RB ' + '
|
2006-12-06 17:25:35 -06:00
|
|
|
or
|
2012-06-02 15:39:40 -05:00
|
|
|
.RB ' \- '
|
|
|
|
to influence the way options are parsed and output is generated (see
|
|
|
|
section
|
2006-12-06 17:25:35 -06:00
|
|
|
.B SCANNING MODES
|
|
|
|
for details).
|
2009-07-22 04:29:05 -05:00
|
|
|
.TP
|
|
|
|
.BR \-q , " \-\-quiet"
|
2006-12-06 17:25:35 -06:00
|
|
|
Disable error reporting by getopt(3).
|
2009-07-22 04:29:05 -05:00
|
|
|
.TP
|
|
|
|
.BR \-Q , " \-\-quiet\-output"
|
2012-06-02 15:39:40 -05:00
|
|
|
Do not generate normal output. Errors are still reported by
|
2009-07-22 04:29:05 -05:00
|
|
|
.BR getopt (3),
|
|
|
|
unless you also use
|
2006-12-06 17:26:12 -06:00
|
|
|
.IR \-q .
|
2009-07-22 04:29:05 -05:00
|
|
|
.TP
|
|
|
|
.BR \-s , " \-\-shell \fIshell\fP"
|
2012-06-02 15:39:40 -05:00
|
|
|
Set quoting conventions to those of shell. If no \-s argument is
|
|
|
|
found, the
|
2006-12-06 17:25:35 -06:00
|
|
|
.SM BASH
|
2012-06-02 15:39:40 -05:00
|
|
|
conventions are used. Valid arguments are currently
|
|
|
|
.RB ' sh '
|
|
|
|
.RB ' bash ',
|
|
|
|
.RB ' csh ',
|
2006-12-06 17:25:35 -06:00
|
|
|
and
|
2012-06-02 15:39:40 -05:00
|
|
|
.RB ' tcsh '.
|
2009-07-22 04:29:05 -05:00
|
|
|
.TP
|
|
|
|
.BR \-u , " \-\-unquoted"
|
2012-06-02 15:39:40 -05:00
|
|
|
Do not quote the output. Note that whitespace and special
|
|
|
|
(shell\-dependent) characters can cause havoc in this mode (like they
|
|
|
|
do with other
|
2006-12-06 17:25:35 -06:00
|
|
|
.BR getopt (1)
|
|
|
|
implementations).
|
2009-07-22 04:29:05 -05:00
|
|
|
.TP
|
|
|
|
.BR \-T , " \-\-test"
|
|
|
|
Test if your
|
|
|
|
.BR getopt (1)
|
2012-06-02 15:39:40 -05:00
|
|
|
is this enhanced version or an old version. This generates no
|
|
|
|
output, and sets the error status to 4. Other implementations of
|
2006-12-06 17:25:35 -06:00
|
|
|
.BR getopt (1),
|
|
|
|
and this version if the environment variable
|
|
|
|
.B GETOPT_COMPATIBLE
|
2012-06-02 15:39:40 -05:00
|
|
|
is set, will return
|
|
|
|
.RB ' \-\- '
|
2006-12-06 17:25:35 -06:00
|
|
|
and error status 0.
|
2009-07-22 04:29:05 -05:00
|
|
|
.TP
|
|
|
|
.BR \-V , " \-\-version"
|
2012-06-02 15:39:40 -05:00
|
|
|
Output version information and exit successfully. No other output is
|
|
|
|
generated.
|
2006-12-06 17:25:35 -06:00
|
|
|
.SH PARSING
|
2012-06-02 15:39:40 -05:00
|
|
|
This section specifies the format of the second part of the
|
|
|
|
parameters of
|
2006-12-06 17:25:35 -06:00
|
|
|
.B getopt
|
2009-07-22 04:29:05 -05:00
|
|
|
(the
|
|
|
|
.I parameters
|
|
|
|
in the
|
|
|
|
.BR SYNOPSIS ).
|
|
|
|
The next section
|
|
|
|
.RB ( OUTPUT )
|
2012-06-02 15:39:40 -05:00
|
|
|
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
|
2009-07-22 04:29:05 -05:00
|
|
|
.B getopt
|
|
|
|
(see the
|
|
|
|
.BR EXAMPLES ).
|
|
|
|
All parsing is done by the GNU
|
|
|
|
.BR getopt (3)
|
|
|
|
routines.
|
2012-06-02 15:39:40 -05:00
|
|
|
.PP
|
|
|
|
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.
|
|
|
|
.PP
|
2009-07-22 04:29:05 -05:00
|
|
|
A simple short option is a
|
2012-06-02 15:39:40 -05:00
|
|
|
.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.
|
|
|
|
.PP
|
2009-07-22 04:29:05 -05:00
|
|
|
It is possible to specify several short options after one
|
2012-06-02 15:39:40 -05:00
|
|
|
.RB ' \- ',
|
|
|
|
as long as all (except possibly the last) do not have required or
|
|
|
|
optional arguments.
|
|
|
|
.PP
|
2009-07-22 04:29:05 -05:00
|
|
|
A long option normally begins with
|
2012-06-02 15:39:40 -05:00
|
|
|
.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 (i.e. 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 ' = ',
|
2009-07-22 04:29:05 -05:00
|
|
|
if present (if you add the
|
2012-06-02 15:39:40 -05:00
|
|
|
.RB ' = '
|
|
|
|
but nothing behind it, it is interpreted as if no argument was
|
|
|
|
present; this is a slight bug, see the
|
2006-12-06 17:25:35 -06:00
|
|
|
.BR BUGS ).
|
|
|
|
Long options may be abbreviated, as long as the abbreviation is not
|
|
|
|
ambiguous.
|
2012-06-02 15:39:40 -05:00
|
|
|
.PP
|
2009-07-22 04:29:05 -05:00
|
|
|
Each parameter not starting with a
|
2012-06-02 15:39:40 -05:00
|
|
|
.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
|
2009-07-22 04:29:05 -05:00
|
|
|
.B POSIXLY_CORRECT
|
2012-06-02 15:39:40 -05:00
|
|
|
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.
|
2006-12-06 17:25:35 -06:00
|
|
|
.SH OUTPUT
|
2012-06-02 15:39:40 -05:00
|
|
|
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
|
2009-07-22 04:29:05 -05:00
|
|
|
.I compatible
|
2006-12-06 17:25:35 -06:00
|
|
|
.RI ( unquoted )
|
2012-06-02 15:39:40 -05:00
|
|
|
mode, or in such way that whitespace and other special characters
|
|
|
|
within arguments and non\-option parameters are preserved (see
|
2006-12-06 17:25:35 -06:00
|
|
|
.BR QUOTING ).
|
|
|
|
When the output is processed in the shell script, it will seem to be
|
2012-06-02 15:39:40 -05:00
|
|
|
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.
|
|
|
|
.PP
|
2006-12-06 17:25:35 -06:00
|
|
|
If there are problems parsing the parameters, for example because a
|
2012-06-02 15:39:40 -05:00
|
|
|
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.
|
|
|
|
.PP
|
2009-07-22 04:29:05 -05:00
|
|
|
For a short option, a single
|
2012-06-02 15:39:40 -05:00
|
|
|
.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.
|
2009-07-22 04:29:05 -05:00
|
|
|
Note that many other
|
|
|
|
.BR getopt (1)
|
2007-07-18 00:32:03 -05:00
|
|
|
implementations do not support optional arguments.
|
2012-06-02 15:39:40 -05:00
|
|
|
.PP
|
2009-07-22 04:29:05 -05:00
|
|
|
If several short options were specified after a single
|
2012-06-02 15:39:40 -05:00
|
|
|
.RB ' \- ',
|
2006-12-06 17:25:35 -06:00
|
|
|
each will be present in the output as a separate parameter.
|
2012-06-02 15:39:40 -05:00
|
|
|
.PP
|
2009-07-22 04:29:05 -05:00
|
|
|
For a long option,
|
2012-06-02 15:39:40 -05:00
|
|
|
.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.
|
|
|
|
.PP
|
|
|
|
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
|
2006-12-06 17:25:35 -06:00
|
|
|
.B SYNOPSIS
|
2006-12-06 17:26:26 -06:00
|
|
|
is used; in that case all preceding occurrences of
|
2012-06-02 15:39:40 -05:00
|
|
|
.RB ' \- '
|
2009-07-22 04:29:05 -05:00
|
|
|
and
|
2012-06-02 15:39:40 -05:00
|
|
|
.RB ' + '
|
2009-07-22 04:29:05 -05:00
|
|
|
are ignored).
|
2006-12-06 17:25:35 -06:00
|
|
|
.SH QUOTING
|
2012-06-02 15:39:40 -05:00
|
|
|
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
|
2009-07-22 04:29:05 -05:00
|
|
|
.B eval
|
2006-12-06 17:25:35 -06:00
|
|
|
command), it is split correctly into separate parameters.
|
2012-06-02 15:39:40 -05:00
|
|
|
.PP
|
2006-12-06 17:25:35 -06:00
|
|
|
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
|
2012-06-02 15:39:40 -05:00
|
|
|
.RB ' \-u '
|
2006-12-06 17:25:35 -06:00
|
|
|
is found.
|
2012-06-02 15:39:40 -05:00
|
|
|
.PP
|
|
|
|
Different shells use different quoting conventions. You can use the
|
|
|
|
.RB ' \-s '
|
|
|
|
option to select the shell you are using. The following shells are
|
2006-12-06 17:25:35 -06:00
|
|
|
currently supported:
|
2012-06-02 15:39:40 -05:00
|
|
|
.RB ' sh ',
|
|
|
|
.RB ' bash ',
|
|
|
|
.RB ' csh '
|
2006-12-06 17:25:35 -06:00
|
|
|
and
|
2012-06-02 15:39:40 -05:00
|
|
|
.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.
|
2006-12-06 17:25:35 -06:00
|
|
|
.SH "SCANNING MODES"
|
|
|
|
The first character of the short options string may be a
|
2012-06-02 15:39:40 -05:00
|
|
|
.RB ' \- '
|
2006-12-06 17:25:35 -06:00
|
|
|
or a
|
2012-06-02 15:39:40 -05:00
|
|
|
.RB ' + '
|
|
|
|
to indicate a special scanning mode. If the first calling form in
|
|
|
|
the
|
2009-07-22 04:29:05 -05:00
|
|
|
.B SYNOPSIS
|
2006-12-06 17:25:35 -06:00
|
|
|
is used they are ignored; the environment variable
|
|
|
|
.B POSIXLY_CORRECT
|
|
|
|
is still examined, though.
|
2012-06-02 15:39:40 -05:00
|
|
|
.PP
|
2009-07-22 04:29:05 -05:00
|
|
|
If the first character is
|
2012-06-02 15:39:40 -05:00
|
|
|
.RB ' + ',
|
2009-07-22 04:29:05 -05:00
|
|
|
or if the environment variable
|
2006-12-06 17:25:35 -06:00
|
|
|
.B POSIXLY_CORRECT
|
2012-06-02 15:39:40 -05:00
|
|
|
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.
|
|
|
|
.PP
|
2006-12-06 17:25:35 -06:00
|
|
|
If the first character is a
|
2012-06-02 15:39:40 -05:00
|
|
|
.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.
|
2006-12-06 17:25:35 -06:00
|
|
|
.SH COMPATIBILITY
|
2009-07-22 04:29:05 -05:00
|
|
|
This version of
|
2006-12-06 17:25:35 -06:00
|
|
|
.BR getopt (1)
|
2012-06-02 15:39:40 -05:00
|
|
|
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.
|
|
|
|
.PP
|
2009-07-22 04:29:05 -05:00
|
|
|
If the first character of the first parameter of getopt is not a
|
2012-06-02 15:39:40 -05:00
|
|
|
.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
|
2009-07-22 04:29:05 -05:00
|
|
|
.B POSIXLY_CORRECT
|
2006-12-06 17:25:35 -06:00
|
|
|
is set.
|
2012-06-02 15:39:40 -05:00
|
|
|
.PP
|
2009-07-22 04:29:05 -05:00
|
|
|
The environment variable
|
|
|
|
.B GETOPT_COMPATIBLE
|
|
|
|
forces
|
2006-12-06 17:25:35 -06:00
|
|
|
.B getopt
|
2012-06-02 15:39:40 -05:00
|
|
|
into compatibility mode. Setting both this environment variable and
|
2006-12-06 17:25:35 -06:00
|
|
|
.B POSIXLY_CORRECT
|
2012-06-02 15:39:40 -05:00
|
|
|
offers 100% compatibility for 'difficult' programs. Usually, though,
|
2006-12-06 17:25:35 -06:00
|
|
|
neither is needed.
|
2012-06-02 15:39:40 -05:00
|
|
|
.PP
|
2009-07-22 04:29:05 -05:00
|
|
|
In compatibility mode, leading
|
2012-06-02 15:39:40 -05:00
|
|
|
.RB ' \- '
|
2009-07-22 04:29:05 -05:00
|
|
|
and
|
2012-06-02 15:39:40 -05:00
|
|
|
.RB ' + '
|
2006-12-06 17:25:35 -06:00
|
|
|
characters in the short options string are ignored.
|
|
|
|
.SH RETURN CODES
|
|
|
|
.B getopt
|
2009-07-22 04:29:05 -05:00
|
|
|
returns error code
|
|
|
|
.B 0
|
2007-07-18 00:32:03 -05:00
|
|
|
for successful parsing,
|
2006-12-06 17:25:35 -06:00
|
|
|
.B 1
|
|
|
|
if
|
|
|
|
.BR getopt (3)
|
|
|
|
returns errors,
|
2009-07-22 04:29:05 -05:00
|
|
|
.B 2
|
2006-12-06 17:25:35 -06:00
|
|
|
if it does not understand its own parameters,
|
|
|
|
.B 3
|
2006-12-06 17:26:12 -06:00
|
|
|
if an internal error occurs like out\-of\-memory, and
|
2006-12-06 17:25:35 -06:00
|
|
|
.B 4
|
2009-07-22 04:29:05 -05:00
|
|
|
if it is called with
|
2006-12-06 17:26:12 -06:00
|
|
|
.BR \-T .
|
2006-12-06 17:25:35 -06:00
|
|
|
.SH EXAMPLES
|
|
|
|
Example scripts for (ba)sh and (t)csh are provided with the
|
|
|
|
.BR getopt (1)
|
2009-07-22 04:29:05 -05:00
|
|
|
distribution, and are optionally installed in
|
2012-06-02 15:39:40 -05:00
|
|
|
.BR /usr/share/getopt/ .
|
2006-12-06 17:25:35 -06:00
|
|
|
.SH ENVIRONMENT
|
|
|
|
.IP POSIXLY_CORRECT
|
|
|
|
This environment variable is examined by the
|
|
|
|
.BR getopt (3)
|
2012-06-02 15:39:40 -05:00
|
|
|
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
|
2006-12-06 17:26:12 -06:00
|
|
|
parameters are also interpreted as non\-option parameters, regardless
|
2009-07-22 04:29:05 -05:00
|
|
|
whether they start with a
|
2012-06-02 15:39:40 -05:00
|
|
|
.RB ' \- '.
|
2006-12-06 17:25:35 -06:00
|
|
|
.IP GETOPT_COMPATIBLE
|
|
|
|
Forces
|
|
|
|
.B getopt
|
|
|
|
to use the first calling format as specified in the
|
|
|
|
.BR SYNOPSIS .
|
|
|
|
.SH BUGS
|
|
|
|
.BR getopt (3)
|
2012-06-02 15:39:40 -05:00
|
|
|
can parse long options with optional arguments that are given an
|
|
|
|
empty optional argument (but can not do this for short options).
|
|
|
|
This
|
2006-12-06 17:25:35 -06:00
|
|
|
.BR getopt (1)
|
|
|
|
treats optional arguments that are empty as if they were not present.
|
2012-06-02 15:39:40 -05:00
|
|
|
.PP
|
2006-12-06 17:25:44 -06:00
|
|
|
The syntax if you do not want any short option variables at all is
|
2007-07-18 00:32:03 -05:00
|
|
|
not very intuitive (you have to set them explicitly to the empty
|
2006-12-06 17:25:44 -06:00
|
|
|
string).
|
2006-12-06 17:25:35 -06:00
|
|
|
.SH AUTHOR
|
2012-06-02 15:39:40 -05:00
|
|
|
.MT frodo@frodo.looijaard.name
|
|
|
|
Frodo Looijaard
|
|
|
|
.ME
|
2006-12-06 17:25:35 -06:00
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR getopt (3),
|
|
|
|
.BR bash (1),
|
|
|
|
.BR tcsh (1).
|
2007-07-02 18:17:04 -05:00
|
|
|
.SH AVAILABILITY
|
2010-11-30 04:41:59 -06:00
|
|
|
The getopt command is part of the util-linux package and is available from
|
2012-06-02 15:39:40 -05:00
|
|
|
.UR ftp://\:ftp.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
|
|
|
|
Linux Kernel Archive
|
|
|
|
.UE .
|