Originální popis anglicky:
getopt, optarg, opterr, optind, optopt - command option parsing
Návod, kniha: POSIX Programmer's Manual
#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 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:
- 1.
- 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.
- 2.
- Otherwise, optarg shall point to the string
following the option character in that element of argv, and
optind shall be incremented by 1.
If, when
getopt() is called:
argv[optind] is a null pointer*
argv[optind] is not the character -
argv[optind] points to the string "-"
getopt() shall return -1 without changing
optind. If:
argv[optind] points to the string "--"
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.
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.
No errors are defined.
The following sections are informative.
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
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;
}
}
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;
}
}
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.
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.
None.
exec() , the Base Definitions volume of
IEEE Std 1003.1-2001,
<unistd.h>, the Shell and
Utilities volume of IEEE Std 1003.1-2001
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 Specifications Issue
6, Copyright (C) 2001-2003 by the Institute of 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
.
