macro and text revision (-mdoc version 3)

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

 .\" All rights reserved.
 .\"
 .\" %sccs.include.redist.man%
 .\"
 .\" All rights reserved.
 .\"
 .\" %sccs.include.redist.man%
 .\"

-.\"    @(#)getopt.3    6.15 (Berkeley) %G%
+.\"     @(#)getopt.3   6.16 (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 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 +112,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 +181,4 @@ while ((c = getopt(argc, argv, "0123456789")) != EOF)
                break;
        }
 }
                break;
        }
 }

-.fi
+.Ed