getopts - parse utility options

The POSIX shell built-in getopts is used by shell scripts to parse arguments and options in the command line and to check for valid options. It supports all applicable rules of the command syntax standard.
You can use getopts in shell procedures to analyze the arguments specified when the procedure is called. The individual options and arguments are stored in sequence in shell variables and can then be easily queried or checked. If an option in the argument list is not permitted or if getopts finds no corresponding argument for an option which requires an argument then getopts issues a corresponding error message.

The argument list should always be processed using getopts and examined for valid options in order to ensure that all procedures and commands process the argument list in the same way.

Syntax

getopts optstring name[ arg ...]

optstring

A string which may consist of letters and colons : . The letters specified in optstring are considered by getopts to be permitted shell procedure options. If a letter is followed by a colon then getopts expects an argument or a group of arguments for this option. Any arguments must be separated from the option by spaces or tabs.

name

Name of the shell variable in which getopts places the next option each time it is invoked.

arg ...

Argument list parsed by getopts.

arg not specified:
getopts parses the argument list of the command line with which the script was invoked.

Mode of operation

Each time it is invoked, getopts places the next option in the shell variable name and the index of the next argument to be processed in the shell variable OPTIND. Whenever the shell command interpreter or a shell script is invoked, OPTIND is initialized to 1.

In the case of options which require an argument, this argument is assigned to the shell variable OPTARG. Options which require an argument must be identified by a colon : in optstring. If no option is present or if the option has no argument then OPTARG is reset.

If an invalid option is identified then a question mark ? is assigned to the shell variable name. Invalid options are those which are not present in optstring. In this case (if the first character in optstring is a colon :) the located option character is assigned to the shell variable OPTARG. However, no output is written to the standard error output. Otherwise the shell variable OPTARG is reset and a message is written to the default error output. This is interpreted as a detected error in the argument presentation for the calling function. It is, however, not a getopts error.

If an option argument is missing, then:

• If the first character of optstring is a colon :, the shell variable specified in name is set to the colon and the shell variable OPTARG is set to the detected option character.

• Otherwise the shell variable specified in name is set to the question mark, the shell variable OPTARG is reset and a message is written to the standard error output. This is interpreted as a detected error in the argument presentation for the calling function. It is, however, not a getopts error. A message is output as indicated but the exit status is zero.

When the end of the option list is encountered, getopts exits with a non-zero exit status. The special option -- may be also used to identify the end of the options.

Changing the value of the shell variable OPTIND or invoking getopts with different sets of arguments may lead to unexpected results.

Locale

The following environment variables affect the execution of getopts:

LANG

Provide a default value for the internationalization variables that are unset or null. If LANG is unset of null, the corresponding value from the implementation-specific default locale will be used. If any of the internationalization variables contains an invalid setting, the utility will behave as if none of the variables had been defined.

LC_ALL

If set to a non-empty string value, override the values of all the other internationalization variables.

LC_CTYPE

Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- as opposed to multi-byte characters in arguments and input files), the classification of characters as upper- to lower-case, and the mapping of characters from one case to the other.

LC_MESSAGES

Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.

NLSPATH

Determine the location of message catalogs for the processing of LC_MESSAGES.

Example

The following fragment of a shell script scrpt shows how you might process the arguments for a script that can take the options -a or -b, as well as the option -o, which requires an option argument. Options -a and -b are mutually exclusive, and if both are specified, only the one listed second applies:

while getopts abo: c
do
      case $c in
      [ab])           FLAG=$c;;
      o)              OARG=$OPTARG;;
      \?)             echo "usage: $0 [-a| -b] [-o <arg>]"
                      exit 2;;
      esac
done
shift `expr $OPTIND - 1`

This code accepts any of the following invocations of scrpt as equivalent:

proz -a -b -o "xxx z yy" file
proz -a -b -o "xxx z yy" -- file
proz -ab -o "xxx z yy" file