1
0
mirror of https://github.com/openbsd/src.git synced 2024-12-22 16:42:56 -08:00
openbsd-src/usr.bin/getopt/getopt.1

130 lines
2.9 KiB
Groff
Raw Permalink Normal View History

.\" $OpenBSD: getopt.1,v 1.20 2021/05/04 21:03:31 naddy Exp $
.\"
.\" This material, written by Henry Spencer, was released by him
.\" into the public domain and is thus not subject to any copyright.
.\"
.Dd $Mdocdate: May 4 2021 $
1995-10-18 01:37:01 -07:00
.Dt GETOPT 1
.Os
.Sh NAME
.Nm getopt
.Nd parse command options
.Sh SYNOPSIS
.Nm
.Ar optstring
.Va $*
1995-10-18 01:37:01 -07:00
.Sh DESCRIPTION
The
.Nm
utility cannot handle option arguments containing whitespace;
consider using the standard
.Ic getopts
shell built-in instead.
.Pp
.Nm
1995-10-18 01:37:01 -07:00
is used to break up options in command lines for easy parsing by
shell procedures, and to check for legal options.
.Ar optstring
1995-10-18 01:37:01 -07:00
is a string of recognized option letters (see
2000-04-14 19:15:09 -07:00
.Xr getopt 3 ) ;
1995-10-18 01:37:01 -07:00
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 whitespace.
However, if a letter is followed by two colons, the argument is optional
and may not be separated by whitespace \- this is an extension not
covered by POSIX.
1995-10-18 01:37:01 -07:00
The special option
2006-01-13 14:13:53 -08:00
.Sq --
1995-10-18 01:37:01 -07:00
is used to delimit the end of the options.
.Nm
1995-10-18 01:37:01 -07:00
will place
2006-01-13 14:13:53 -08:00
.Sq --
1995-10-18 01:37:01 -07:00
in the arguments at the end of the options,
or recognize it if used explicitly.
The shell arguments
2006-01-13 14:13:53 -08:00
.Pf ( Va $1 , $2 , ... )
are reset so that each option is
1995-10-18 01:37:01 -07:00
preceded by a
2006-01-13 14:13:53 -08:00
.Sq -
1995-10-18 01:37:01 -07:00
and in its own shell argument;
each option argument is also in its own shell argument.
2000-03-07 13:11:07 -08:00
.Sh EXAMPLES
1995-10-18 01:37:01 -07:00
The following code fragment shows how one might process the arguments
for a command that can take the options
2000-03-07 13:11:07 -08:00
.Fl a
1995-10-18 01:37:01 -07:00
and
2000-03-07 13:11:07 -08:00
.Fl b ,
1995-10-18 01:37:01 -07:00
and the option
2000-03-07 13:11:07 -08:00
.Fl o ,
1995-10-18 01:37:01 -07:00
which requires an argument.
.Bd -literal -offset indent
args=`getopt abo: $*`
if [ $? -ne 0 ]
1995-10-18 01:37:01 -07:00
then
echo 'Usage: ...'
exit 2
fi
set -- $args
while [ $# -ne 0 ]
1995-10-18 01:37:01 -07:00
do
case "$1"
1995-10-18 01:37:01 -07:00
in
2006-01-13 14:13:53 -08:00
-a|-b)
flag="$1"; shift;;
2006-01-13 14:13:53 -08:00
-o)
oarg="$2"; shift; shift;;
2006-01-13 14:13:53 -08:00
--)
1995-10-18 01:37:01 -07:00
shift; break;;
esac
done
.Ed
.Pp
This code will accept any of the following as equivalent:
.Bd -literal -offset indent
2006-01-13 14:13:53 -08:00
cmd -aoarg file file
cmd -a -o arg file file
cmd -oarg -a file file
cmd -a -oarg -- file file
1995-10-18 01:37:01 -07:00
.Ed
.Sh DIAGNOSTICS
.Nm
1995-10-18 01:37:01 -07:00
prints an error message on the standard error output when it
encounters an option letter not included in
.Ar optstring .
2000-03-07 13:11:07 -08:00
.Sh SEE ALSO
.Xr sh 1 ,
.Xr getopt 3
1995-10-18 01:37:01 -07:00
.Sh HISTORY
Written by Henry Spencer, working from a Bell Labs manual page.
Behavior believed identical to the Bell version.
.Sh CAVEATS
Note that the construction
.Pp
.Dl set -- `getopt optstring $*`
.Pp
is not recommended, as the exit value from
.Sy set
will prevent the exit value from
.Nm
from being determined.
1995-10-18 01:37:01 -07:00
.Sh BUGS
Whatever
.Xr getopt 3
has.
.Pp
Arguments containing whitespace or embedded shell metacharacters
2000-03-07 13:11:07 -08:00
generally will not survive intact; this looks easy to fix but isn't.
1995-10-18 01:37:01 -07:00
.Pp
The error message for an invalid option is identified as coming
from
.Nm
1995-10-18 01:37:01 -07:00
rather than from the shell procedure containing the invocation
of
.Nm getopt ;
this again is hard to fix.
.Pp
The precise best way to use the
.Sy set
1995-10-18 01:37:01 -07:00
command to set the arguments without disrupting the value(s) of
shell options varies from one shell version to another.