+++ /dev/null
-.TH GETOPT "1" "December 2014" "util-linux" "User Commands"
-.SH NAME
-getopt \- parse command options (enhanced)
-.SH SYNOPSIS
-.BI getopt
-.I optstring parameters
-.br
-.B getopt
-[options]
-.RB [ \-\- ]
-.I optstring parameters
-.br
-.B getopt
-[options]
-.BR \-o | \-\-options
-.I optstring
-[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.
-.PP
-The parameters
-.B getopt
-is called with can be divided into two parts: options which modify
-the way
-.B getopt
-will do the parsing
-.RI "(the " options
-and the
-.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.
-.PP
-If the environment variable
-.B GETOPT_COMPATIBLE
-is set, or if the first \fIparameter\fR is not an option (does not start
-with a
-.RB ' \- ',
-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).
-.PP
-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"
-Display help text and exit. 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
-.BR \-q .
-.TP
-.BR \-s , " \-\-shell \fIshell\fP"
-Set quoting conventions to those of \fIshell\fR.
-If the \fB\-s\fR option is not given, the
-.SM BASH
-conventions are used. Valid arguments are currently
-.RB ' sh '
-.RB ' bash ',
-.RB ' csh ',
-and
-.RB ' tcsh '.
-.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 \-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 \-V , " \-\-version"
-Display version information and exit. 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.
-.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
-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 (i.e. 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
-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.
-.PP
-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 (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 ' = ',
-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.
-.PP
-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.
-.PP
-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.
-.PP
-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.
-.PP
-If several short options were specified after a single
-.RB ' \- ',
-each will be present in the output as a separate parameter.
-.PP
-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.
-.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
-.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.
-.PP
-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.
-.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
-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.
-.PP
-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
-(i.e. 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
-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.
-.PP
-If the first character of the first parameter of getopt is not a
-.RB ' \- ',
-.B 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 (i.e. all
-non\-option parameters are output at the end), unless the
-environment variable
-.B POSIXLY_CORRECT
-is set.
-.PP
-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.
-.PP
-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/
-or
-.BR /usr/share/doc/
-in the util-linux subdirectory.
-.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.
-.PP
-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
-.MT frodo@frodo.looijaard.name
-Frodo Looijaard
-.ME
-.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
-.UR ftp://\:ftp.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
-Linux Kernel Archive
-.UE .
projects / thirdparty / util-linux.git / blobdiff