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 d3e7bb4..05c7252 100644 (file)
--- a/usr/src/lib/libc/stdlib/getopt.3
+++ b/usr/src/lib/libc/stdlib/getopt.3
@@ -1,31 +1,33 @@
-.\" Copyright (c) 1988, 1991 Regents of the University of California.
-.\" All rights reserved.
+.\" Copyright (c) 1988, 1991, 1993
+.\"    The Regents of the University of California.  All rights reserved.

 .\"
 .\" %sccs.include.redist.man%
 .\"
 .\"
 .\" %sccs.include.redist.man%
 .\"

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

 .\"
 .Dd 
 .Dt GETOPT 3
 .Os BSD 4.3
 .Sh NAME
 .Nm getopt
 .\"
 .Dd 
 .Dt GETOPT 3
 .Os BSD 4.3
 .Sh NAME
 .Nm getopt

-.Nd get option letter from argv
+.Nd get option character from command line argument list

 .Sh SYNOPSIS
 .Fd #include <stdlib.h>
 .Sh SYNOPSIS
 .Fd #include <stdlib.h>

-.Vt extern char *optarg
-.Vt extern int   optind
-.Vt extern int   opterr
+.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
 .Ft int
 .Fn getopt "int argc" "char * const *argv" "const char *optstring"
 .Sh DESCRIPTION
 The
 .Fn getopt

-function gets 
-the next
+function incrementally parses a command line argument list
+.Fa argv
+and returns the next

 .Em known
 .Em known

-option character from
-.Fa argv .
+option character.

 An option character is
 .Em known
 if it has been specified in the string of accepted option characters,
 An option character is
 .Em known
 if it has been specified in the string of accepted option characters,


@@ -33,9 +35,18 @@ if it has been specified in the string of accepted option characters,
 .Pp
 The option string
 .Fa optstring
 .Pp
 The option string
 .Fa optstring

-may contain the following characters; letters and
-letters followed by a colon to indicate an option argument
-is to follow. It does not matter to
+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
 .Fn getopt
 if a following argument has leading white space.
 .Pp


@@ -50,19 +61,35 @@ contains the index to the next
 argument for a subsequent call
 to
 .Fn getopt .
 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.
 .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,
 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
 .Va optind

-must be initialized to the number of argv entries to be skipped in each
-evaluation.
+must be reinitialized.

 .Pp
 The
 .Fn getopt
 .Pp
 The
 .Fn getopt


@@ -89,14 +116,34 @@ If the
 function encounters a character not found in the string
 .Va optarg
 or detects
 function encounters a character not found in the string
 .Va optarg
 or detects

-a missing option argument
-it writes error message
+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.
 .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;
 .Sh EXAMPLE
 .Bd -literal -compact
 extern char *optarg;


@@ -112,8 +159,8 @@ while ((ch = getopt(argc, argv, "bf:")) != EOF)
        case 'f':
                if ((fd = open(optarg, O_RDONLY, 0)) < 0) {
                        (void)fprintf(stderr,
        case 'f':
                if ((fd = open(optarg, O_RDONLY, 0)) < 0) {
                        (void)fprintf(stderr,

-                               "myname: unable to read file %s.\en", optarg);
-                       exit(1) ;
+                           "myname: %s: %s\en", optarg, strerror(errno));
+                       exit(1);

                }
                break;
        case '?':
                }
                break;
        case '?':


@@ -129,11 +176,6 @@ The
 function appeared
 .Bx 4.3 .
 .Sh BUGS
 function appeared
 .Bx 4.3 .
 .Sh BUGS

-Option arguments are allowed to begin with
-.Dq Li \- ;
-this is reasonable but
-reduces the amount of error checking possible.
-.Pp

 A single dash
 .Dq Li -
 may be specified as an character in
 A single dash
 .Dq Li -
 may be specified as an character in


@@ -164,7 +206,7 @@ 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 fairly well.
+The following code fragment works in most cases.

 .Bd -literal -offset indent
 int length;
 char *p;
 .Bd -literal -offset indent
 int length;
 char *p;