--- getopt/trunk/getopt.1	2005/11/07 22:19:13	263
+++ getopt/trunk/getopt.1	2014/11/20 20:15:01	365
@@ -1,421 +1,433 @@
-.TH GETOPT 1 "May 31, 1997" Linux ""
+.TH GETOPT "1" "June 2012" "Linux" "User Commands"
 .SH NAME
 getopt \- parse command options (enhanced)
 .SH SYNOPSIS
-.BR getopt " optstring parameters"
-
-.BR getopt " [options] [" \-\- "] optstring parameters"
-
-.BR getopt " [options] " \-o | \-\-options " optstring [options] [" \-\- "] parameters"
+.BI 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 
+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 
+options in command lines for easy parsing by shell procedures, and to
+check for legal options.  It uses the
 .SM GNU
-.BR getopt (3) 
+.BR getopt (3)
 routines to do this.
-
-The parameters 
+.PP
+The parameters
 .B getopt
-is called with can be divided into two parts: options
-which modify the way getopt will parse
-.RI ( options
-and
-.I \-o|\-\-options optstring
-in the 
-.BR SYNOPSIS), 
-and the parameters which are to be
-parsed
+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.
-
+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 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
+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). 
-
+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
+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 
+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). 
+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 ) 
+.RB ( \-T )
 can be used.
 .SH OPTIONS
-.IP "\-a, \-\-alternative"
-Allow long options to start with a single 
-.RB ` \- '.
-.IP "\-h, \-\-help"
-Output a small usage guide and exit succesfully. No other output is generated. 
-.IP "\-l, \-\-longoptions longopts"
-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.
-.IP "\-n, \-\-name progname"
-The name that will be used by the 
+.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
+routines when it reports errors.  Note that errors of
 .BR getopt (1)
 are still reported as coming from getopt.
-.IP "\-o, \-\-options shortopts"
-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 ` \- ' 
+.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 
+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 ` + ' 
+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 
+.RB ' \- '
+to influence the way options are parsed and output is generated (see
+section
 .B SCANNING MODES
 for details).
-.IP "\-q, \-\-quiet"
+.TP
+.BR \-q , " \-\-quiet"
 Disable error reporting by getopt(3).
-.IP "\-Q, \-\-quiet\-output"
-Do not generate normal output. Errors are still reported by
-.BR getopt (3), 
-unless you also use 
-.IR \-q .
-.IP "\-s, \-\-shell shell"
-Set quoting conventions to those of shell. If no \-s argument is found,
-the
+.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 ',
+conventions are used.  Valid arguments are currently
+.RB ' sh '
+.RB ' bash ',
+.RB ' csh ',
 and
-.RB ` tcsh '.
-.IP "\-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
+.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).
-.IP "\-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 
+.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 ` \-\- ' 
+is set, will return
+.RB ' \-\- '
 and error status 0.
-.IP "\-V, \-\-version"
-Output version information and exit succesfully. No other output is generated. 
+.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
+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 
+(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.
-
-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.
+.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 
+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 
+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.
-
+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.
-
-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) 
-implemetations do not support optional arguments.
-
-If several short options were specified after a single 
-.RB ` \- ', 
+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.
-
-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 
+.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). 
+.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 
+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 '
+.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
+.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 ' 
+.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.
-
+.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 ` \- '
+.RB ' \- '
 or a
-.RB ` + '
-to indicate a special scanning mode. If the first calling form
-in the
-.B SYNOPSIS 
+.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 
+.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 
-(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.
-
+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 outputed 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.
+.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 
+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 outputed
-at the end), unless the environment variable 
-.B POSIXLY_CORRECT 
+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.
-
-The environment variable 
-.B GETOPT_COMPATIBLE 
-forces 
+.PP
+The environment variable
+.B GETOPT_COMPATIBLE
+forces
 .B getopt
-into compatibility mode. Setting both this environment variable and
+into compatibility mode.  Setting both this environment variable and
 .B POSIXLY_CORRECT
-offers 100% compatibility for `difficult' programs. Usually, though,
+offers 100% compatibility for 'difficult' programs.  Usually, though,
 neither is needed.
-
-In compatibility mode, leading 
-.RB ` \- '
-and 
-.RB ` + '
+.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 succesful parsing, 
+returns error code
+.B 0
+for successful parsing,
 .B 1
 if
 .BR getopt (3)
 returns errors,
-.B 2 
+.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 
+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 
-.B /usr/local/lib/getopt 
-or 
-.BR /usr/lib/getopt .
+distribution, and are optionally installed in
+.BR /usr/local/share/getopt/
+or
+.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 
+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 ` \- '.
+whether they start with a
+.RB ' \- '.
 .IP GETOPT_COMPATIBLE
 Forces
 .B getopt
@@ -423,19 +435,29 @@
 .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 
+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 explicitely to the empty
+not very intuitive (you have to set them explicitly to the empty
 string).
-
 .SH AUTHOR
-Frodo Looijaard <frodo@frodo.looijaard.name>
+.MT frodo@frodo.looijaard.name
+Frodo Looijaard
+.ME
 .SH "SEE ALSO"
 .BR getopt (3),
 .BR bash (1),
 .BR tcsh (1).
-
+.SH AVAILABILITY
+You can download the latest getopt from
+.UR http://frodo.looijaard.name/project/getopt
+the author's home page
+.UE .
+It is also part of the util-linux package which is available from
+.UR ftp://\:ftp.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
+Linux Kernel Archive
+.UE .