diff options
Diffstat (limited to 'misc-utils/getopt.1')
| -rw-r--r-- | misc-utils/getopt.1 | 462 |
1 files changed, 462 insertions, 0 deletions
diff --git a/misc-utils/getopt.1 b/misc-utils/getopt.1 new file mode 100644 index 0000000..47e032b --- /dev/null +++ b/misc-utils/getopt.1 @@ -0,0 +1,462 @@ +.TH GETOPT "1" "December 2014" "util-linux" "User Commands" +.SH NAME +getopt \- parse command options (enhanced) +.SH SYNOPSIS +.B 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 valid 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 +.I parameter +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 +.IR shell . +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 +.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 +.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 cannot 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 bash (1), +.BR tcsh (1), +.BR getopt (3) +.SH AVAILABILITY +The getopt command is part of the util-linux package and is available from +.UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/ +Linux Kernel Archive +.UE . |