Libc-825.40.1.tar.gz

[apple/libc.git] / stdlib / FreeBSD / getopt.3

diff --git a/stdlib/FreeBSD/getopt.3 b/stdlib/FreeBSD/getopt.3
index 828b786696ec37ba46a34f069d3586075aca7923..ec9bf198096f03f60cc048b075df7cdb1fd759fc 100644 (file)
--- 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.
 .\"
 .\" 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.
 .\" 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.
 .\" 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
 .\" 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
 .\"
 .Dd April 27, 1995
 .Dt GETOPT 3


@@ -43,12 +41,12 @@
 .Sh SYNOPSIS
 .In unistd.h
 .Vt extern char *optarg ;
 .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
 .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
 .Sh DESCRIPTION
 The
 .Fn getopt


@@ -97,7 +95,7 @@ saves the last
 option character returned by
 .Fn getopt .
 .Pp
 option character returned by
 .Fn getopt .
 .Pp

-The variable
+The variables

 .Va opterr
 and
 .Va optind
 .Va opterr
 and
 .Va optind


@@ -122,12 +120,7 @@ must be reinitialized.
 .Pp
 The
 .Fn getopt
 .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 --
 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.
 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
 .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
 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
 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
 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 \- ;
 .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
 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.
 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
 .Sh HISTORY
 The
 .Fn getopt


@@ -209,7 +237,7 @@ This was changed by
 to decouple
 .Fn getopt
 from
 to decouple
 .Fn getopt
 from

-.Pa <stdio.h> .
+.In stdio.h .

 .Pp
 A single dash
 .Dq Li -
 .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 .
 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.
 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
 .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 .
 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
 .Bd -literal -offset indent

-int length;
+int ch;
+long length;

 char *p, *ep;
 
 while ((ch = getopt(argc, argv, "0123456789")) != -1)
 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];
        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),
                        length = strtol((p = argv[optind] + 1),

-                           &ep, 10);
+                           \*[Am]ep, 10);

                        optind++;
                        optreset = 1;
                } else
                        usage();
                        optind++;
                        optreset = 1;
                } else
                        usage();

-               if (*ep != '\0')
+               if (*ep != '\e0')

                        errx(EX_USAGE, "illegal number -- %s", p);
                break;
        }
                        errx(EX_USAGE, "illegal number -- %s", p);
                break;
        }