1 GETOPT(3C) Standard C Library Functions GETOPT(3C)
2
3
4
5 NAME
6 getopt - command option parsing
7
8 SYNOPSIS
9 SVID3, XPG3
10 #include <stdio.h>
11
12 int getopt(int argc, char * const argv[], const char *optstring);
13
14
15 extern char *optarg;
16
17
18 extern int optind, opterr, optopt;
19
20
21 POSIX.2, XPG4, SUS, SUSv2, SUSv3
22 #include <unistd.h>
23
24 int getopt(int argc, char * const argv[], const char *optstring);
25
26
27 extern char *optarg;
28
29
30 extern int optind, opterr, optopt;
31
32
33 DESCRIPTION
34 The getopt() function is a command line parser that can be used by
35 applications that follow Basic Utility Syntax Guidelines 3, 4, 5, 6, 7,
36 9, and 10 which parallel those defined by application portability
37 standards (see Intro(1)). It can also be used by applications which
38 additionally follow the Command Line Interface Paradigm (CLIP) syntax
39 extension guidelines 15, 16, and 17. It partially enforces guideline 18
40 by requiring that every option has a short-name, but it allows multiple
41 long-names to be associated with an option. The remaining guidelines
42 are not addressed by getopt() and are the responsibility of the
43 application.
44
45
46 The argc and argv arguments are the argument count and argument array
47 as passed to main (see exec(2)). The optstring argument specifies the
48 acceptable options. For utilities wanting to conform to the Basic
49 Utility Syntax Guidelines, optstring is a string of recognized option
50 characters. All option characters allowed by Utility Syntax Guideline 3
51 are allowed in optstring. If a character is followed by a colon (:),
52 the option is expected to have an option-argument, which can be
53 separated from it by white space. Utilities wanting to conform to the
54 extended CLIP guidelines can specify long-option equivalents to short
55 options by following the short-option character (and optional colon)
56 with a sequence of strings, each enclosed in parentheses, that specify
57 the long-option aliases.
58
59
60 The getopt() function returns the short-option character in optstring
61 that corresponds to the next option found in argv.
62
63
64 The getopt() function places in optind the argv index of the next
65 argument to be processed. The optind variable is external and is
66 initialized to 1 before the first call to getopt(). The getopt()
67 function sets the variable optarg to point to the start of the option-
68 argument as follows:
69
70 o If the option is a short option and that character is the
71 last character in the argument, then optarg contains the
72 next element of argv, and optind is incremented by 2.
73
74 o If the option is a short option and that character is not
75 the last character in the argument, then optarg points to
76 the string following the option character in that argument,
77 and optind is incremented by 1.
78
79 o If the option is a long option and the character equals is
80 not found in the argument, then optarg contains the next
81 element of argv, and optind is incremented by 2.
82
83 o If the option is a long option and the character equals is
84 found in the argument, then optarg points to the string
85 following the equals character in that argument and optind
86 is incremented by 1.
87
88
89 In all cases, if the resulting value of optind is not less than argc,
90 this indicates a missing option-argument and getopt() returns an error
91 indication.
92
93
94 When all options have been processed (that is, up to the first
95 operand), getopt() returns -1. The special option "--"(two hyphens) can
96 be used to delimit the end of the options; when it is encountered, -1
97 is returned and "--" is skipped. This is useful in delimiting non-
98 option arguments that begin with "-" (hyphen).
99
100
101 If getopt() encounters a short-option character or a long-option string
102 not described in the opstring argument, it returns the question-mark
103 (?) character. If it detects a missing option-argument, it also returns
104 the question-mark (?) character, unless the first character of the
105 optstring argument was a colon (:), in which case getopt() returns the
106 colon (:) character. For short options, getopt() sets the variable
107 optopt to the option character that caused the error. For long options,
108 optopt is set to the hyphen (-) character and the failing long option
109 can be identified through argv[optind-1]. If the application has not
110 set the variable opterr to 0 and the first character of optstring is
111 not a colon (:), getopt() also prints a diagnostic message to stderr.
112
113 RETURN VALUES
114 The getopt() function returns the short-option character associated
115 with the option recognized.
116
117
118 A colon (:) is returned if getopt() detects a missing argument and the
119 first character of optstring was a colon (:).
120
121
122 A question mark (?) is returned if getopt() encounters an option not
123 specified in optstring or detects a missing argument and the first
124 character of optstring was not a colon (:).
125
126
127 Otherwise, getopt() returns -1 when all command line options are
128 parsed.
129
130 ERRORS
131 No errors are defined.
132
133 EXAMPLES
134 Example 1 Parsing Command Line Options
135
136
137 The following code fragment shows how you might process the arguments
138 for a utility that can take the mutually-exclusive options a and b and
139 the options f and o, both of which require arguments:
140
141
142 #include <unistd.h>
143
144 int
145 main(int argc, char *argv[ ])
146 {
147 int c;
148 int bflg, aflg, errflg;
149 char *ifile;
150 char *ofile;
151 extern char *optarg;
152 extern int optind, optopt;
153 ...
154 while ((c = getopt(argc, argv, ":abf:o:")) != -1) {
155 switch(c) {
156 case 'a':
157 if (bflg)
158 errflg++;
159 else
160 aflg++;
161 break;
162 case 'b':
163 if (aflg)
164 errflg++;
165 else {
166 bflg++;
167 bproc();
168 }
169 break;
170 case 'f':
171 ifile = optarg;
172 break;
173 case 'o':
174 ofile = optarg;
175 break;
176 case ':': /* -f or -o without operand */
177 fprintf(stderr,
178 "Option -%c requires an operand\n", optopt);
179 errflg++;
180 break;
181 case '?':
182 fprintf(stderr,
183 "Unrecognized option: -%c\n", optopt);
184 errflg++;
185 }
186 }
187 if (errflg) {
188 fprintf(stderr, "usage: ... ");
189 exit(2);
190 }
191 for ( ; optind < argc; optind++) {
192 if (access(argv[optind], R_OK)) {
193 ...
194 }
195
196
197
198 This code accepts any of the following as equivalent:
199
200
201 cmd -ao arg path path
202 cmd -a -o arg path path
203 cmd -o arg -a path path
204 cmd -a -o arg -- path path
205 cmd -a -oarg path path
206 cmd -aoarg path path
207
208
209 Example 2 Check Options and Arguments.
210
211
212 The following example parses a set of command line options and prints
213 messages to standard output for each option and argument that it
214 encounters.
215
216
217 #include <unistd.h>
218 #include <stdio.h>
219 ...
220 int c;
221 char *filename;
222 extern char *optarg;
223 extern int optind, optopt, opterr;
224 ...
225 while ((c = getopt(argc, argv, ":abf:")) != -1) {
226 switch(c) {
227 case 'a':
228 printf("a is set\n");
229 break;
230 case 'b':
231 printf("b is set\n");
232 break;
233 case 'f':
234 filename = optarg;
235 printf("filename is %s\n", filename);
236 break;
237 case ':':
238 printf("-%c without filename\n", optopt);
239 break;
240 case '?':
241 printf("unknown arg %c\n", optopt);
242 break;
243 }
244 }
245
246
247
248 This example can be expanded to be CLIP-compliant by substituting the
249 following string for the optstring argument:
250
251
252 :a(ascii)b(binary)f:(in-file)o:(out-file)V(version)?(help)
253
254
255
256 and by replacing the '?' case processing with:
257
258
259 case 'V':
260 fprintf(stdout, "cmd 1.1\n");
261 exit(0);
262 case '?':
263 if (optopt == '?') {
264 print_help();
265 exit(0);
266 }
267 if (optopt == '-')
268 fprintf(stderr,
269 "unrecognized option: %s\n", argv[optind-1]);
270 else
271 fprintf(stderr,
272 "unrecognized option: -%c\n", optopt);
273 errflg++;
274 break;
275
276
277
278 and by replacing the ':' case processing with:
279
280
281 case ':': /* -f or -o without operand */
282 if (optopt == '-')
283 fprintf(stderr,
284 "Option %s requires an operand\n", argv[optind-1]);
285 else
286 fprintf(stderr,
287 "Option -%c requires an operand\n", optopt);
288 errflg++;
289 break;
290
291
292
293 While not encouraged by the CLIP specification, multiple long-option
294 aliases can also be assigned as shown in the following example:
295
296
297 :a(ascii)b(binary):(in-file)(input)o:(outfile)(output)V(version)?(help)
298
299
300 ENVIRONMENT VARIABLES
301 See environ(5) for descriptions of the following environment variables
302 that affect the execution of getopt(): LANG, LC_ALL, and LC_MESSAGES.
303
304 LC_CTYPE
305 Determine the locale for the interpretation of sequences of
306 bytes as characters in optstring.
307
308
309 USAGE
310 The getopt() function does not fully check for mandatory arguments
311 because there is no unambiguous algorithm to do so. Given an option
312 string a:b and the input -a -b, getopt() assumes that -b is the
313 mandatory argument to the -a option and not that -a is missing a
314 mandatory argument. Indeed, the only time a missing option-argument
315 can be reliably detected is when the option is the final option on the
316 command line and is not followed by any command arguments.
317
318
319 It is a violation of the Basic Utility Command syntax standard (see
320 Intro(1)) for options with arguments to be grouped with other options,
321 as in cmd -abo filename , where a and b are options, o is an option
322 that requires an argument, and filename is the argument to o. Although
323 this syntax is permitted in the current implementation, it should not
324 be used because it may not be supported in future releases. The
325 correct syntax to use is:
326
327 cmd -ab -o filename
328
329
330
331 ATTRIBUTES
332 See attributes(5) for descriptions of the following attributes:
333
334
335
336
337 +--------------------+-----------------+
338 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
339 +--------------------+-----------------+
340 |Interface Stability | Committed |
341 +--------------------+-----------------+
342 |MT-Level | Unsafe |
343 +--------------------+-----------------+
344 |Standard | See below. |
345 +--------------------+-----------------+
346
347
348 For the Basic Utility Command syntax is Standard, see standards(5).
349
350 SEE ALSO
351 Intro(1), getopt(1), getopts(1), getopt_long(3C), getsubopt(3C),
352 gettext(3C), setlocale(3C), attributes(5), environ(5), standards(5)
353
354
355
356 July 17, 2018 GETOPT(3C)