getopt command (analyzes command line options)
- Organization of this page
Format 1
getopt analysis-options argument-to-be-analyzed
Format 2
getopt [option] [--] analysis-options argument-to-be-analyzed
Format 3
getopt [option] -o short-analysis-option-name [option] [--] argument-to-be-analyzed
Description
This command analyzes the command line specified in argument-to-be-analyzed according to the specified analysis-options and outputs the analysis results to the standard output. The command can analyze both short and long options. This command simplifies syntax analysis of shell scripts.
If one of the following specifications is made, the command assumes that format 1 is being used:
-
The first parameter of the argument does not begin with -.
-
The GETOPT_COMPATIBLE environment variable is set.
For any other specifications, if the -o option is specified, format 3 is assumed; if the -o option is not specified, format 2 is assumed.
Arguments
- analysis-options
-
Specifies a character string containing the analysis options.
When you specify short options, note the following:
-
If a short option begins with -, an operand is output at the location where it appears. If a short option begins with +, the option must be specified before an operand.
Note that in format 1, - and + at the beginning are ignored.
-
If a short option begins with : (or if a short option begins with - or + and the next character is :), and the option for the argument to be analyzed is not specified in the analysis options, no error message is issued, but the return code will be an error. Analysis of the arguments to be analyzed will continue.
By specifying : or :: after an option character or an option name, you can define the following:
- Specifying : after an option character or an option name
-
This indicates that the option requires a value.
In this case, specify an option name and an option value for the argument to be analyzed in the following format:
-
Specify a short option name and an option value without a separator.
$ getopt "xy:z" -yarg
-y arg --
-
Specify a short option name and an option value separated by a space.
$ getopt "xy:z" -y arg
-y arg --
-
Specify a long option name and an option value separated by a space.
$ getopt -o "abc" -l xyz: -- --xyz nml
--xyz 'nml' --
-
Specify in the format long-option-name=option-value.
$ getopt -o "abc" -l xyz: -- --xyz=nml
--xyz 'nml' --
-
- Specifying :: after an option character or an option name
-
This indicates that specifying a value for the option is optional. If you specify an argument, specify :: immediately after an option character or an option name.
In this case, specify an option name and an option value for the argument to be analyzed in the following format:
-
Short options
Specify an option name immediately followed by an option value.
-
Long options
Specify in the format long-option-name=option-value.
-
-
- argument-to-be-analyzed
-
Specifies an option name, an option value, and an operand as the argument to be analyzed. For details about specifying options, see 8.1 Command description format.
- How to specify options
-
Specify a short option following - and a long option following --. If no long option name follows --, the command terminates option analysis at that location and treats all subsequent parameters as operands.
You can abbreviate long option names. In such a case, the complete long option names are displayed in the output results. The following shows an example:
$ getopt -o "" -l "longZ" -- --lo --longZ --
If you abbreviate a long option name, make sure that the specified name can be distinguished from all other options. If the specified long option name cannot be identified, the command treats it as any option name defined earlier in analysis-options.
- Specification order of options and operands
-
By default, there is no rule for the specification order of options and operands. The options specified after operands are still analyzed. You can specify an option specification order by using the following environment variables:
-
Using the ADSH_CMD_ARGORDER environment variable to specify an option specification order
If the ADSH_CMD_ARGORDER environment variable is specified, the options specified as the argument to be analyzed must appear before operands.
-
Using the POSIXLY_CORRECT environment variable to specify an option specification order
If the POSIXLY_CORRECT environment variable is specified, the options specified as the argument to be analyzed must appear before operands.
This definition applies to commands in the Linux version as well as to commands specified in the ADSH_CMD_ARGORDER environment variable.
-
- option
-
In formats 2 and 3, you can specify the following options:
- -longoptions=long-option-name
-
Specifies the long analysis option.
To specify multiple options, separate them with the comma (,) or the space or specify this option multiple times.
- --name=program-name
-
Specifies a command name that is to be displayed in error messages for option analysis instead of the getopt command name.
- --quiet
-
Specifies that output of error messages resulting from option analysis of the argument being analyzed is to be suppressed.
- --unquoted
-
Specifies that option values and operands obtained as analysis results in formats 2 and 3 are not to be enclosed in quotation marks.
- --options=short-option-name
-
Specifies a short analysis option.
If this option is specified more than once, the last value specified takes effect.
If W; is specified for the short option and a long option name with -W for the argument to be analyzed is specified, the specified value is treated as a long option name.
Output of analysis results
Analysis results are classified into option names, option values, and operands and output to the standard output.
If format 2 or 3 was used, option values and operands are enclosed in single quotation marks ('). If -u is specified, they are not enclosed in single quotation marks (').
For short options, an option name with - is output as one option. For long options, the complete option name with -- is output as one option.
The separator -- is output between an option (option name and option value) and an operand. This does not apply if - is specified at the beginning of short options.
The command continues processing all parameter options even if an error occurs during option analysis. The following shows an example:
$ getopt "xyz" -w -x getopt: invalid option -- w -x --
Return codes
Return code |
Meaning |
---|---|
0 |
Normal termination |
1 |
Error termination
|
2 |
Error termination
|
3 |
Error termination
|
Examples
-
Execute the command using format 1:
$ getopt "xy:z" -z -y arg1 arg2 -z -y arg1 -- arg2
-
Execute the command using format 2:
$ getopt -q "xy:z" -z -y arg1 arg2 -z -y 'arg1' -- 'arg2'
-
Execute the command using format 3:
$ getopt -o "xy:z" -- -z -y arg1 arg2 -z -y 'arg1' -- 'arg2'
-
Set analysis results in positional parameters.
Executable file
OPT=`getopt -o abc:d: -- -a -b` eval set -- "$OPT" echo $1 echo $2 echo $3
Execution results
-a -b --
-
Display option error messages:
This message might vary depending on the platform used to execute the command. The following is an example for Windows:
C:\> getopt -z getopt: illegal option -- z usage: getopt optstring parameters getopt [options] [--] optstring parameters getopt [options] -o optstring [options] [--] parameters