build-sys: move getopt to misc-utils/

Signed-off-by: Karel Zak <kzak@redhat.com>

1 files changed, 448 insertions, 0 deletions

diff --git a/misc-utils/getopt.1 b/misc-utils/getopt.1
new file mode 100644
index 000000000..6558e12bf
--- /dev/null
+++ b/misc-utils/getopt.1
@@ -0,0 +1,448 @@
+.TH GETOPT "1" "June 2012" "util-linux" "User Commands"
+.SH NAME
+getopt \- parse command options (enhanced)
+.SH SYNOPSIS
+getopt optstring parameters
+.br
+getopt [options] [\-\-] optstring parameters
+.br
+getopt [options] \-o|\-\-options optstring [options] [\-\-]
+.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 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.
+.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
+.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"
+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.
+.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 (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
+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 (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
+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 ' \- ',
+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.
+.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/ .
+.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 .