'\"macro stdmacro
.if n .pH g3c.getopt @(#)getopt	40.16 of 10/26/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} getopt 3C "C Programming Language Utilities" "\&"
.if \nX=1 .ds x} getopt 3C "C Programming Language Utilities"
.if \nX=2 .ds x} getopt 3C "" "\&"
.if \nX=3 .ds x} getopt "" "" "\&"
.TH \*(x}
.SH NAME
\f4getopt\f1 \- get option letter from argument vector
.SH SYNOPSIS
\f4#include <stdlib.h>\f1
.PP
\f4int getopt (int argc, char \(** const \(**argv, const char \(**optstring);\f1
.PP
\f4extern char \(**optarg;\f1
.PP
\f4extern int optind, opterr, optopt;\f1
.SH DESCRIPTION
\f4getopt\fP
returns the next option letter in
.I argv\^
that matches
a letter in
.IR optstring .
It supports all the rules of the command syntax standard
[see
\f4intro\fP(1)].
Since all new commands are intended to adhere to the command syntax standard,
they should use
\f4getopts\fP(1),
\f4getopt\fP(3C), or
\f4getsubopts\fP(3C)
to parse positional parameters and check for options that are legal for that
command.
.PP
.I optstring\^
must contain the option letters the command using
\f4getopt\fP
will recognize;
if a letter is followed by a colon, the option
is expected to have an argument, or group of arguments,
which may
be separated from it by white space.
.I optarg\^
is set to point to the start of the option argument
on return from
\f4getopt\fP.
.PP
\f4getopt\fP
places in
.I optind
the
.I argv\^
index of the next argument to be processed.
.I optind
is external and is initialized to 1 before the first call to \f4getopt\fP.
When all options have been processed
(i.e., up to the first non-option argument),
\f4getopt\fP
returns
\f4EOF\f1.
The special option
``\f4\-\^\-\f1'' (two hyphens)
may be used to delimit the end of the options;
when it is encountered,
\f4EOF\f1
is returned and
``\f4\-\^\-\f1''
is skipped. This is useful in delimiting
non-option arguments that begin with ``\f4\-\f1'' (hyphen).
.SH EXAMPLE
The following code fragment shows how one might process the arguments
for a command that can take the mutually exclusive options
\f4a\f1
and
\f4b\f1,
and the option
\f4o\f1,
which requires an argument:
.sp
.nf
.ss 18
.ftCW
#include <stdlib.h>
#include <stdio.h>

main (int argc, char \(**\(**argv)
{
	int c;
	extern char \(**optarg;
	extern int optind;
	int aflg = 0;
	int bflg = 0;
	int errflg = 0;
	char \(**ofile = NULL;

	while ((c = getopt(argc, argv, "abo:")) != EOF)
		switch (c) {
		case 'a':
			if (bflg)
				errflg++;
			else
				aflg++;
			break;
		case 'b':
			if (aflg)
				errflg++;
			else
				bflg++;
			break;
		case 'o':
			ofile = optarg;
			(void)printf("ofile = %s\en", ofile);
			break;
		case '?':
			errflg++;
		}
	if (errflg) {
		(void)fprintf(stderr,
			"usage: cmd [\-a|\-b] [\-o<file>] files...\en");
		exit (2);
	}
	for ( ; optind < argc; optind++)
		(void)printf("%s\en", argv[optind]);
	return 0;
}
.ss 12
.fi
.ftP
.SH SEE ALSO
\f4getsubopt\fP(3C).
.br
\f4getopts\fP(1), \f4intro\fP(1) in the \f2User's Reference Manual\f1.
.SH DIAGNOSTICS
\f4getopt\fP
prints an error message on
the standard error
and returns a
``\f4?\f1''
(question mark)
when it encounters an option letter not included in
.I optstring
or no argument after an option that expects one.
This error message may be disabled by setting 
\f4opterr\f1 to 0.
The value of the character that caused the error is in \f4optopt\f1.
.SH NOTES
The library routine \f4getopt\f1 does not fully check
for mandatory arguments.
That is, given an option
string \f4a:b\f1 and the input \f4\-a \-b\f1, \f4getopt\f1
assumes that \f4\-b\f1 is the mandatory argument to the
option \f4\-a\f1 and not that \f4\-a\f1 is missing a mandatory
argument.
.P
It is a violation of the command syntax
standard [see \f4intro\f1(1)] for options
with arguments to be grouped with
other options, as in
\f4cmd \-aboxxx file\f1,
where \f4a\f1 and \f4b\f1 are options, 
\f4o\f1 is an option that
requires an argument,
and \f4xxx\f1 is the argument to \f4o\f1.
Although this syntax is permitted in the current implementation,
it should not be used because it may not be supported in future releases. 
The correct syntax is
\f4cmd \-ab \-oxxx file\f1.
.\"	@(#)getopt.3c	6.2 of 10/20/83
.Ee
