BSD 4_3_Net_2 release

[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 8df4b13..c21a0a7 100644 (file)
--- a/usr/src/lib/libc/stdlib/getopt.3
+++ b/usr/src/lib/libc/stdlib/getopt.3
@@ -1,78 +1,130 @@
-.\" Copyright (c) 1988 Regents of the University of California.
+.\" Copyright (c) 1988, 1991 Regents of the University of California.

 .\" All rights reserved.
 .\"
 .\" All rights reserved.
 .\"

-.\" %sccs.include.redist.man%
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 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.

 .\"
 .\"

-.\"    @(#)getopt.3    6.15 (Berkeley) %G%
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.

 .\"
 .\"

-.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
+.\"     @(#)getopt.3   6.16 (Berkeley) 4/19/91
+.\"
+.Dd April 19, 1991
+.Dt GETOPT 3
+.Os BSD 4.3
+.Sh NAME
+.Nm getopt
+.Nd get option letter from argv
+.Sh SYNOPSIS
+.Fd #include <stdlib.h>
+.Vt extern char *optarg
+.Vt extern int   optind
+.Vt extern int   opterr
+.Ft int
+.Fn getopt "int argc" "char * const *argv" "const char *optstring"
+.Sh DESCRIPTION
+The
+.Fn getopt
+function gets 
+the next
+.Em known
+option character from
+.Fa argv .
+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 characters; letters and
+letters followed by a colon to indicate an option argument
+is to follow. 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 .
+.Pp
+The variable
+.Va opterr

 and
 and

-.I optind
+.Va optind

 are both initialized to 1.
 In order to use
 are both initialized to 1.
 In order to use

-.I getopt
+.Fn getopt

 to evaluate multiple sets of arguments, or to evaluate a single set of
 arguments multiple times,
 to evaluate multiple sets of arguments, or to evaluate a single set of
 arguments multiple times,

-.I optind
+.Va optind

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

-.PP
+.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 error message
+.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
+.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;


@@ -86,48 +138,60 @@ 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: unable to read file %s.\en", optarg);
+                       exit(1) ;

                }
                break;
        case '?':
        default:
                usage();
                }
                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
+.Ed
+.Sh HISTORY
+The
+.Fn getopt
+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.
 reduces the amount of error checking possible.

-.PP
-A single dash (``-'') may be specified as an character in
-.IR optstring ,
+.Pp
+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 .
+.Em only .

 The following code fragment works fairly well.
 The following code fragment works fairly well.

-.sp
-.nf
-.in +5
+.Bd -literal -offset indent

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


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

-.fi
+.Ed