'\"macro stdmacro
.if n .pH g1.getopts @(#)getopts	40.4 of 10/10/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} getopts 1 "Essential Utilities" "\&"
.if \nX=1 .ds x} getopts 1 "Essential Utilities"
.if \nX=2 .ds x} getopts 1 "" "\&"
.if \nX=3 .ds x} getopts "" "" "\&"
.TH \*(x}
.if t .ds ' \h@.05m@\s+4\v@.333m@\'\v@-.333m@\s-4\h@.05m@
.if n .ds ' '
.if t .ds ` \h@.05m@\s+4\v@.333m@\`\v@-.333m@\s-4\h@.05m@
.if n .ds ` `
.SH NAME
\f4getopts\f1, \f4getoptcvt\f1 \- parse command options
.SH SYNOPSIS
\f4getopts\f1
.I optstring
.I name
[
.IR arg " ... ]"
.PP
\f4/usr/lib/getoptcvt\f1 [ \f4\-b\f1 ]
.I file
.SH DESCRIPTION
\f4getopts\fP
is used by shell procedures to parse positional parameters 
and to check for valid options.
It supports all applicable rules of the command syntax standard
(see Rules 3-10,
\f4intro\fP(1)).
It should be used in place of the
\f4getopt\fP
command.
(See the
.SM NOTES
section below.)
.PP
.I optstring
must contain the option letters the command using
\f4getopts\fP
will recognize;
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.
.PP
Each time it is invoked,
\f4getopts\fP
places the next option in the shell variable
.I name
and the index of the next argument to be processed
in the shell variable
\f4OPTIND\f1.
Whenever the shell or a shell
procedure is invoked,
\f4OPTIND\f1
is initialized to
\f41\f1.
.PP
When an option requires an option-argument,
\f4getopts\fP
places it in the
shell variable
\f4OPTARG\f1.
.PP
If
an illegal option is encountered,
\f4?\f1
will be placed in
.IR name\^ .
.PP
When the end of options is encountered,
\f4getopts\fP
exits with a non-zero
exit status.  The special option
\f4\-\-\f1
may be used to delimit the end of the
options.
.PP
By default,
\f4getopts\fP
parses the positional parameters.  If extra arguments
.RI ( arg
\&.\|.\|.)
are given on the
\f4getopts\fP
command line,
\f4getopts\fP
parsees them instead.
.P
\f4/usr/lib/getoptcvt\fP
reads the shell script in
.IR file\^ ,
converts it to use
\f4getopts\fP
instead of
\f4getopt\fP,
and writes the results on the standard output.
.TP
\f4\-b\f1
Make the converted script portable to earlier releases of the
.SM UNIX
system.
\f4/usr/lib/getoptcvt\fP
modifies the shell script in
.I file 
so that when the resulting shell script is executed,
it determines at run time whether to invoke
\f4getopts\fP
or
\f4getopt\fP.
.PP
So all new commands will adhere to the command syntax standard
described in
\f4intro\fP(1),
they should use
\f4getopts\fP
or
\f4getopt\fP
to parse positional parameters and check for options that are valid
for that command
(see the
.SM NOTES
section below).
.SH EXAMPLE
The following fragment of a shell program shows how one might process the arguments
for a command that can take the options
\f4a\f1
or
\f4b\f1,
as well as the option
\f4o\f1,
which requires an option-argument:
.PP
.RS
.nf
.ft 4
.ta +.5i +1i
while getopts abo: c
do
	case $c in
	a \(bv b)	FLAG=$c;;
	o)	OARG=$OPTARG;;
	\\?)	echo $USAGE
		exit 2;;
	esac
done
shift \*`expr $OPTIND \- 1\*`
.fi
.ta
.ft1
.RE
.PP
This code accepts any of the following as equivalent:
.PP
.RS
.nf
.ft 4
cmd \-a \-b \-o "xxx z yy" file
cmd \-a \-b \-o "xxx z yy" \-\- file
cmd \-ab \-o xxx,z,yy file
cmd \-ab \-o "xxx z yy" file
cmd \-o xxx,z,yy \-b \-a file
.fi
.ft 1
.RE
.SH SEE ALSO
\f4intro\fP(1), \f4sh\fP(1).
.br
\f4getopt\fP(3C) in the
.IR "Programmer's Reference Manual\^" .
.SH NOTES
Although
the following command syntax rule [see
\f4intro\fP(1)]
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
.SM EXAMPLE
section above,
\f4a\f1
and
\f4b\f1
are options, and the option
\f4o\f1
requires an option-argument.
The following example violates
Rule 5:  options with
option-arguments must not be grouped with other options:
.PP
.RS
.ft 4
cmd \-aboxxx file
.ft 1
.RE
.P
The following example violates
Rule 6: there must be white space after an option
that takes an option-argument:
.PP
.RS
.ft 4
cmd \-ab \-oxxx file
.ft 1
.RE
.PP
Changing the value of the shell variable
\f4OPTIND\f1
or parsing different sets of arguments may lead to unexpected results.
.SH DIAGNOSTICS
\f4getopts\fP
prints an error message on
the standard error
when it encounters an option letter not included in
.IR optstring .
.\"	@(#)getopt.1	6.2 of 9/2/83
.Ee
