added whiteout

[unix-history] / usr / src / lib / libc / stdlib / getopt.3

diff --git a/usr/src/lib/libc/stdlib/getopt.3 b/usr/src/lib/libc/stdlib/getopt.3
index 73d08c1..05c7252 100644 (file)
--- a/usr/src/lib/libc/stdlib/getopt.3
+++ b/usr/src/lib/libc/stdlib/getopt.3
@@ -1,155 +1,226 @@
-.\" Copyright (c) 1988 Regents of the University of California.
-.\" All rights reserved.
+.\" Copyright (c) 1988, 1991, 1993
+.\"    The Regents of the University of California.  All rights reserved.

 .\"
 .\"

-.\" Redistribution and use in source and binary forms are permitted
-.\" provided that this notice is preserved and that due credit is given
-.\" to the University of California at Berkeley. The name of the University
-.\" may not be used to endorse or promote products derived from this
-.\" software without specific prior written permission. This software
-.\" is provided ``as is'' without express or implied warranty.
+.\" %sccs.include.redist.man%

 .\"
 .\"

-.\"    @(#)getopt.3    6.6 (Berkeley) %G%
+.\"     @(#)getopt.3   8.4 (Berkeley) %G%

 .\"
 .\"

-.TH GETOPT 3 ""
-.UC 6
-.SH NAME
-getopt \- get option letter from argv
-.SH SYNOPSIS
-.ft B
-int getopt(argc, argv, optstring)
-.br
-int argc;
-.br
-char **argv;
-.br
-char *optstring;
-.sp
+.Dd 
+.Dt GETOPT 3
+.Os BSD 4.3
+.Sh NAME
+.Nm getopt
+.Nd get option character from command line argument list
+.Sh SYNOPSIS
+.Fd #include <stdlib.h>
+.Vt extern char *optarg;
+.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"
+.Sh DESCRIPTION
+The
+.Fn getopt
+function incrementally parses a command line argument list
+.Fa argv
+and returns the next
+.Em known
+option character.
+An option character is
+.Em known
+if it has been specified in the string of accepted option characters,
+.Fa optstring .
+.Pp
+The option string
+.Fa optstring
+may contain the following elements: individual characters, and
+characters followed by a colon to indicate an option argument
+is to follow.
+For example, an option string
+.Li "\&""x""
+recognizes an option
+.Dq Fl x ,
+and an option string
+.Li "\&""x:""
+recognizes an option and argument
+.Dq Fl x Ar argument .
+It does not matter to
+.Fn getopt
+if a following argument has leading white space.
+.Pp
+On return from
+.Fn getopt ,
+.Va optarg
+points to an option argument, if it is anticipated,
+and the variable
+.Va optind
+contains the index to the next
+.Fa argv
+argument for a subsequent call
+to
+.Fn getopt .
+The variable
+.Va optopt
+saves the last
+.Em known
+option character returned by
+.Fn getopt .
+.Pp
+The variable
+.Va opterr
+and
+.Va optind
+are both initialized to 1.
+The
+.Va optind
+variable may be set to another value before a set of calls to
+.Fn getopt
+in order to skip over more or less argv entries.
+.Pp
+In order to use
+.Fn getopt
+to evaluate multiple sets of arguments, or to evaluate a single set of
+arguments multiple times,
+the variable
+.Va optreset
+must be set to 1 before the second and each additional set of calls to
+.Fn getopt ,
+and the variable
+.Va optind
+must be reinitialized.
+.Pp
+The
+.Fn getopt
+function
+returns an
+.Dv EOF
+when the argument list is exhausted, or a non-recognized
+option is encountered.
+The interpretation of options in the argument list may be cancelled
+by the option
+.Ql --
+(double dash) which causes
+.Fn getopt
+to signal the end of argument processing and return an
+.Dv EOF . 
+When all options have been processed (i.e., up to the first non-option
+argument),
+.Fn getopt
+returns
+.Dv EOF .
+.Sh DIAGNOSTICS
+If the
+.Fn getopt
+function encounters a character not found in the string
+.Va optarg
+or detects
+a missing option argument it writes an error message and returns
+.Ql ?
+to the
+.Em stderr .
+Setting
+.Va opterr
+to a zero will disable these error messages.
+If
+.Va optstring 
+has a leading 
+.Ql \&:
+then a missing option argument causes a
+.Ql \&:
+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
+The
+.Va optreset
+variable was added to make it possible to call the
+.Fn getopt
+function multiple times.
+This is an extension to the
+.St -p1003.2
+specification.
+.Sh EXAMPLE
+.Bd -literal -compact

 extern char *optarg;
 extern char *optarg;

