irix-657m-src/eoe/man/man1/getopt.1

'\"macro stdmacro
.if n .pH g1.getopt @(#)getopt	41.8 of 5/26/91
.\" Copyright 1991 UNIX System Laboratories, Inc.
.\" Copyright 1989, 1990 AT&T
.nr X
.if \nX=0 .ds x} getopt 1 "Essential Utilities" "\&"
.if \nX=1 .ds x} getopt 1 "Essential Utilities"
.if \nX=2 .ds x} getopt 1 "" "\&"
.if \nX=3 .ds x} getopt "" "" "\&"
.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
\f4getopt\f1 \- parse command options
.SH SYNOPSIS
\f4set \-\- \*`getopt\f1
.I optstring
\f4$\(**\*`\f1
.SH DESCRIPTION
The
\f4getopts\fP(1)
command supersedes
\f4getopt\fP.
.ig
\f4getopt\fP(1)
may not be supported in a future release.
..
For more information, see the
NOTES
below.
.PP
\f4getopt\fP
is used to break up options in command lines for easy parsing by shell
procedures and to check for legal options.
It recognizes supplementary code set characters
in the argument given to \f2optstring\fP
according to the locale specified in the \f4LC_CTYPE\fP
environment variable [see \f4LANG\fP on \f4environ\fP(5)].
.PP
.I optstring\^
is a string of recognized option letters; see \f4getopt\fP(3C).
If a letter is \%followed by a colon, the option
is expected to have an argument which may or
may not be separated from it by white space.
The special option \f4\-\-\fP is used to delimit the end of the
options.
If it is used explicitly,
\f4getopt\fP
recognizes it;
otherwise,
\f4getopt\fP
generates it;
in either case,
\f4getopt\fP
places it
at the end
of the options.
The positional parameters (\f4$1 $2\fP .\|.\|.\|) of the shell are reset
so that each option
is preceded by a \f4\-\fP and is in its own positional parameter;
each option
argument is also parsed into its own positional parameter.
.SH EXAMPLE
The following code fragment 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 argument:
.PP
.RS
.nf
.ft 4
.ta +.5i +1i
set \-\- \*`getopt abo: $\(**\*`
if [ $? != 0 ]
then
	echo $USAGE
	exit 2
fi
for i in $\(**
do
	case $i in
	\-a \(bv \-b)	FLAG=$i; shift;;
	\-o)	OARG=$2; shift 2;;
	\-\-)	shift; break;;
	esac
done
.fi
.ta
.ft 1
.RE
.PP
This code accepts any of the following as equivalent:
.PP
.RS
.nf
.ft 4
cmd \-aoarg file file
cmd \-a \-o arg file file
cmd \-oarg \-a file file
cmd \-a \-oarg \-\- file file
.fi
.ft 1
.RE
.bp
.SH FILES
.TP
\f4/usr/lib/locale/\f2locale\f4/LC_MESSAGES/uxcore\f1
language-specific message file [See \f4LANG\fP on \f4environ\f1(5).]
.SH SEE ALSO
\f4getopts\fP(1), \f4sh\fP(1),
\f4getopt\fP(3C)
.SH DIAGNOSTICS
\f4getopt\fP
prints an error message on
the standard error
when it encounters an option letter not included in
.IR optstring .
.SH NOTES
\f4getopt\fP
may not be supported in a future release.
For this release a conversion tool has been provided,
\f4getoptcvt\fP.
For more information about
\f4getopts\fP
and
\f4getoptcvt\fP, 
see
\f4getopts\fP(1).
.PP
Reset \f4OPTIND\fP to 1
when rescanning the options.
.P
\f4getopt\fP
does not support
the part of Rule 8 of the command syntax standard
[see
\f4intro\fP(1)]
that permits groups of option-arguments following an
option to be separated by white space and quoted.
For example,
.PP
.RS
\f4cmd \-a \-b \-o "xxx z yy" file\fP
.RE
.P
is not handled correctly.
To correct this deficiency,
use the \f4getopts\fP command
in place of
\f4getopt\fP.
.PP
If an option that takes an option-argument is followed by a value that
is the same as one of the options listed in
.I optstring\^
(referring to the earlier
EXAMPLE
section, but using the following
command line:
\f4cmd -o -a file\fP),
\f4getopt\fP
always treats
\f4\-a\f1
as an option-argument to
\f4\-o\f1;
it never recognizes
\f4\-a\f1
as an option.
For this case, the
\f4for\f1
loop in the example shifts past the
.I file
argument.