From ce8bd08be4a8bb0e70663a4aa4f6e79f43d29867 Mon Sep 17 00:00:00 2001 From: ache Date: Sat, 6 Mar 2004 17:09:10 +0000 Subject: Merge some fixes from NetBSD's getopt.3 v1.31: cleanup, add more sections, better explanation, declaration --- lib/libc/stdlib/getopt.3 | 131 +++++++++++++++++++++++++++++++---------------- 1 file changed, 88 insertions(+), 43 deletions(-) (limited to 'lib/libc') 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; } -- cgit v1.1