The
getopt
() function is a command-line parser that shall follow
Utility Syntax Guidelines 3, 4, 5, 6, 7, 9, and 10 in
the Base Definitions volume of IEEE Std 1003.1-2001, Section 12.2,
Utility Syntax Guidelines.
The parameters
argc
and
argv
are the argument count and
argument array as passed to
main
() (see
exec
() ). The
argument
optstring
is a string of recognized
option characters; if a character is followed by a colon, the option
takes an argument. All option characters allowed by Utility
Syntax Guideline 3 are allowed in
optstring
. The implementation
may accept other characters as an extension.
The variable
optind
is the index of the next element of the
argv
[] vector to be processed. It shall be initialized
to 1 by the system, and
getopt
() shall update it when it finishes
with each element of
argv
[]. When an element of
argv
[] contains multiple option characters, it is unspecified
how
getopt
() determines which options have already been
processed.
The
getopt
() function shall return the next option character
(if one is found) from
argv
that matches a character
in
optstring
, if there is one that matches. If the option takes
an argument,
getopt
() shall set the variable
optarg
to point to the option-argument as follows:
If the option was the last character in the string pointed to by an
element of
argv
, then
optarg
shall contain the
next element of
argv
, and
optind
shall be incremented
by 2. If the resulting value of
optind
is greater than
argc
, this indicates a missing option-argument, and
getopt
()
shall return an error indication.
Otherwise,
optarg
shall point to the string following the option
character in that element of
argv
, and
optind
shall be incremented by 1.
getopt
() shall return -1 after incrementing
optind
.
If
getopt
() encounters an option character that is not contained
in
optstring
, it shall return the question-mark (
'?'
) character. If it detects a missing option-argument, it
shall return the colon character (
':'
) if the
first character of
optstring
was a colon, or a question-mark
character (
'?'
) otherwise. In either case,
getopt
() shall set the variable
optopt
to the option character
that caused the error. If the application has not set
the variable
opterr
to 0 and the first character of
optstring
is not a colon,
getopt
() shall also print a
diagnostic message to
stderr
in the format specified for the
getopts
utility.
The
getopt
() function need not be reentrant. A function that
is not required to be reentrant is not required to be
thread-safe.
RETURN VALUE
The
getopt
() function shall return the next option character
specified on the command line.
A colon (
':'
) shall be returned if
getopt
() detects
a missing argument and the first character of
optstring
was a colon (
':'
).
A question mark (
'?'
) shall be returned if
getopt
()
encounters an option character not in
optstring
or
detects a missing argument and the first character of
optstring
was not a colon (
':'
).
Otherwise,
getopt
() shall return -1 when all command line options
are parsed.
ERRORS
No errors are defined.
The following sections are informative.
EXAMPLES
The following code fragment shows how you might process the arguments
for a utility that can take the mutually-exclusive options
a
and
b
and the options
f
and
o
, both of which
require arguments:
case ':': /* -f or -o without operand */
fprintf(stderr,
"Option -%c requires an operand\n", optopt);
errflg++;
break;
case '?':
fprintf(stderr,
"Unrecognized option: -%c\n", optopt);
errflg++;
if (errflg) {
fprintf(stderr, "usage: . . . ");
exit
(2);
for ( ; optind < argc; optind++) {
if (access(argv[optind], R_OK)) {
. . .
The following example parses a set of command line options and prints
messages to standard output for each option and argument
that it encounters.
dbtype = 0;
while ((c = getopt(argc, argv, Options)) != -1) {
if ((st = strchr(Options, c)) != NULL) {
dbtype = st - Options;
break;
The
getopt
() function is only required to support option characters
included in Utility Syntax Guideline 3. Many
historical implementations of
getopt
() support other characters
as options. This is an allowed extension, but applications
that use extensions are not maximally portable. Note that support
for multi-byte option characters is only possible when such
characters can be represented as type
int
.
RATIONALE
The
optopt
variable represents historical practice and allows
the application to obtain the identity of the invalid
option.
The description has been written to make it clear that
getopt
(),
like the
getopts
utility, deals with option-arguments whether
separated from the option by
<blank>s or not. Note that the requirements on
getopt
() and
getopts
are
more stringent than the Utility Syntax Guidelines.
The
getopt
() function shall return -1, rather than EOF, so that
<stdio.h>
is not required.
The special significance of a colon as the first character of
optstring
makes
getopt
() consistent with the
getopts
utility. It
allows an application to make a distinction between a missing
argument and an incorrect option letter without having to examine
the option letter. It is true that a missing argument can only be
detected in one case, but that is a case that has to be considered.
FUTURE DIRECTIONS
None.
COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html
.
