irix-657m-src/eoe/man/man3c/getopt.3c

'\"macro stdmacro
.if n .pH g3c.getopt @(#)getopt	41.8 of 5/26/91
.\" Copyright 1991 UNIX System Laboratories, Inc.
.\" Copyright 1989, 1990 AT&T
.nr X
.if \nX=0 .ds x} getopt 3C "C Development Set" "\&"
.if \nX=1 .ds x} getopt 3C "C Development Set"
.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 <unistd.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
.PP
\f4extern void getoptreset (void);\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
\f4getsubopt\fP(3C)
to parse positional parameters and check for options that are legal for that
command.
.PP
.I optstring\^
must contain the option letters that 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
\f4\-1\f1.
The special option
``\f4\-\^\-\f1'' (two hyphens)
may be used to delimit the end of the options;
when it is encountered,
\f4\-1\f1
is returned and
``\f4\-\^\-\f1''
is skipped. This is useful in delimiting
non-option arguments that begin with ``\f4\-\f1'' (hyphen).
.PP
\f4getoptreset\fP can be used to reset all the internal state of \f4getopt\fP
so that it may be used again on a different set of arguments.
.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 <unistd.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:")) != -1)
		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 FILES
.TP
\f4/usr/lib/locale/\f2locale\f4/LC_MESSAGES/uxlibc\f1
language-specific message file [See \f4LANG\fP on \f4environ\f1(5).]
.SH SEE ALSO
\f4getopts\fP(1), \f4intro\fP(1),
\f4getsubopt\fP(3C), \f4pfmt\fP(3C), \f4setlabel\fP(3C)
.SH "RETURN VALUE"
The \f4getopt\fP function returns the next option character specified on the
command line.
.P
A colon character
``\f4:\f1''
is returned if \f4getopt\fP detects a missing argument and the first character
of
.I optstring
was a colon character
``\f4:\f1''.
.P
A question mark character
``\f4?\f1''
is returned if \f4getopt\fP encounters an option character not in
.I optstring
or detects a missing argument and the first character of
.I optstring
was not a colon character
``\f4:\f1''.
.P
Otherwise \f4getopt\fP returns \f4\-1\f1 when all command line options 
are parsed.
.SH DIAGNOSTICS
If \f4getopt\fP detects a missing option-argument, it
returns the 
``\f4:\f1''
colon character if the first character
of
.I optstring
was a colon, or a 
``\f4?\f1''
(question mark) character
otherwise.  If the application has not set the variable
\f4opterr\f1 to zero and the first character of
.I optstring
is not a colon, \f4getopt\fP also prints a diagnostic message
in the standard error format.
The value of the character that caused the error is in \f4optopt\f1.
.P
The label defined by a call to \f4setlabel\f1(3C) will be used if available;
otherwise the name of the utility (\f4argv[0]\f1) will be used.  Remember to
set the environment variable (\f4NOMSGSEVERITY=1\f1) for X/Open conformance.
Also, the environment variable (\f4NOMSGLABEL\f1) must be not defined in order 
for \f4setlabel\f1(3C) to print labels.
.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 \-o xxx file\f1.
.\"	@(#)getopt.3c	6.2 of 10/20/83
.Ee