date and time created 90/05/16 12:49:58 by bostic

[unix-history] / usr / src / lib / libc / stdlib / getopt.3

.\" Copyright (c) 1988 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.
.\"
.\"	@(#)getopt.3	6.13 (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
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
and
.I optind
are both initialized to 1.
.PP
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.
Setting
.I opterr
to a zero will disable these error messages.
.SH EXAMPLE
.nf
.in +5
extern char *optarg;
extern int optind;
int bflag, ch, fd;

bflag = 0;
while ((ch = getopt(argc, argv, "bf:")) != EOF)
	switch(ch) {
	case 'b':
		bflag = 1;
		break;
	case 'f':
		if ((fd = open(optarg, O_RDONLY, 0)) < 0) {
			(void)fprintf(stderr,
			    "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
reduces the amount of error checking possible.
.PP
A single dash (``-'') may be specified as an character in
.IR optstring ,
however it should
.B never
have an argument associated with it.
This allows
.I getopt
to be used with programs that expect ``-'' 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 .
By default, a single dash causes
.I getopt
to return EOF.
This is, we believe, compatible with System V.
.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.
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
int length;
char *p;

while ((c = getopt(argc, argv, "0123456789")) != EOF)
	switch (c) {
	case '0': case '1': case '2': case '3': case '4':
	case '5': case '6': case '7': case '8': case '9':
		p = argv[optind - 1];
		if (p[0] == '-' && p[1] == ch && !p[2])
			length = atoi(++p);
		else
			length = atoi(argv[optind] + 1);
		break;
	}
}
.fi