+.\" $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.
.\"
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
-.\" 3. All advertising materials mentioning features or use of this software
-.\" must display the following acknowledgement:
-.\" This product includes software developed by the University of
-.\" California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\" SUCH DAMAGE.
.\"
.\" @(#)getopt.3 8.5 (Berkeley) 4/27/95
-.\" $FreeBSD: src/lib/libc/stdlib/getopt.3,v 1.21 2002/12/04 18:57:45 ru Exp $
+.\" $FreeBSD: src/lib/libc/stdlib/getopt.3,v 1.26 2007/01/09 00:28:10 imp Exp $
.\"
.Dd April 27, 1995
.Dt GETOPT 3
.Sh SYNOPSIS
.In unistd.h
.Vt extern char *optarg ;
-.Vt extern int optind ;
-.Vt extern int optopt ;
-.Vt extern int opterr ;
-.Vt extern int optreset ;
+.Vt extern int optind ;
+.Vt extern int optopt ;
+.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
option character returned by
.Fn getopt .
.Pp
-The variable
+The variables
.Va opterr
and
.Va optind
.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 --
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
+#include <unistd.h>
+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
.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
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
to decouple
.Fn getopt
from
-.Pa <stdio.h> .
+.In stdio.h .
.Pp
A single dash
.Dq Li -
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
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)
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;
}
projects / apple / libc.git / blobdiff