getopts(C)

getopts, getoptcvt -- parse command options

Syntax

getopts optstring name [ arg ... ]

/usr/lib/getoptcvt [ -b ] file

Description

The getopts command is used by shell procedures to parse positional parameters and to check for legal options. It supports all applicable rules of the command syntax standard (see Rules 3-10, Intro(C)). It should be used instead of the getopt(C) command.

This feature is only available in the Bourne (sh) and Korn (ksh) shells.

optstring contains the option letters that the command using getopts recognizes. If a letter is followed by a colon, the option is expected to have an argument, or group of arguments, which must be separated from it by white space.

Each time it is invoked, getopts places the first option it reads in the shell variable name, and the index of the next argument to be processed in the shell variable OPTIND. Whenever the shell is invoked, OPTIND is initialized to 1.

To use getopts, invoke it in a loop. After each execution of getopts, take the action appropriate to the option saved in name. If the option has a parameter, take it from OPTARG. Finally, return to the top of the loop. The loop exit condition should be reached when no more options can be read (that is, when getopts exits with a status of 1).

To process another set of arguments within a script, set OPTIND to 1 before invoking getopts.

When an option requires an option-argument, getopts places it in the shell variable OPTARG.

If an illegal option is encountered, getopts normally prints a message to standard error, and sets the name variable to ``?''. If the optstring begins with a colon ``:'', no message is printed and OPTARG is set to the value of the illegal character; name is still set to ``?''.

By default, getopts parses the positional parameters. If extra arguments (arg ...) are given on the getopts command line, getopts will parse them instead.

The /usr/lib/getoptcvt command reads the shell script in file, converts it to use getopts instead of the getopt command, and writes the results to the standard output. The following flag is recognized:

-b: The results of running /usr/lib/getoptcvt will be portable to earlier UNIX releases. /usr/lib/getoptcvt modifies the shell script in file so that when the resulting shell script is executed, it determines at run time whether to invoke getopts or getopt.

All new commands should use getopts or getopt to parse positional parameters and check their options for legality so that they conform to the standard command syntax described in Intro(C).

Exit values

When the end of options is encountered, getopts exits with a status of 1. The special option ``--'' may be used to delimit the end of the options.

Diagnostics

getopts prints an error message to the standard error when it encounters an option letter not included in optstring.

Examples

The following fragment of a shell program (named foo) shows how one might process the arguments for a command that can take the options -a or -b, as well as the option -o which requires an option-argument:

   HELP="foo is the archetypal example program"
   USAGE="foo [[-h] | [[-a | -b] [-o list] [otherargs ... ]]]"
   
   if [ $# = 0 ]
   then
   	echo "$USAGE"
   	exit 1
   fi
   

   while getopts habo: c
   do
   	case $c in
   	h)	echo "$HELP"
   		echo "$USAGE"
   		exit 2;;
   	a | b)	FLAG=$c;;
   	o)	OARG=$OPTARG;;
           \?)     echo "$USAGE"
                   exit 3;;
   	esac
   done
   shift `expr $OPTIND - 1`

The shift command allows the shell program to continue to process any other arguments. This example will accept any of the following as equivalent:

foo -a -o "xxx z yy"
foo -o "xxx z yy" -a
foo -a -o "xxx z yy" --

Limitations

Although the following command syntax rule (see Intro(C)) relaxations are permitted under the current implementation, they should not be used because they may not be supported in future releases of the system. As in the ``Examples'' section above, -a and -o are options to command, with option -o requiring an option-argument:

command -ao xxx file: (Rule 5 violation: options with option-arguments must not be grouped with other options.)
command -a -oxxx file: (Rule 6 violation: there must be white space after an option that takes an option-argument.)

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

Standards conformance

getopts is conformant with:

ISO/IEC DIS 99452:1992, Information technology Portable Operating System Interface (POSIX) Part 2: Shell and Utilities (IEEE Std 1003.21992);
X/Open CAE Specification, Commands and Utilities, Issue 4, 1992.

getoptcvt is not part of any currently supported standard.