getopt - command option parsing
#include <stdio.h>
int getopt(int argc, char * const argv[], const char *optstring);
extern char *optarg;
extern int optind, opterr, optopt;
#include <unistd.h>
int getopt(int argc, char * const argv[], const char *optstring);
extern char *optarg;
extern int optind, opterr, optopt;
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.
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.
No errors are defined.
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)
See
environ(5) 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.
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
See
attributes(5) for descriptions of the following attributes:
| ATTRIBUTE TYPE |
ATTRIBUTE VALUE |
|
| Interface Stability |
Committed |
|
| MT-Level |
Unsafe |
|
| Standard |
See below. |
For the Basic Utility Command syntax is Standard, see
standards(5).
Intro(1),
getopt(1),
getopts(1),
getopt_long(3C),
getsubopt(3C),
gettext(3C),
setlocale(3C),
attributes(5),
environ(5),
standards(5)