X-Git-Url: https://git.saurik.com/apple/libc.git/blobdiff_plain/9385eb3d10ebe5eb398c52040ec3dbfba9b0cdcf..a28bf75d63c6a64e4c3b417c6052e45f42c6cedd:/stdlib/FreeBSD/getopt.3?ds=inline diff --git a/stdlib/FreeBSD/getopt.3 b/stdlib/FreeBSD/getopt.3 index 828b786..ec9bf19 100644 --- a/stdlib/FreeBSD/getopt.3 +++ b/stdlib/FreeBSD/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. .\" @@ -9,10 +11,6 @@ .\" 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. @@ -30,7 +28,7 @@ .\" 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 @@ -43,12 +41,12 @@ .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 @@ -97,7 +95,7 @@ saves the last option character returned by .Fn getopt . .Pp -The variable +The variables .Va opterr and .Va optind @@ -122,12 +120,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 +131,74 @@ 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 +#include +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 +207,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 +221,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 @@ -209,7 +237,7 @@ This was changed by to decouple .Fn getopt from -.Pa . +.In stdio.h . .Pp A single dash .Dq Li - @@ -226,10 +254,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 +278,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 +289,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; }