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

cleanup, add more sections, better explanation, declaration

1 files changed, 88 insertions, 43 deletions

diff --git a/lib/libc/stdlib/getopt.3 b/lib/libc/stdlib/getopt.3
index 1a840a2..bada90e 100644
--- a/lib/libc/stdlib/getopt.3
+++ b/lib/libc/stdlib/getopt.3
@@ -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;
 	}