| .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 . |