X-Git-Url: https://git.subgeniuskitty.com/unix-history/.git/blobdiff_plain/a9647b53cc82fed22e6bbee47b15db9b2a7d88f6..ae59e04cb5f746d72d5e3e8c84dad7862c9b50e7:/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 8df4b13870..d3e7bb46bd 100644
--- 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%
 .\"
-.\"	@(#)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
-.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
-.I optind
+.Va optind
 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,
-.I optind
+.Va optind
 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),
-.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
-.I opterr
+.Va opterr
 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;
@@ -86,48 +112,60 @@ while ((ch = getopt(argc, argv, "bf:")) != EOF)
 	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();
-	}
+}
 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.
-.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
-.B never
+.Em never
 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
-.BR only .
+.Em only .
 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.
-.PP
+.Pp
 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
-.BR only .
+.Em only .
 The following code fragment works fairly well.
-.sp
-.nf
-.in +5
+.Bd -literal -offset indent
 int length;
 char *p;
 
@@ -143,4 +181,4 @@ while ((c = getopt(argc, argv, "0123456789")) != EOF)
 		break;
 	}
 }
-.fi
+.Ed