getopt(3C)
NAME
getopt - get option letter from argument vector
SYNOPSIS
SVID3, XPG3
#include <stdio.h>
int getopt(int argc, char * const argv[], const char *opt-
string);
extern char *optarg;
extern int optind, opterr, optopt;
POSIX.2, XPG4, SUS, SUSv2
#include <unistd.h>
int getopt(int argc, char * const argv[], const char *opt-
string);
extern char *optarg;
extern int optind, opterr, optopt;
DESCRIPTION
The getopt() function returns the next option letter in argv
that matches a letter in optstring. It supports all the
rules of the command syntax standard (see intro(1)). Since
all new commands are intended to adhere to the command syn-
tax standard, they should use getopts(1), getopt(3C), or
getsubopt(3C) to parse positional parameters and check for
options that are legal for that command.
The optstring argument must contain the option letters the
command using getopt() will recognize; if a letter is fol-
lowed by a colon, the option is expected to have an argu-
ment, or group of arguments, which may be separated from it
by white space. The optarg argument is set to point to the
start of the option argument on return from getopt().
The getopt() function places in optind the argv index of the
next argument to be processed. optind is external and is
initialized to 1 before the first call to getopt(). When all
options have been processed (that is, up to the first non-
option argument), getopt() returns -1. The special option
"--" (two hyphens) may 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).
RETURN VALUES
The getopt() function returns the next option character
specified on the command line.
A colon (':') is returned if getopt() detects a missing
argument and the first character of optstring was a colon
(':').
The getopt() function outputs an error message to standard
error and returns a question mark ('?') when it encounters
an option letter not included in optstring or no argument
after an option that expects one. This error message can be
disabled by setting opterr to 0. The value of the character
that caused the error is in optopt.
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;
}
}
Example 3: Select Options from the Command Line.
The following example selects the type of database routines
the user wants to use based on the Options argument.
#include <unistd.h>
#include <string.h>
...
char *Options = "hdbtl";
...
int dbtype, i;
char c;
char *st;
...
dbtype = 0;
while ((c = getopt(argc, argv, Options)) != -1) {
if ((st = strchr(Options, c)) != NULL) {
dbtype = st - Options;
break;
}
}
ENVIRONMENT VARIABLES
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.
USAGE
The getopt() function does not fully check for mandatory
arguments; that is, 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 argu-
ment.
It is a violation of the 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 per-
mitted 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
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Standard |
|_____________________________|_____________________________|
| MT-Level | Unsafe |
|_____________________________|_____________________________|
SEE ALSO
intro(1), getopt(1), getopts(1), getsubopt(3C), gettext(3C),
setlocale(3C), attributes(5), environ(5), standards(5)
Man(1) output converted with
man2html