xref: /freebsd/usr.bin/getopt/getopt.1 (revision 18b3ba267cff8d71364cbabb5429eccf1e79bba4)

.Dd April 3, 1999
.Dt GETOPT 1
.Os
.Sh NAME
.Nm getopt
.Nd parse command options
.Sh SYNOPSIS
.Ic set \-\- \`getopt Ar optstring
.Qq $@
\`
.Sh DESCRIPTION
.Nm Getopt
is used to break up options in command lines for easy parsing by
shell procedures, and to check for legal options.
.Ar Optstring
is a string of recognized option letters (see
.Xr getopt 3
);
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
.Ql \-\-
is used to delimit the end of the options.
.Nm Getopt
will place
.Ql \-\-
in the arguments at the end of the options,
or recognize it if used explicitly.
The shell arguments
(\fB$1 $2\fR ...) are reset so that each option is
preceded by a
.Ql \-
and in its own shell argument;
each option argument is also in its own shell argument.
.Sh EXAMPLE
The following code fragment shows how one might process the arguments
for a command that can take the options
.Fl a
and
.Fl b ,
and the option
.Fl o ,
which requires an argument.
.Pp
.Bd -literal -offset indent
tmp=$(getopt abo: "$@")
if [ $? != 0 ]
then
	echo 'Usage: ...'
	exit 2
fi
eval set \-\- $tmp
for i
do
	case "$i"
	in
		\-a|\-b)
			echo flag $i set; sflags="${i#-}$sflags"; shift;;
		\-o)
			echo oarg is "'"$2"'"; oarg="$2"; shift; shift;;
		\-\-)
			shift; break;;
	esac
done
echo single-char flags: $sflags
echo oarg is "'"$oarg"'"
.Ed
.Pp
This code will accept any of the following as equivalent:
.Pp
.Bd -literal -offset indent
cmd \-aoarg file file
cmd \-a \-o arg file file
cmd \-oarg -a file file
cmd \-a \-oarg \-\- file file
.Pp
Test your scripts with calls like this
.Pp
cmd \-ab \-o 'f \-z'
.Pp
to verify that they work with parameters/filenames that have
whitespace in them.
.Ed
.Sh SEE ALSO
.Xr sh 1 ,
.Xr getopt 3
.Sh DIAGNOSTICS
.Nm Getopt
prints an error message on the standard error output and exits with
status > 0 when it encounters an option letter not included in
.Ar optstring .
.Sh HISTORY
Written by Henry Spencer, working from a Bell Labs manual page.
Behavior believed identical to the Bell version. Example replaced in
.Fx
version 3.2 and 4.0.
.Sh BUGS
Whatever
.Xr getopt 3
has.
.Pp
It is hard to get command switch parsing right in shell scripts,
especially with arguments containing whitespace or embedded shell
metacharacters. This version of
.Nm getopt
and the example in this manpage have been fixed to avoid traditional
problems. They have been tested with
.Fx
.Xr sh 1
and with GNU bash. Note that bash has a builtin
.Nm getopt .
In shells with builtin
.Nm getopt
you need to call getopt with a full path to get the external version
described here.
.Pp
The error message for an invalid option is identified as coming
from
.Nm getopt
rather than from the shell procedure containing the invocation
of
.Nm getopt ;
this is hard to fix.