Tribblix: manual page: getopt.3c

GETOPT(3C) Standard C Library Functions GETOPT(3C)

NAME

getopt - command option parsing

SYNOPSIS

SVID3, XPG3
#include <stdio.h>

int getopt(int argc, char * const argv[], const char *optstring);

extern char *optarg;

extern int optind, opterr, optopt;

POSIX.2, XPG4, SUS, SUSv2, SUSv3
#include <unistd.h>

int getopt(int argc, char * const argv[], const char *optstring);

extern char *optarg;

extern int optind, opterr, optopt;

DESCRIPTION

The getopt() function is a command line parser that can be used by
applications that follow Basic Utility Syntax Guidelines 3, 4, 5, 6,
7, 9, and 10 which parallel those defined by application portability
standards (see Intro(1)). It can also be used by applications which
additionally follow the Command Line Interface Paradigm (CLIP) syntax
extension guidelines 15, 16, and 17. It partially enforces guideline
18 by requiring that every option has a short-name, but it allows
multiple long-names to be associated with an option. The remaining
guidelines are not addressed by getopt() and are the responsibility
of the application.

The argc and argv arguments are the argument count and argument array
as passed to main (see exec(2)). The optstring argument specifies the
acceptable options. For utilities wanting to conform to the Basic
Utility Syntax Guidelines, optstring is a string of recognized option
characters. All option characters allowed by Utility Syntax Guideline
3 are allowed in optstring. If a character is followed by a colon
(:), the option is expected to have an option-argument, which can be
separated from it by white space. Utilities wanting to conform to
the extended CLIP guidelines can specify long-option equivalents to
short options by following the short-option character (and optional
colon) with a sequence of strings, each enclosed in parentheses, that
specify the long-option aliases.

The getopt() function returns the short-option character in optstring
that corresponds to the next option found in argv.

The getopt() function places in optind the argv index of the next
argument to be processed. The optind variable is external and is
initialized to 1 before the first call to getopt(). The getopt()
function sets the variable optarg to point to the start of the
option-argument as follows:

o If the option is a short option and that character is the
last character in the argument, then optarg contains the
next element of argv, and optind is incremented by 2.

o If the option is a short option and that character is not
the last character in the argument, then optarg points to
the string following the option character in that
argument, and optind is incremented by 1.

o If the option is a long option and the character equals is
not found in the argument, then optarg contains the next
element of argv, and optind is incremented by 2.

o If the option is a long option and the character equals is
found in the argument, then optarg points to the string
following the equals character in that argument and optind
is incremented by 1.

In all cases, if the resulting value of optind is not less than argc,
this indicates a missing option-argument and getopt() returns an
error indication.

When all options have been processed (that is, up to the first
operand), getopt() returns -1. The special option "--"(two hyphens)
can be used to delimit the end of the options; when it is
encountered, -1 is returned and "--" is skipped. This is useful in
delimiting non-option arguments that begin with "-" (hyphen).

If getopt() encounters a short-option character or a long-option
string not described in the opstring argument, it returns the
question-mark (?) character. If it detects a missing option-argument,
it also returns the question-mark (?) character, unless the first
character of the optstring argument was a colon (:), in which case
getopt() returns the colon (:) character. For short options, getopt()
sets the variable optopt to the option character that caused the
error. For long options, optopt is set to the hyphen (-) character
and the failing long option can be identified through argv[optind-1].
If the application has not set the variable opterr to 0 and the first
character of optstring is not a colon (:), getopt() also prints a
diagnostic message to stderr.

RETURN VALUES

The getopt() function returns the short-option character associated
with the option recognized.

A colon (:) is returned if getopt() detects a missing argument and
the first character of optstring was a colon (:).

A question mark (?) is returned if getopt() encounters an option not
specified in optstring or detects a missing argument and the first
character of optstring was not a colon (:).

Otherwise, getopt() returns -1 when all command line options are
parsed.

ERRORS

No errors are defined.

EXAMPLES

Example 1: Parsing Command Line Options

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:

#include <unistd.h>

int
main(int argc, char *argv[ ])
{
int c;
int bflg, aflg, errflg;
char *ifile;
char *ofile;
extern char *optarg;
extern int optind, optopt;
...
while ((c = getopt(argc, argv, ":abf:o:")) != -1) {
switch(c) {
case 'a':
if (bflg)
errflg++;
else
aflg++;
break;
case 'b':
if (aflg)
errflg++;
else {
bflg++;
bproc();
}
break;
case 'f':
ifile = optarg;
break;
case 'o':
ofile = optarg;
break;
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)) {
...
}

This code accepts any of the following as equivalent:

cmd -ao arg path path
cmd -a -o arg path path
cmd -o arg -a path path
cmd -a -o arg -- path path
cmd -a -oarg path path
cmd -aoarg path path

Example 2: Check Options and Arguments.

The following example parses a set of command line options and prints
messages to standard output for each option and argument that it
encounters.

#include <unistd.h>
#include <stdio.h>
...
int c;
char *filename;
extern char *optarg;
extern int optind, optopt, opterr;
...
while ((c = getopt(argc, argv, ":abf:")) != -1) {
switch(c) {
case 'a':
printf("a is set\n");
break;
case 'b':
printf("b is set\n");
break;
case 'f':
filename = optarg;
printf("filename is %s\n", filename);
break;
case ':':
printf("-%c without filename\n", optopt);
break;
case '?':
printf("unknown arg %c\n", optopt);
break;
}
}

This example can be expanded to be CLIP-compliant by substituting the
following string for the optstring argument:

:a(ascii)b(binary)f:(in-file)o:(out-file)V(version)?(help)

and by replacing the '?' case processing with:

case 'V':
fprintf(stdout, "cmd 1.1\n");
exit(0);
case '?':
if (optopt == '?') {
print_help();
exit(0);
}
if (optopt == '-')
fprintf(stderr,
"unrecognized option: %s\n", argv[optind-1]);
else
fprintf(stderr,
"unrecognized option: -%c\n", optopt);
errflg++;
break;

and by replacing the ':' case processing with:

case ':': /* -f or -o without operand */
if (optopt == '-')
fprintf(stderr,
"Option %s requires an operand\n", argv[optind-1]);
else
fprintf(stderr,
"Option -%c requires an operand\n", optopt);
errflg++;
break;

While not encouraged by the CLIP specification, multiple long-option
aliases can also be assigned as shown in the following example:

:a(ascii)b(binary):(in-file)(input)o:(outfile)(output)V(version)?(help)

ENVIRONMENT VARIABLES

See environ(7) for descriptions of the following environment
variables that affect the execution of getopt(): LANG, LC_ALL, and
LC_MESSAGES.

LC_CTYPE
Determine the locale for the interpretation of sequences
of bytes as characters in optstring.

USAGE

The getopt() function does not fully check for mandatory arguments
because there is no unambiguous algorithm to do so. Given an option
string a:b and the input -a -b, getopt() assumes that -b is the
mandatory argument to the -a option and not that -a is missing a
mandatory argument. Indeed, the only time a missing option-argument
can be reliably detected is when the option is the final option on
the command line and is not followed by any command arguments.

It is a violation of the Basic Utility Command syntax standard (see
Intro(1)) for options with arguments to be grouped with other
options, as in cmd -abo filename , where a and b are options, o is an
option that requires an argument, and filename is the argument to o.
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 to use is:

cmd -ab -o filename

ATTRIBUTES