]>
Commit | Line | Data |
---|---|---|
bf5a7247 | 1 | .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) |
fea681da MK |
2 | .\" |
3 | .\" Permission is granted to make and distribute verbatim copies of this | |
4 | .\" manual provided the copyright notice and this permission notice are | |
5 | .\" preserved on all copies. | |
6 | .\" | |
7 | .\" Permission is granted to copy and distribute modified versions of this | |
8 | .\" manual under the conditions for verbatim copying, provided that the | |
9 | .\" entire resulting derived work is distributed under the terms of a | |
10 | .\" permission notice identical to this one. | |
c13182ef | 11 | .\" |
fea681da MK |
12 | .\" Since the Linux kernel and libraries are constantly changing, this |
13 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
14 | .\" responsibility for errors or omissions, or for damages resulting from | |
15 | .\" the use of the information contained herein. The author(s) may not | |
16 | .\" have taken the same level of care in the production of this manual, | |
17 | .\" which is licensed free of charge, as they might when working | |
18 | .\" professionally. | |
c13182ef | 19 | .\" |
fea681da MK |
20 | .\" Formatted or processed versions of this manual, if unaccompanied by |
21 | .\" the source, must acknowledge the copyright and authors of this work. | |
22 | .\" License. | |
23 | .\" Modified Sat Jul 24 19:27:50 1993 by Rik Faith (faith@cs.unc.edu) | |
24 | .\" Modified Mon Aug 30 22:02:34 1995 by Jim Van Zandt <jrv@vanzandt.mv.com> | |
25 | .\" longindex is a pointer, has_arg can take 3 values, using consistent | |
26 | .\" names for optstring and longindex, "\n" in formats fixed. Documenting | |
27 | .\" opterr and getopt_long_only. Clarified explanations (borrowing heavily | |
28 | .\" from the source code). | |
29 | .\" Modified 8 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk) | |
30 | .\" Modified 990715, aeb: changed `EOF' into `-1' since that is what POSIX | |
31 | .\" says; moreover, EOF is not defined in <unistd.h>. | |
32 | .\" Modified 2002-02-16, joey: added information about non-existing | |
33 | .\" option character and colon as first option character | |
c11b1abf | 34 | .\" Modified 2004-07-28, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da MK |
35 | .\" Added text to explain how to order both '[-+]' and ':' at |
36 | .\" the start of optstring | |
92e014f6 | 37 | .\" Modified 2006-12-15, mtk, Added getopt() example program. |
fea681da | 38 | .\" |
ff4e3b35 | 39 | .TH GETOPT 3 2008-04-25 "GNU" "Linux Programmer's Manual" |
fea681da | 40 | .SH NAME |
57db674d MK |
41 | getopt, getopt_long, getopt_long_only, |
42 | optarg, optind, opterr, optopt \- Parse command-line options | |
fea681da MK |
43 | .SH SYNOPSIS |
44 | .nf | |
45 | .B #include <unistd.h> | |
46 | .sp | |
47 | .BI "int getopt(int " argc ", char * const " argv[] , | |
48 | .BI " const char *" optstring ); | |
49 | .sp | |
50 | .BI "extern char *" optarg ; | |
51 | .BI "extern int " optind ", " opterr ", " optopt ; | |
52 | .sp | |
53 | .B #define _GNU_SOURCE | |
54 | .br | |
55 | .B #include <getopt.h> | |
56 | .sp | |
57 | .BI "int getopt_long(int " argc ", char * const " argv[] , | |
58 | .BI " const char *" optstring , | |
59 | .BI " const struct option *" longopts ", int *" longindex ); | |
60 | .sp | |
61 | .BI "int getopt_long_only(int " argc ", char * const " argv[] , | |
62 | .BI " const char *" optstring , | |
63 | .BI " const struct option *" longopts ", int *" longindex ); | |
64 | .fi | |
65 | .SH DESCRIPTION | |
66 | The | |
f10e4102 | 67 | .BR getopt () |
c13182ef MK |
68 | function parses the command-line arguments. |
69 | Its arguments | |
fea681da MK |
70 | .I argc |
71 | and | |
72 | .I argv | |
73 | are the argument count and array as passed to the | |
63aa9df0 | 74 | .IR main () |
fea681da | 75 | function on program invocation. |
f81fb444 | 76 | An element of \fIargv\fP that starts with \(aq\-\(aq |
fea681da | 77 | (and is not exactly "\-" or "\-\-") |
c13182ef MK |
78 | is an option element. |
79 | The characters of this element | |
f81fb444 | 80 | (aside from the initial \(aq\-\(aq) are option characters. |
60a90ecd MK |
81 | If |
82 | .BR getopt () | |
fea681da MK |
83 | is called repeatedly, it returns successively each of the option characters |
84 | from each of the option elements. | |
85 | .PP | |
60a90ecd MK |
86 | If |
87 | .BR getopt () | |
88 | finds another option character, it returns that | |
fea681da | 89 | character, updating the external variable \fIoptind\fP and a static |
60a90ecd MK |
90 | variable \fInextchar\fP so that the next call to |
91 | .BR getopt () | |
92 | can | |
fea681da MK |
93 | resume the scan with the following option character or |
94 | \fIargv\fP-element. | |
95 | .PP | |
60a90ecd MK |
96 | If there are no more option characters, |
97 | .BR getopt () | |
98 | returns \-1. | |
fea681da MK |
99 | Then \fIoptind\fP is the index in \fIargv\fP of the first |
100 | \fIargv\fP-element that is not an option. | |
101 | .PP | |
102 | .I optstring | |
c13182ef MK |
103 | is a string containing the legitimate option characters. |
104 | If such a | |
fea681da | 105 | character is followed by a colon, the option requires an argument, so |
60a90ecd MK |
106 | .BR getopt () |
107 | places a pointer to the following text in the same | |
fea681da MK |
108 | \fIargv\fP-element, or the text of the following \fIargv\fP-element, in |
109 | .IR optarg . | |
110 | Two colons mean an option takes | |
e6bcc128 | 111 | an optional arg; if there is text in the current \fIargv\fP-element |
f262c004 | 112 | (i.e., in the same word as the option name itself, for example, "\-oarg"), |
e6bcc128 | 113 | then it is returned in \fIoptarg\fP, otherwise \fIoptarg\fP is set to zero. |
c13182ef MK |
114 | This is a GNU extension. |
115 | If | |
fea681da MK |
116 | .I optstring |
117 | contains | |
118 | .B W | |
119 | followed by a semicolon, then | |
120 | .B \-W foo | |
121 | is treated as the long option | |
122 | .BR \-\-foo . | |
123 | (The | |
124 | .B \-W | |
125 | option is reserved by POSIX.2 for implementation extensions.) | |
d9bfdb9c | 126 | This behavior is a GNU extension, not available with libraries before |
5260fe08 | 127 | glibc 2. |
fea681da | 128 | .PP |
60a90ecd MK |
129 | By default, |
130 | .BR getopt () | |
131 | permutes the contents of \fIargv\fP as it | |
c13182ef MK |
132 | scans, so that eventually all the non-options are at the end. |
133 | Two other modes are also implemented. | |
134 | If the first character of | |
f81fb444 | 135 | \fIoptstring\fP is \(aq+\(aq or the environment variable |
d9a10d9d MK |
136 | .B POSIXLY_CORRECT |
137 | is set, then option processing stops as soon as a non-option argument is | |
c13182ef | 138 | encountered. |
f81fb444 | 139 | If the first character of \fIoptstring\fP is \(aq\-\(aq, then |
fea681da MK |
140 | each non-option \fIargv\fP-element is handled as if it were the argument of |
141 | an option with character code 1. (This is used by programs that were | |
142 | written to expect options and other \fIargv\fP-elements in any order | |
143 | and that care about the ordering of the two.) | |
144 | The special argument "\-\-" forces an end of option-scanning regardless | |
145 | of the scanning mode. | |
146 | .PP | |
60a90ecd MK |
147 | If |
148 | .BR getopt () | |
149 | does not recognize an option character, it prints an | |
ce2801d0 | 150 | error message to \fIstderr\fP, stores the character in \fIoptopt\fP, and |
f81fb444 | 151 | returns \(aq?\(aq. |
c13182ef | 152 | The calling program may prevent the error message by |
fea681da MK |
153 | setting \fIopterr\fP to 0. |
154 | .PP | |
60a90ecd MK |
155 | If |
156 | .BR getopt () | |
157 | finds an option character in \fIargv\fP that was not | |
fea681da | 158 | included in \fIoptstring\fP, or if it detects a missing option argument, |
0425de01 | 159 | it returns \(aq?\(aq and sets the external variable \fIoptopt\fP to the |
c13182ef MK |
160 | actual option character. |
161 | If the first character | |
f81fb444 | 162 | (following any optional \(aq+\(aq or \(aq\-\(aq described above) |
fea681da | 163 | of \fIoptstring\fP |
f81fb444 | 164 | is a colon (\(aq:\(aq), then |
60a90ecd | 165 | .BR getopt () |
f81fb444 | 166 | returns \(aq:\(aq instead of \(aq?\(aq to |
c13182ef MK |
167 | indicate a missing option argument. |
168 | If an error was detected, and | |
fea681da | 169 | the first character of \fIoptstring\fP is not a colon, and |
eba72288 | 170 | the external variable \fIopterr\fP is non-zero (which is the default), |
60a90ecd MK |
171 | .BR getopt () |
172 | prints an error message. | |
2aeec1f9 | 173 | .SS getopt_long() and getopt_long_only() |
fea681da | 174 | The |
f10e4102 | 175 | .BR getopt_long () |
fea681da | 176 | function works like |
f10e4102 | 177 | .BR getopt () |
c1ed35a7 | 178 | except that it also accepts long options, started with two dashes. |
d0ac4fb3 MK |
179 | (If the program accepts only long options, then |
180 | .I optstring | |
181 | should be specified as an empty string (""), not NULL.) | |
fea681da | 182 | Long option names may be abbreviated if the abbreviation is |
c13182ef MK |
183 | unique or is an exact match for some defined option. |
184 | A long option | |
fea681da MK |
185 | may take a parameter, of the form |
186 | .B \-\-arg=param | |
187 | or | |
188 | .BR "\-\-arg param" . | |
189 | .PP | |
190 | .I longopts | |
191 | is a pointer to the first element of an array of | |
8478ee02 | 192 | .I struct option |
fea681da | 193 | declared in |
8478ee02 | 194 | .I <getopt.h> |
fea681da | 195 | as |
088a639b | 196 | .in +4n |
fea681da MK |
197 | .nf |
198 | .sp | |
fea681da | 199 | struct option { |
cf448976 MK |
200 | const char *name; |
201 | int has_arg; | |
202 | int *flag; | |
203 | int val; | |
fea681da MK |
204 | }; |
205 | .fi | |
cf448976 | 206 | .in |
fea681da MK |
207 | .PP |
208 | The meanings of the different fields are: | |
209 | .TP | |
210 | .I name | |
211 | is the name of the long option. | |
212 | .TP | |
213 | .I has_arg | |
214 | is: | |
f10e4102 MK |
215 | \fBno_argument\fP (or 0) if the option does not take an argument; |
216 | \fBrequired_argument\fP (or 1) if the option requires an argument; or | |
fea681da MK |
217 | \fBoptional_argument\fP (or 2) if the option takes an optional argument. |
218 | .TP | |
219 | .I flag | |
c13182ef MK |
220 | specifies how results are returned for a long option. |
221 | If \fIflag\fP | |
60a90ecd MK |
222 | is NULL, then |
223 | .BR getopt_long () | |
224 | returns \fIval\fP. (For | |
fea681da | 225 | example, the calling program may set \fIval\fP to the equivalent short |
c13182ef | 226 | option character.) |
60a90ecd MK |
227 | Otherwise, |
228 | .BR getopt_long () | |
229 | returns 0, and | |
fea681da MK |
230 | \fIflag\fP points to a variable which is set to \fIval\fP if the |
231 | option is found, but left unchanged if the option is not found. | |
232 | .TP | |
c13182ef | 233 | \fIval\fP |
fea681da MK |
234 | is the value to return, or to load into the variable pointed |
235 | to by \fIflag\fP. | |
236 | .PP | |
7b01461a | 237 | The last element of the array has to be filled with zeros. |
fea681da | 238 | .PP |
35e21ba7 | 239 | If \fIlongindex\fP is not NULL, it |
fea681da MK |
240 | points to a variable which is set to the index of the long option relative to |
241 | .IR longopts . | |
242 | .PP | |
60a90ecd MK |
243 | .BR getopt_long_only () |
244 | is like | |
245 | .BR getopt_long (), | |
f81fb444 | 246 | but \(aq\-\(aq as well |
f8a07a21 | 247 | as "\-\-" can indicate a long option. |
f81fb444 | 248 | If an option that starts with \(aq\-\(aq |
f8a07a21 | 249 | (not "\-\-") doesn't match a long option, but does match a short option, |
c13182ef | 250 | it is parsed as a short option instead. |
fea681da | 251 | .SH "RETURN VALUE" |
f10e4102 MK |
252 | If an option was successfully found, then |
253 | .BR getopt () | |
254 | returns the option character. | |
255 | If all command-line options have been parsed, then | |
256 | .BR getopt () | |
257 | returns \-1. | |
258 | If | |
259 | .BR getopt () | |
260 | encounters an option character that was not in | |
261 | .IR optstring , | |
f81fb444 | 262 | then \(aq?\(aq is returned. |
f10e4102 MK |
263 | If |
264 | .BR getopt () | |
265 | encounters an option with a missing argument, | |
266 | then the return value depends on the first character in | |
267 | .IR optstring : | |
f81fb444 | 268 | if it is \(aq:\(aq, then \(aq:\(aq is returned; otherwise \(aq?\(aq is returned. |
fea681da | 269 | .PP |
60a90ecd MK |
270 | .BR getopt_long () |
271 | and | |
272 | .BR getopt_long_only () | |
273 | also return the option | |
c13182ef MK |
274 | character when a short option is recognized. |
275 | For a long option, they | |
276 | return \fIval\fP if \fIflag\fP is NULL, and 0 otherwise. | |
60a90ecd MK |
277 | Error and \-1 returns are the same as for |
278 | .BR getopt (), | |
f81fb444 | 279 | plus \(aq?\(aq for an |
fea681da | 280 | ambiguous match or an extraneous parameter. |
d219a1a3 | 281 | .SH ENVIRONMENT |
fea681da | 282 | .TP |
fea681da | 283 | .B POSIXLY_CORRECT |
c13182ef | 284 | If this is set, then option processing stops as soon as a non-option |
fea681da MK |
285 | argument is encountered. |
286 | .TP | |
fea681da MK |
287 | .B _<PID>_GNU_nonoption_argv_flags_ |
288 | This variable was used by | |
f19a0f03 | 289 | .BR bash (1) |
5260fe08 | 290 | 2.0 to communicate to glibc which arguments are the results of |
c13182ef | 291 | wildcard expansion and so should not be considered as options. |
d9bfdb9c | 292 | This behavior was removed in |
f19a0f03 | 293 | .BR bash (1) |
5260fe08 | 294 | version 2.01, but the support remains in glibc. |
2b2581ee MK |
295 | .SH "CONFORMING TO" |
296 | .TP | |
297 | .BR getopt (): | |
298 | POSIX.2 and POSIX.1-2001, | |
d9a10d9d MK |
299 | provided the environment variable |
300 | .B POSIXLY_CORRECT | |
301 | is set. | |
2b2581ee MK |
302 | Otherwise, the elements of \fIargv\fP aren't really const, because we |
303 | permute them. | |
304 | We pretend they're const in the prototype to be | |
305 | compatible with other systems. | |
ca92ce95 | 306 | |
2b2581ee MK |
307 | On some older implementations, |
308 | .BR getopt () | |
309 | was declared in | |
310 | .IR <stdio.h> . | |
311 | SUSv1 permitted the declaration to appear in either | |
312 | .I <unistd.h> | |
313 | or | |
314 | .IR <stdio.h> . | |
315 | POSIX.1-2001 marked the use of | |
316 | .I <stdio.h> | |
317 | for this purpose as LEGACY. | |
318 | POSIX.1-2001 does not allow the declaration to appear in | |
319 | .IR <stdio.h> . | |
320 | .SH BUGS | |
321 | The POSIX.2 specification of | |
322 | .BR getopt () | |
323 | has a technical error described in POSIX.2 Interpretation 150. | |
324 | The GNU | |
325 | implementation (and probably all other implementations) implements the | |
d9bfdb9c | 326 | correct behavior rather than that specified. |
fea681da | 327 | .SH EXAMPLE |
92e014f6 MK |
328 | The following trivial example program uses |
329 | .BR getopt () | |
c13182ef | 330 | to handle two program options: |
f262c004 | 331 | .IR \-n , |
92e014f6 | 332 | with no associated value; and |
f262c004 | 333 | .IR "\-t val" , |
92e014f6 MK |
334 | which expects an associated value. |
335 | .nf | |
336 | .sp | |
337 | #include <unistd.h> | |
338 | #include <stdlib.h> | |
339 | #include <stdio.h> | |
340 | ||
341 | int | |
342 | main(int argc, char *argv[]) | |
343 | { | |
344 | int flags, opt; | |
345 | int nsecs, tfnd; | |
346 | ||
347 | nsecs = 0; | |
348 | tfnd = 0; | |
349 | flags = 0; | |
29059a65 | 350 | while ((opt = getopt(argc, argv, "nt:")) != \-1) { |
92e014f6 | 351 | switch (opt) { |
f81fb444 | 352 | case \(aqn\(aq: |
92e014f6 MK |
353 | flags = 1; |
354 | break; | |
f81fb444 | 355 | case \(aqt\(aq: |
92e014f6 MK |
356 | nsecs = atoi(optarg); |
357 | tfnd = 1; | |
358 | break; | |
f81fb444 | 359 | default: /* \(aq?\(aq */ |
29059a65 | 360 | fprintf(stderr, "Usage: %s [\-t nsecs] [\-n] name\\n", |
cec29a73 | 361 | argv[0]); |
92e014f6 MK |
362 | exit(EXIT_FAILURE); |
363 | } | |
364 | } | |
365 | ||
366 | printf("flags=%d; tfnd=%d; optind=%d\\n", flags, tfnd, optind); | |
367 | ||
368 | if (optind >= argc) { | |
369 | fprintf(stderr, "Expected argument after options\\n"); | |
370 | exit(EXIT_FAILURE); | |
371 | } | |
372 | ||
373 | printf("name argument = %s\\n", argv[optind]); | |
374 | ||
375 | /* Other code omitted */ | |
376 | ||
377 | exit(EXIT_SUCCESS); | |
378 | } | |
379 | .fi | |
380 | .PP | |
fea681da | 381 | The following example program illustrates the use of |
f10e4102 | 382 | .BR getopt_long () |
fea681da MK |
383 | with most of its features. |
384 | .nf | |
385 | .sp | |
386 | #include <stdio.h> /* for printf */ | |
387 | #include <stdlib.h> /* for exit */ | |
388 | #include <getopt.h> | |
389 | ||
390 | int | |
c13182ef | 391 | main(int argc, char **argv) |
41798314 | 392 | { |
fea681da MK |
393 | int c; |
394 | int digit_optind = 0; | |
395 | ||
396 | while (1) { | |
397 | int this_option_optind = optind ? optind : 1; | |
398 | int option_index = 0; | |
399 | static struct option long_options[] = { | |
400 | {"add", 1, 0, 0}, | |
401 | {"append", 0, 0, 0}, | |
402 | {"delete", 1, 0, 0}, | |
403 | {"verbose", 0, 0, 0}, | |
f81fb444 | 404 | {"create", 1, 0, \(aqc\(aq}, |
fea681da MK |
405 | {"file", 1, 0, 0}, |
406 | {0, 0, 0, 0} | |
407 | }; | |
408 | ||
cf0a9ace | 409 | c = getopt_long(argc, argv, "abc:d:012", |
fea681da MK |
410 | long_options, &option_index); |
411 | if (c == \-1) | |
412 | break; | |
413 | ||
414 | switch (c) { | |
415 | case 0: | |
cf0a9ace | 416 | printf("option %s", long_options[option_index].name); |
fea681da | 417 | if (optarg) |
cf0a9ace MK |
418 | printf(" with arg %s", optarg); |
419 | printf("\\n"); | |
fea681da MK |
420 | break; |
421 | ||
f81fb444 MK |
422 | case \(aq0\(aq: |
423 | case \(aq1\(aq: | |
424 | case \(aq2\(aq: | |
fea681da | 425 | if (digit_optind != 0 && digit_optind != this_option_optind) |
29059a65 | 426 | printf("digits occur in two different argv\-elements.\\n"); |
fea681da | 427 | digit_optind = this_option_optind; |
cf0a9ace | 428 | printf("option %c\\n", c); |
fea681da MK |
429 | break; |
430 | ||
f81fb444 | 431 | case \(aqa\(aq: |
cf0a9ace | 432 | printf("option a\\n"); |
fea681da MK |
433 | break; |
434 | ||
f81fb444 | 435 | case \(aqb\(aq: |
cf0a9ace | 436 | printf("option b\\n"); |
fea681da MK |
437 | break; |
438 | ||
f81fb444 MK |
439 | case \(aqc\(aq: |
440 | printf("option c with value \(aq%s\(aq\\n", optarg); | |
fea681da MK |
441 | break; |
442 | ||
f81fb444 MK |
443 | case \(aqd\(aq: |
444 | printf("option d with value \(aq%s\(aq\\n", optarg); | |
fea681da MK |
445 | break; |
446 | ||
f81fb444 | 447 | case \(aq?\(aq: |
fea681da MK |
448 | break; |
449 | ||
450 | default: | |
cf0a9ace | 451 | printf("?? getopt returned character code 0%o ??\\n", c); |
fea681da MK |
452 | } |
453 | } | |
454 | ||
455 | if (optind < argc) { | |
29059a65 | 456 | printf("non\-option ARGV\-elements: "); |
fea681da | 457 | while (optind < argc) |
cf0a9ace MK |
458 | printf("%s ", argv[optind++]); |
459 | printf("\\n"); | |
fea681da MK |
460 | } |
461 | ||
4c44ffe5 | 462 | exit(EXIT_SUCCESS); |
fea681da MK |
463 | } |
464 | .fi | |
0a90178c | 465 | .SH "SEE ALSO" |
33c98653 | 466 | .BR getsubopt (3), |
0a90178c | 467 | .BR feature_test_macros (7) |