-.TH GETOPT "1" "June 2012" "util-linux" "User Commands"
+.TH GETOPT "1" "December 2014" "util-linux" "User Commands"
.SH NAME
getopt \- parse command options (enhanced)
.SH SYNOPSIS
-getopt optstring parameters
+.B getopt
+.I optstring parameters
.br
-getopt [options] [\-\-] optstring parameters
+.B getopt
+[options]
+.RB [ \-\- ]
+.I optstring parameters
.br
-getopt [options] \-o|\-\-options optstring [options] [\-\-]
+.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
+check for valid 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
+the way
+.B getopt
+will do the parsing
+.RI "(the " options
+and the
.I optstring
in the
.BR SYNOPSIS ),
.PP
If the environment variable
.B GETOPT_COMPATIBLE
-is set, or if its first parameter is not an option (does not start
-with a
+is set, or if the first
+.I parameter
+is not an option (does not start with a
.RB ' \- ',
-this is the first format in the
+the first format in the
.BR SYNOPSIS ),
.B getopt
will generate output that is compatible with that of other versions of
.PP
Traditional implementations of
.BR getopt (1)
-are unable to cope with whitespace and other (shell\-specific)
+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
.RB ' \- '.
.TP
.BR \-h , " \-\-help"
-Output a small usage guide and exit successfully. No other output is
-generated.
+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
Do not generate normal output. Errors are still reported by
.BR getopt (3),
unless you also use
-.IR \-q .
+.BR \-q .
.TP
.BR \-s , " \-\-shell \fIshell\fP"
-Set quoting conventions to those of shell. If no \-s argument is
-found, the
+Set quoting conventions to those of
+.IR shell .
+If the \fB\-s\fR option is not given, the
.SM BASH
conventions are used. Valid arguments are currently
.RB ' sh '
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)
.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"
-Output version information and exit successfully. No other output is
-generated.
+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
.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
+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
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
+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 ' = ',
.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
+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 of the first parameter of getopt is not a
.RB ' \- ',
-getopt goes into compatibility mode. It will interpret its first
+.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 (ie. all
-non\-option parameters are outputted at the end), unless the
+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.
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/ .
+.I /usr/share/getopt/
+or
+.I /usr/share/doc/
+in the util-linux subdirectory.
.SH ENVIRONMENT
.IP POSIXLY_CORRECT
This environment variable is examined by the
.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).
+empty optional argument (but cannot do this for short options).
This
.BR getopt (1)
treats optional arguments that are empty as if they were not present.
Frodo Looijaard
.ME
.SH "SEE ALSO"
-.BR getopt (3),
.BR bash (1),
-.BR tcsh (1).
+.BR tcsh (1),
+.BR getopt (3)
.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/
+.UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
Linux Kernel Archive
.UE .
projects / thirdparty / util-linux.git / blobdiff