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