d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge some fixes from NetBSD's getopt.3 v1.31:

Browse Source 
cleanup, add more sections, better explanation, declaration
This commit is contained in:
ache 2004-03-06 17:09:10 +00:00
parent c53e3b1fa9
commit e76a2d5e16
1 changed files with 88 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

131
lib/libc/stdlib/getopt.3
View File

@ -1,3 +1,5 @@
.\" $NetBSD: getopt.3,v 1.31 2003/09/23 10:26:54 wiz Exp $
.\"
.\" Copyright (c) 1988, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
@ -48,7 +50,7 @@
.Vt extern int opterr ;
.Vt extern int optreset ;
.Ft int
.Fn getopt "int argc" "char * const *argv" "const char *optstring"
.Fn getopt "int argc" "char * const argv[]" "const char *optstring"
.Sh DESCRIPTION
The
.Fn getopt
@ -97,7 +99,7 @@ saves the last
option character returned by
.Fn getopt .
.Pp
The variable
The variables
.Va opterr
and
.Va optind
@ -122,12 +124,7 @@ must be reinitialized.
.Pp
The
.Fn getopt
function
returns \-1
when the argument list is exhausted, or
.Ql ?\&
if a non-recognized
option is encountered.
function returns \-1 when the argument list is exhausted.
The interpretation of options in the argument list may be cancelled
by the option
.Ql --
@ -138,21 +135,75 @@ When all options have been processed (i.e., up to the first non-option
argument),
.Fn getopt
returns \-1.
.Sh RETURN VALUES
The
.Fn getopt
function returns the next known option character in
.Fa optstring .
If
.Fn getopt
encounters a character not found in
.Fa optstring
or if it detects a missing option argument,
it returns
.Ql \&?
(question mark).
If
.Fa optstring
has a leading
.Ql \&:
then a missing option argument causes
.Ql \&:
to be returned instead of
.Ql \&? .
In either case, the variable
.Va optopt
is set to the character that caused the error.
The
.Fn getopt
function returns \-1 when the argument list is exhausted.
.Sh EXAMPLES
.Bd -literal -compact
extern char *optarg;
extern int optind;
int bflag, ch, fd;
bflag = 0;
while ((ch = getopt(argc, argv, "bf:")) != -1) {
switch (ch) {
case 'b':
bflag = 1;
break;
case 'f':
if ((fd = open(optarg, O_RDONLY, 0)) \*[Lt] 0) {
(void)fprintf(stderr,
"myname: %s: %s\en", optarg, strerror(errno));
exit(1);
}
break;
case '?':
default:
usage();
}
}
argc -= optind;
argv += optind;
.Ed
.Sh DIAGNOSTICS
If the
.Fn getopt
function encounters a character not found in the string
.Va optstring
.Fa optstring
or detects
a missing option argument it writes an error message to the
.Dv stderr
and returns
.Ql ?\& .
.Ql \&? .
Setting
.Va opterr
to a zero will disable these error messages.
If
.Va optstring
.Fa optstring
has a leading
.Ql \&:
then a missing option argument causes a
@ -161,9 +212,12 @@ to be returned in addition to suppressing any error messages.
.Pp
Option arguments are allowed to begin with
.Dq Li \- ;
this is reasonable but
reduces the amount of error checking possible.
.Sh EXTENSIONS
this is reasonable but reduces the amount of error checking possible.
.Sh SEE ALSO
.Xr getopt 1 ,
.Xr getopt_long 3 ,
.Xr getsubopt 3
.Sh STANDARDS
The
.Va optreset
variable was added to make it possible to call the
@ -172,27 +226,6 @@ function multiple times.
This is an extension to the
.St -p1003.2
specification.
.Sh EXAMPLES
.Bd -literal -compact
int bflag, ch, fd;
bflag = 0;
while ((ch = getopt(argc, argv, "bf:")) != -1)
switch (ch) {
case 'b':
bflag = 1;
break;
case 'f':
if ((fd = open(optarg, O_RDONLY, 0)) < 0)
err(1, "%s", optarg);
break;
case '?':
default:
usage();
}
argc -= optind;
argv += optind;
.Ed
.Sh HISTORY
The
.Fn getopt
@ -226,10 +259,20 @@ as an option flag.
This practice is wrong, and should not be used in any current development.
It is provided for backward compatibility
.Em only .
Care should be taken not to use
.Ql \&-
as the first character in
.Fa optstring
to avoid a semantic conflict with
.Tn GNU
.Fn getopt ,
which assigns different meaning to an
.Fa optstring
that begins with a
.Ql \&- .
By default, a single dash causes
.Fn getopt
to return \-1.
This is, we believe, compatible with System V.
.Pp
It is also possible to handle digits as option letters.
This allows
@ -240,9 +283,10 @@ as an option.
This practice is wrong, and should not be used in any current development.
It is provided for backward compatibility
.Em only .
The following code fragment works in most (but not all) cases.
The following code fragment works in most cases.
.Bd -literal -offset indent
int length;
int ch;
long length;
char *p, *ep;
while ((ch = getopt(argc, argv, "0123456789")) != -1)
@ -250,16 +294,17 @@ while ((ch = getopt(argc, argv, "0123456789")) != -1)
case '0': case '1': case '2': case '3': case '4':
case '5': case '6': case '7': case '8': case '9':
p = argv[optind - 1];
if (p[0] == '-' && p[1] == ch && !p[2])
length = strtol(++p, &ep, 10);
else if (argv[optind] && argv[optind][1] == ch) {
if (p[0] == '-' \*[Am]\*[Am] p[1] == ch \*[Am]\*[Am] !p[2]) {
length = ch - '0';
ep = "";
} else if (argv[optind] \*[Am]\*[Am] argv[optind][1] == ch) {
length = strtol((p = argv[optind] + 1),
&ep, 10);
\*[Am]ep, 10);
optind++;
optreset = 1;
} else
usage();
if (*ep != '\0')
if (*ep != '\e0')
errx(EX_USAGE, "illegal number -- %s", p);
break;
}