NetBSD/usr.bin/getopt/getopt.1

122 lines
2.6 KiB
Groff
Raw Normal View History

1999-12-01 15:03:16 +03:00
.\" $NetBSD: getopt.1,v 1.9 1999/12/01 12:03:16 lukem Exp $
1993-06-21 16:43:56 +04:00
.Dd June 21, 1993
.Dt GETOPT 1
.Os
.Sh NAME
.Nm getopt
.Nd parse command options
.Sh SYNOPSIS
1997-10-19 06:13:39 +04:00
.Li args=\`getopt optstring $*\`
.Pp
.Li set \-\- \`getopt optstring $*\`
1993-06-21 16:43:56 +04:00
.Sh DESCRIPTION
1997-10-19 06:13:39 +04:00
.Nm
1993-06-21 16:43:56 +04:00
is used to break up options in command lines for easy parsing by
shell procedures, and to check for legal options.
.Op Optstring
is a string of recognized option letters (see
1999-12-01 15:03:16 +03:00
.Xr getopt 3) ;
1993-06-21 16:43:56 +04: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 white space.
The special option
.Dq \-\-
1993-06-21 16:43:56 +04:00
is used to delimit the end of the options.
1997-10-19 06:13:39 +04:00
.Nm
1993-06-21 16:43:56 +04:00
will place
.Dq \-\-
1993-06-21 16:43:56 +04:00
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
.Dq \-
1993-06-21 16:43:56 +04:00
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
.Op a
and
.Op b ,
and the option
1999-12-01 15:03:16 +03:00
.Op c ,
1993-06-21 16:43:56 +04:00
which requires an argument.
.Pp
.Bd -literal -offset indent
1999-12-01 15:03:16 +03:00
args=\`getopt abc: $*\`
if [ $? != 0 ]; then
1993-06-21 16:43:56 +04:00
echo 'Usage: ...'
exit 2
fi
set \-\- $args
1999-12-01 15:03:16 +03:00
for i; do
shift
case "$i"; in
1993-06-21 16:43:56 +04:00
\-a|\-b)
1999-12-01 15:03:16 +03:00
flag=$i
;;
\-c)
carg=$1; shift
;;
1993-06-21 16:43:56 +04:00
\-\-)
1999-12-01 15:03:16 +03:00
break
;;
1993-06-21 16:43:56 +04:00
esac
done
.Ed
.Pp
This code will accept any of the following as equivalent:
.Pp
.Bd -literal -offset indent
1999-12-01 15:03:16 +03:00
cmd \-acarg file file
cmd \-a \-c arg file file
cmd \-carg -a file file
cmd \-a \-carg \-\- file file
1993-06-21 16:43:56 +04:00
.Ed
.Pp
.St -p1003.2
mandates that the
1997-10-19 06:13:39 +04:00
.Xr sh 1
set command return the value of 0 for the exit status. Therefore,
the exit status of the
1997-10-19 06:13:39 +04:00
.Nm
command is lost when
1997-10-19 06:13:39 +04:00
.Nm
and the
1997-10-19 06:13:39 +04:00
.Xr sh 1
set command are used on the same line. The example given
is one way to detect errors found by
1997-10-19 06:13:39 +04:00
.Nm "" .
1993-06-21 16:43:56 +04:00
.Sh SEE ALSO
.Xr sh 1 ,
.Xr getopt 3
.Sh DIAGNOSTICS
1997-10-19 06:13:39 +04:00
.Nm
1993-06-21 16:43:56 +04:00
prints an error message on the standard error output when it
encounters an option letter not included in
.Op optstring .
.Sh HISTORY
Written by Henry Spencer, working from a Bell Labs manual page.
Behavior believed identical to the Bell version.
.Sh BUGS
Whatever
.Xr getopt 3
has.
.Pp
1994-01-11 05:21:43 +03:00
Arguments containing white space or embedded shell metacharacters
1993-06-21 16:43:56 +04:00
generally will not survive intact; this looks easy to fix but isn't.
.Pp
The error message for an invalid option is identified as coming
from
1997-10-19 06:13:39 +04:00
.Nm
1993-06-21 16:43:56 +04:00
rather than from the shell procedure containing the invocation
of
1997-10-19 06:13:39 +04:00
.Nm "" ;
1993-06-21 16:43:56 +04:00
this again is hard to fix.
.Pp
The precise best way to use the
1997-10-19 06:13:39 +04:00
.Ic set
1993-06-21 16:43:56 +04:00
command to set the arguments without disrupting the value(s) of
1997-10-19 06:13:39 +04:00
shell options varies from one shell version to another.