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 5e99329..05c7252 100644 (file)
--- a/usr/src/lib/libc/stdlib/getopt.3
+++ b/usr/src/lib/libc/stdlib/getopt.3
@@ -1,81 +1,151 @@
-.\" 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 the above copyright notice and this paragraph are
-.\" duplicated in all such forms and that any documentation,
-.\" advertising materials, and other materials related to such
-.\" distribution and use acknowledge that the software was developed
-.\" by the University of California, 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'' AND WITHOUT ANY EXPRESS OR
-.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
-.\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+.\" %sccs.include.redist.man%

 .\"
 .\"

-.\"    @(#)getopt.3    6.13 (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
-.nf
-int getopt(argc, argv, optstring)
-int argc;
-char **argv;
-char *optstring;
-.sp
-extern char *optarg;
-extern int optind;
-extern int opterr;
-.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.
-.PP
+.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
 On return from

-.IR getopt ,
-optarg is set to point to the start of any option argument.
-.I Optind
-contains the
-.I argv
-index of the next argument to be processed.
-.PP
-.I Opterr
+.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
 and

-.I optind
+.Va optind

 are both initialized to 1.
 are both initialized to 1.

-.PP
+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),
 When all options have been processed (i.e., up to the first non-option
 argument),

-.I getopt
-returns EOF.
-The special option ``\-\-'' may be used to delimit the end of the options;
-EOF will be returned, and the ``\-\-'' will be skipped.
-.SH DIAGNOSTICS
-.I Getopt
-prints an error message on
-.I stderr
-and returns a question mark (``?'') when it encounters an option
-letter not included in
-.IR optstring ,
-or it encounters an option that requires an argument which is not
-supplied.
+.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
 Setting

-.I opterr
+.Va opterr

 to a zero will disable these error messages.
 to a zero will disable these error messages.

-.SH EXAMPLE
-.nf
-.in +5
+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 int optind;
 int bflag, ch, fd;
 extern char *optarg;
 extern int optind;
 int bflag, ch, fd;


@@ -89,48 +159,55 @@ 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);
+                           "myname: %s: %s\en", optarg, strerror(errno));

                        exit(1);
                }
                break;
        case '?':
        default:
                usage();
                        exit(1);
                }
                break;
        case '?':
        default:
                usage();

-       }
+}

 argc -= optind;
 argv += optind;
 argc -= optind;
 argv += optind;

-.fi
-.SH BUGS
-Option arguments are allowed to begin with ``\-''; this is reasonable but
-reduces the amount of error checking possible.
-.PP
-A single dash (``-'') may be specified as an character in
-.IR optstring ,
+.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
 however it should

-.B never
+.Em never

 have an argument associated with it.
 This allows
 have an argument associated with it.
 This allows

-.I getopt
-to be used with programs that expect ``-'' as an option flag.
+.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
 This practice is wrong, and should not be used in any current development.
 It is provided for backward compatibility

-.BR only .
+.Em only .

 By default, a single dash causes
 By default, a single dash causes

-.I getopt
-to return EOF.
+.Fn getopt
+to return
+.Dv EOF .

 This is, we believe, compatible with System V.
 This is, we believe, compatible with System V.

-.PP
+.Pp

 It is also possible to handle digits as option letters.
 This allows
 It is also possible to handle digits as option letters.
 This allows

-.I getopt
-to be used with programs that expect a number (``-3'') as an option.
+.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
 This practice is wrong, and should not be used in any current development.
 It is provided for backward compatibility

-.BR only .
-The following code fragment works fairly well.
-.sp
-.nf
-.in +5
+.Em only .
+The following code fragment works in most cases.
+.Bd -literal -offset indent

 int length;
 char *p;
 
 int length;
 char *p;
 


@@ -146,4 +223,4 @@ while ((c = getopt(argc, argv, "0123456789")) != EOF)
                break;
        }
 }
                break;
        }
 }

-.fi
+.Ed