GETOPT(3C) | Standard C Library Functions | GETOPT(3C) |
#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 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:
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.
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.
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)
LC_CTYPE
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
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
Interface Stability | Committed |
MT-Level | Unsafe |
Standard | See below. |
For the Basic Utility Command syntax is Standard, see standards(7).
July 17, 2018 | OmniOS |