-.br

 extern int optind;
 extern int optind;

-.ft
-.SH DESCRIPTION
-.I Getopt
-returns the next option letter in
-.I argv
-that matches a letter in
-.IR optstring .
-.I Optstring
-is a string of recognized option letters;
-if a letter is followed by a colon, the option is expected to have
-an argument that may or may not be separated from it by white space.
-.I Optarg
-is set to point to the start of the option argument on return from
-.IR getopt .
-.PP
-.I Getopt
-places in
-.I optind
-the
-.I argv
-index of the next argument to be processed.
-Because
-.I optind
-is external, it is normally initialized to zero automatically
-before the first call to 
-.IR getopt .
-.PP
-When all options have been processed (i.e., up to the first
-non-option argument),
-.I getopt
-returns
-.BR EOF .
-The special option
-.B \-\-
-may be used to delimit the end of the options;
-.B EOF
-will be returned, and
-.B \-\-
-will be skipped.
-.SH DIAGNOSTICS
-.I Getopt
-prints an error message on
-.I stderr
-and returns a question mark
-.RB ( ? )
-when it encounters an option letter not included in
-.IR optstring .
-.SH EXAMPLE
-The following code fragment shows how one might process the arguments
-for a command that can take the mutually exclusive options
-.B a
-and
-.BR b ,
-and the options
-.B f
-and
-.BR o ,
-both of which require arguments:
-.PP
-.RS
-.nf
-main(argc, argv)
-int argc;
-char **argv;
-{
-       int c;
-       extern int optind;
-       extern char *optarg;
-       \&.
-       \&.
-       \&.
-       while ((c = getopt(argc, argv, "abf:o:")) != EOF)
-               switch (c) {
-               case `a':
-                       if (bflg)
-                               errflg++;
-                       else
-                               aflg++;
-                       break;
-               case `b':
-                       if (aflg)
-                               errflg++;
-                       else
-                               bproc();
-                       break;
-               case `f':
-                       ifile = optarg;
-                       break;
-               case `o':
-                       ofile = optarg;
-                       break;
-               case `?':
-               default:
-                       errflg++;
-                       break;
+int bflag, ch, fd;
+
+bflag = 0;
+while ((ch = getopt(argc, argv, "bf:")) != EOF)
+       switch(ch) {
+       case 'b':
+               bflag = 1;
+               break;
+       case 'f':
+               if ((fd = open(optarg, O_RDONLY, 0)) < 0) {
+                       (void)fprintf(stderr,
+                           "myname: %s: %s\en", optarg, strerror(errno));
+                       exit(1);

                }
                }

-       if (errflg) {
-               fprintf(stderr, "Usage: ...");
-               exit(2);
-       }
-       for (; optind < argc; optind++) {
-               \&.
-               \&.
-               \&.
+               break;
+       case '?':
+       default:
+               usage();
+}
+argc -= optind;
+argv += optind;
+.Ed
+.Sh HISTORY
+The
+.Fn getopt
+function appeared
+.Bx 4.3 .
+.Sh BUGS
+A single dash
+.Dq Li -
+may be specified as an character in
+.Fa optstring ,
+however it should
+.Em never
+have an argument associated with it.
+This allows
+.Fn getopt
+to be used with programs that expect
+.Dq Li -
+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 .
+By default, a single dash causes
+.Fn getopt
+to return
+.Dv EOF .
+This is, we believe, compatible with System V.
+.Pp
+It is also possible to handle digits as option letters.
+This allows
+.Fn getopt
+to be used with programs that expect a number
+.Pq Dq Li \&-\&3
+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 cases.
+.Bd -literal -offset indent
+int length;
+char *p;
+
+while ((c = getopt(argc, argv, "0123456789")) != EOF)
+       switch (c) {
+       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 = atoi(++p);
+               else
+                       length = atoi(argv[optind] + 1);
+               break;

        }
        }

-       \&.
-       \&.
-       \&.

 }
 }

-.RE
-.SH HISTORY
-Written by Henry Spencer, working from a Bell Labs manual page.
-Modified by Keith Bostic to behave more like the System V version.
-.SH BUGS
-``-'' may be specified as an option letter, however it should never have
-an argument associated with it.  This allows getopt to be used with
-programs that think that ``-'' means standard input.
-.PP
-Option arguments are allowed to begin with ``\-'';
-this is reasonable but reduces the amount of error checking possible.
-.PP
-.I Getopt
-is quite flexible but the obvious price must be paid:  there is much
-it could do that it doesn't, like
-checking mutually exclusive options, checking type of
-option arguments, etc.
+.Ed