getopt(1) getopt(1)
NAME
getopt - scan command-line arguments for options
SYNOPSIS
getopt optstring $*
DESCRIPTION
getopt is being replaced by the Bourne shell built-in getopts(1) and
will not be supported in future releases. A conversion tool
/usr/lib/getoptcvt has been provided to convert earlier shell scripts
from getopt to getopts [see getoptcvt(1)].
getopt reads the contents of the shell parameter $* and compares them
with the getopt command-line argument optstring. On the basis of this
comparison, getopt either puts the contents of the shell parameter in
a standard format and writes them to standard output in that form, or
sends error messages to standard error.
The getopt command can be used in shell scripts to parse the arguments
specified when the script is invoked. getopt breaks up the specified
command-line arguments into options and arguments to be passed to the
script. The arguments can thus be easily parsed and checked for legal
options.
OPERANDS
optstring
A string that may comprise letters and colons. getopt treats the
letters specified in optstring as legal options of the shell
script. If a letter is followed by a colon, getopt expects the
option to take an argument.
$* Shell parameter containing all the command-line arguments of the
shell script.
Parsing command-line script arguments
When a shell script is invoked, the shell passes the name of the
script to positional parameter $0 and all the command-line script
arguments to the shell parameter $* [see sh(1)]. If the script
includes a getopt command, getopt reads the contents of the shell
parameter $* (see arguments to the script) and compares them with
optstring, parsing the argument list into
- options
- arguments associated with an option
- other arguments.
getopt has the following rules for the writing of command-line script
arguments:
Page 1 Reliant UNIX 5.44 Printed 11/98
getopt(1) getopt(1)
- Options may appear in any order.
- Options may be listed individually, separated by a blank and a
minus sign, or grouped together with no blanks and only one minus
sign at the start, e.g.
script -a -b -c
script -ab -c
script -abc
script -b -ac
- If an option has to have an argument, the argument can either come
immediately after the option or be separated from it by a blank or
a tab. It must be separated from the next option by a blank or a
tab:
script -a -b arg -c
script -ab arg -c
script -abarg -c
script -acbarg
Caution:
getopt does not correctly handle a quoted group of arguments
following an option and a blank. For example:
proc -a -b -o "xxx z yy" file
The argument "xxx z yy" to the -o option is not interpreted
correctly. In such cases you should use the getopts(1) command
instead of getopt.
If the command-line options and arguments match the defined optstring
in the getopt command, getopt writes them to standard output in a
standard format. The options are listed separately, each preceded by a
minus sign and followed by a blank. The argument for an option comes
after the option and is separated from it by a blank. The end of the
option list is marked by two minus signs (--); then come the other
arguments, with blanks between them.
Example:
- optstring: a:b:cdef
- command-line arguments: -fb arg -caarg -de file1 file2
- output from getopt: -f -b arg -c -a arg -d -e -- file1 file2
See also Example 1.
Page 2 Reliant UNIX 5.44 Printed 11/98
getopt(1) getopt(1)
If there is an illegal option in the argument list of a shell script,
or if getopt cannot find a suitable argument for an option which has
to have one, getopt issues an error message to that effect (see ERROR
MESSAGES). If an argument has been assigned to an option which does
not take one, getopt either tries to interpret it as an option or
assumes that it has reached the end of the option list.
Example:
- optstring: abc
- command-line arguments: -a -barg -c
- output from getopt if the GETOPTPREFIX environment variable is not
set:
getopt: illegal option -- r
getopt: illegal option -- g
or:
output from getopt if the GETOPTPREFIX environment variable is set
to program:
program: illegal option -- r
program: illegal option -- g
- optstring: abc
- command-line arguments: -a -b --arg -c
- output from getopt: -a -b -- arg -c
You can also use the special option -- to mark the end of the option
list explicitly when you call a shell script. You only really need to
do so if an argument which is not associated with an option is to
start with a minus sign (see Example 1).
You can use the Bourne shell built-in set(1) to manipulate the parsed
argument list that getopt writes to standard output: the command line
set -- `getopt ...`
passes the output of getopt to the shell parameter $*, thereby substi-
tuting the parsed command-line arguments for the original contents of
$* (the non-parsed command-line script arguments; see also Example 2).
Page 3 Reliant UNIX 5.44 Printed 11/98
getopt(1) getopt(1)
ERROR MESSAGES
If the GETOPTPREFIX environment variable is not set:
getopt: option requires an argument --x
if the GETOPTPREFIX environment variable is set to program:
program: option requires an argument --x
-x has been identified in the getopt call as an option with arguments;
however, you have not specified an argument for -x when calling the
shell script that contains this getopt call.
If the GETOPTPREFIX environment variable is not set:
getopt: option requires an argument --x
if the GETOPTPREFIX environment variable is set to program:
program: option requires an argument --x
-y is not included in the list of legal options (optstring), but has
been specified in the command line of the shell script.
LOCALE
The LCMESSAGES environment variable governs the language in which
message texts are displayed. If LCMESSAGES is undefined or is defined
as the null string, it defaults to the value of LANG. If LANG is like-
wise undefined or null, the system acts as if it were not internation-
alized.
The LCALL environment variable governs the entire locale. LCALL
takes precedence over all the other environment variables which affect
internationalization.
EXAMPLES
Example 1
The shell script proc has the following contents:
echo $*
getopt -abo:f $*
echo $*
...
The getopt line specifies that the legal options for proc are -a, -b,
-o and -f and that option -o must have an argument.
Page 4 Reliant UNIX 5.44 Printed 11/98
getopt(1) getopt(1)
You now invoke the script:
$ proc -bf -oarg file
-bf -oarg file
-b -f -o arg -- file
-bf -oarg file
The outputs from echo show that the command-line arguments are passed
to the shell parameter $* and that getopt does nothing to change this.
As the argument list is acceptable, getopt does not issue any error
messages, but simply writes the argument list to standard output in
the standard format.
You now invoke the script with an illegal option:
$ proc -abx file
-abx file
getopt: illegal option -- x
-abx file
If you want the script to have an argument starting with a minus sign,
you have to separate this argument from the option list with the dou-
ble minus sign --:
$ proc -bf -oarg -- -argument
-bf -oarg -- -argument
-b -f -o arg -- -argument
-bf -oarg -- -argument
The special option -- marks the end of the option list; any arguments
coming after it are no longer interpreted as options or as option-
related arguments.
Example 2
The following code fragment from a shell script named proc shows how
one might process the arguments of a shell script. The legal options
for proc are -a, -b, and -o; -o requires an argument. Options -a and
-b are mutually exclusive; and if both are specified, only the one
listed second applies:
GETOPTPREFIX = proc
set -- `getopt abo: $*`
if [ $? != 0 ]
then
echo "usage: $0 [-a | -b] [-o <arg>]"
exit 2
fi
Page 5 Reliant UNIX 5.44 Printed 11/98
getopt(1) getopt(1)
for i in $*
do
case $i in
-a | -b) shift; FLAG=$i;;
-o) OARG=$2; shift 2;;
--) shift; break;;
esac
done
This program code will accept any of the following proc calls as
equivalent (among others):
proc -aoarg file1 file2
proc -a- o arg file1 file2
proc -oarg -a file1 file2
proc -boarg -a file1 file2
proc -a -o arg -- file1 file2
Next proc is invoked to show how this fragment of coding operates.
Suppose you invoke proc with the following command:
$ proc -boarg -a file1 file2
getopt establishes that the argument list is acceptable and passes it
to set in the following format:
-b -o arg -a -- file1 file2
set successively passes the elements of this list to positional param-
eters $1, $2 and so on, and passes the entire list to the shell param-
eter $*. The resultant values are:
$1 = -b
$2 = -o
$3 = arg
$4 = -a
$5 = --
$6 = file1
$7 = file2
$* = -b -o arg -a -- file1 file2
As the argument list in your invocation of proc is acceptable, the
condition in the if construct is not met, and the script then runs
through the for loop.
First pass through the for loop:
The value of $i is -b. The case construction matches -b and assigns it
to the shell variable FLAG. Following the shift function, positional
parameters $1, $2, ..., $* have the following values:
Page 6 Reliant UNIX 5.44 Printed 11/98
getopt(1) getopt(1)
$1 = -o
$2 = arg
$3 = -a
$4 = --
$5 = file1
$6 = file2
$* = -b -o arg -a -- file1 file2
Second pass through the for loop:
The value of $i is -o, so the script takes the second branch of the
case construction. On account of the shift command in the first pass
of the for loop, the value of $2 is arg; hence the assignment OARG=$2
gives the shell variable OARG the value of the argument for the -o
option. Following the shift 2 command, the positional parameters have
the following values:
$1 = -a
$2 = --
$3 = file1
$4 = file2
$* = -b -o arg -a -- file1 file2
Third pass through the for loop:
The value of $i is now arg. As there is no branch of case for arg,
nothing happens, and the values of the positional parameters stay as
they are.
Fourth pass through the for loop:
Now the value of $i is -a. The case construction matches -a and
assigns it to the shell variable FLAG, overwriting its old value of
-b: options -a and -b are mutually exclusive, so only the second one
that you specify is accepted, in this case -a. The values of the
remaining parameters after the shift command are:
$1 = --
$2 = file1
$3 = file2
$* = -b -o arg -a -- file1 file2
Fifth pass through the for loop:
The value of $i is --. The break command in the associated branch of
the case construction causes the for loop to exit. Following the shift
command, the values of parameters $1, $2 and $* are:
$1 = file1
$2 = file2
$* = -b -o arg -a -- file1 file2
Page 7 Reliant UNIX 5.44 Printed 11/98
getopt(1) getopt(1)
The script would then continue with further code for handling these
arguments, and would then process them together with the options and
their arguments.
SEE ALSO
getoptcvt(1), getopts(1), sh(1), getopt(3C).
Page 8 Reliant UNIX 5.44 Printed 11/98