1 .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
3 .\" %%%LICENSE_START(VERBATIM)
4 .\" Permission is granted to make and distribute verbatim copies of this
5 .\" manual provided the copyright notice and this permission notice are
6 .\" preserved on all copies.
8 .\" Permission is granted to copy and distribute modified versions of this
9 .\" manual under the conditions for verbatim copying, provided that the
10 .\" entire resulting derived work is distributed under the terms of a
11 .\" permission notice identical to this one.
13 .\" Since the Linux kernel and libraries are constantly changing, this
14 .\" manual page may be incorrect or out-of-date. The author(s) assume no
15 .\" responsibility for errors or omissions, or for damages resulting from
16 .\" the use of the information contained herein. The author(s) may not
17 .\" have taken the same level of care in the production of this manual,
18 .\" which is licensed free of charge, as they might when working
21 .\" Formatted or processed versions of this manual, if unaccompanied by
22 .\" the source, must acknowledge the copyright and authors of this work.
25 .\" Modified Sat Jul 24 19:27:50 1993 by Rik Faith (faith@cs.unc.edu)
26 .\" Modified Mon Aug 30 22:02:34 1995 by Jim Van Zandt <jrv@vanzandt.mv.com>
27 .\" longindex is a pointer, has_arg can take 3 values, using consistent
28 .\" names for optstring and longindex, "\n" in formats fixed. Documenting
29 .\" opterr and getopt_long_only. Clarified explanations (borrowing heavily
30 .\" from the source code).
31 .\" Modified 8 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk)
32 .\" Modified 990715, aeb: changed `EOF' into `-1' since that is what POSIX
33 .\" says; moreover, EOF is not defined in <unistd.h>.
34 .\" Modified 2002-02-16, joey: added information about nonexistent
35 .\" option character and colon as first option character
36 .\" Modified 2004-07-28, Michael Kerrisk <mtk.manpages@gmail.com>
37 .\" Added text to explain how to order both '[-+]' and ':' at
38 .\" the start of optstring
39 .\" Modified 2006-12-15, mtk, Added getopt() example program.
41 .TH GETOPT 3 2017-09-15 "GNU" "Linux Programmer's Manual"
43 getopt, getopt_long, getopt_long_only,
44 optarg, optind, opterr, optopt \- Parse command-line options
47 .B #include <unistd.h>
49 .BI "int getopt(int " argc ", char * const " argv[] ,
50 .BI " const char *" optstring );
52 .BI "extern char *" optarg ;
53 .BI "extern int " optind ", " opterr ", " optopt ;
55 .B #include <getopt.h>
57 .BI "int getopt_long(int " argc ", char * const " argv[] ,
58 .BI " const char *" optstring ,
59 .BI " const struct option *" longopts ", int *" longindex );
61 .BI "int getopt_long_only(int " argc ", char * const " argv[] ,
62 .BI " const char *" optstring ,
63 .BI " const struct option *" longopts ", int *" longindex );
67 Feature Test Macro Requirements for glibc (see
68 .BR feature_test_macros (7)):
73 _POSIX_C_SOURCE\ >=\ 2 || _XOPEN_SOURCE
76 .BR getopt_long_only ():
82 function parses the command-line arguments.
87 are the argument count and array as passed to the
89 function on program invocation.
90 An element of \fIargv\fP that starts with \(aq\-\(aq
91 (and is not exactly "\-" or "\-\-")
93 The characters of this element
94 (aside from the initial \(aq\-\(aq) are option characters.
97 is called repeatedly, it returns successively each of the option characters
98 from each of the option elements.
102 is the index of the next element to be processed in
104 The system initializes this value to 1.
105 The caller can reset it to 1 to restart scanning of the same
107 or when scanning a new argument vector.
111 finds another option character, it returns that
112 character, updating the external variable \fIoptind\fP and a static
113 variable \fInextchar\fP so that the next call to
116 resume the scan with the following option character or
119 If there are no more option characters,
122 Then \fIoptind\fP is the index in \fIargv\fP of the first
123 \fIargv\fP-element that is not an option.
126 is a string containing the legitimate option characters.
128 character is followed by a colon, the option requires an argument, so
130 places a pointer to the following text in the same
131 \fIargv\fP-element, or the text of the following \fIargv\fP-element, in
133 Two colons mean an option takes
134 an optional arg; if there is text in the current \fIargv\fP-element
135 (i.e., in the same word as the option name itself, for example, "\-oarg"),
136 then it is returned in \fIoptarg\fP, otherwise \fIoptarg\fP is set to zero.
137 This is a GNU extension.
142 followed by a semicolon, then
144 is treated as the long option
148 option is reserved by POSIX.2 for implementation extensions.)
149 This behavior is a GNU extension, not available with libraries before
154 permutes the contents of \fIargv\fP as it
155 scans, so that eventually all the nonoptions are at the end.
156 Two other modes are also implemented.
157 If the first character of
158 \fIoptstring\fP is \(aq+\(aq or the environment variable
160 is set, then option processing stops as soon as a nonoption argument is
162 If the first character of \fIoptstring\fP is \(aq\-\(aq, then
163 each nonoption \fIargv\fP-element is handled as if it were the argument of
164 an option with character code 1. (This is used by programs that were
165 written to expect options and other \fIargv\fP-elements in any order
166 and that care about the ordering of the two.)
167 The special argument "\-\-" forces an end of option-scanning regardless
168 of the scanning mode.
170 While processing the option list,
172 can detect two kinds of errors:
173 (1) an option character that was not specified in
175 and (2) a missing option argument
176 (i.e., an option at the end of the command line without an expected argument).
177 Such errors are handled and reported as follows:
181 prints an error message on standard error,
182 places the erroneous option character in
184 and returns \(aq?\(aq as the function result.
186 If the caller has set the global variable
190 does not print an error message.
191 The caller can determine that there was an error by testing whether
192 the function return value is \(aq?\(aq.
195 has a nonzero value.)
197 If the first character
198 (following any optional \(aq+\(aq or \(aq\-\(aq described above)
200 is a colon (\(aq:\(aq), then
202 likewise does not print an error message.
203 In addition, it returns \(aq:\(aq instead of \(aq?\(aq to
204 indicate a missing option argument.
205 This allows the caller to distinguish the two different types of errors.
207 .SS getopt_long() and getopt_long_only()
212 except that it also accepts long options, started with two dashes.
213 (If the program accepts only long options, then
215 should be specified as an empty string (""), not NULL.)
216 Long option names may be abbreviated if the abbreviation is
217 unique or is an exact match for some defined option.
219 may take a parameter, of the form
222 .BR "\-\-arg param" .
225 is a pointer to the first element of an array of
242 The meanings of the different fields are:
245 is the name of the long option.
249 \fBno_argument\fP (or 0) if the option does not take an argument;
250 \fBrequired_argument\fP (or 1) if the option requires an argument; or
251 \fBoptional_argument\fP (or 2) if the option takes an optional argument.
254 specifies how results are returned for a long option.
259 (For example, the calling program may set \fIval\fP to the equivalent short
264 \fIflag\fP points to a variable which is set to \fIval\fP if the
265 option is found, but left unchanged if the option is not found.
268 is the value to return, or to load into the variable pointed
271 The last element of the array has to be filled with zeros.
273 If \fIlongindex\fP is not NULL, it
274 points to a variable which is set to the index of the long option relative to
277 .BR getopt_long_only ()
280 but \(aq\-\(aq as well
281 as "\-\-" can indicate a long option.
282 If an option that starts with \(aq\-\(aq
283 (not "\-\-") doesn't match a long option, but does match a short option,
284 it is parsed as a short option instead.
286 If an option was successfully found, then
288 returns the option character.
289 If all command-line options have been parsed, then
294 encounters an option character that was not in
296 then \(aq?\(aq is returned.
299 encounters an option with a missing argument,
300 then the return value depends on the first character in
302 if it is \(aq:\(aq, then \(aq:\(aq is returned; otherwise \(aq?\(aq is returned.
306 .BR getopt_long_only ()
307 also return the option
308 character when a short option is recognized.
309 For a long option, they
310 return \fIval\fP if \fIflag\fP is NULL, and 0 otherwise.
311 Error and \-1 returns are the same as for
313 plus \(aq?\(aq for an
314 ambiguous match or an extraneous parameter.
318 If this is set, then option processing stops as soon as a nonoption
319 argument is encountered.
321 .B _<PID>_GNU_nonoption_argv_flags_
322 This variable was used by
324 2.0 to communicate to glibc which arguments are the results of
325 wildcard expansion and so should not be considered as options.
326 This behavior was removed in
328 version 2.01, but the support remains in glibc.
330 For an explanation of the terms used in this section, see
336 Interface Attribute Value
340 .BR getopt_long_only ()
341 T} Thread safety MT-Unsafe race:getopt env
346 POSIX.1-2001, POSIX.1-2008, and POSIX.2,
347 provided the environment variable
350 Otherwise, the elements of \fIargv\fP aren't really
352 because we permute them.
355 in the prototype to be compatible with other systems.
357 The use of \(aq+\(aq and \(aq\-\(aq in
361 On some older implementations,
365 SUSv1 permitted the declaration to appear in either
369 POSIX.1-1996 marked the use of
371 for this purpose as LEGACY.
372 POSIX.1-2001 does not require the declaration to appear in
375 .BR getopt_long "() and " getopt_long_only ():
376 These functions are GNU extensions.
378 A program that scans multiple argument vectors,
379 or rescans the same vector more than once,
380 and wants to make use of GNU extensions such as \(aq+\(aq
381 and \(aq\-\(aq at the start of
383 or changes the value of
390 to 0, rather than the traditional value of 1.
391 (Resetting to 0 forces the invocation of an internal initialization
392 routine that rechecks
394 and checks for GNU extensions in
398 The following trivial example program uses
400 to handle two program options:
402 with no associated value; and
404 which expects an associated value.
412 main(int argc, char *argv[])
420 while ((opt = getopt(argc, argv, "nt:")) != \-1) {
426 nsecs = atoi(optarg);
429 default: /* \(aq?\(aq */
430 fprintf(stderr, "Usage: %s [\-t nsecs] [\-n] name\\n",
436 printf("flags=%d; tfnd=%d; nsecs=%d; optind=%d\\n",
437 flags, tfnd, nsecs, optind);
439 if (optind >= argc) {
440 fprintf(stderr, "Expected argument after options\\n");
444 printf("name argument = %s\\n", argv[optind]);
446 /* Other code omitted */
452 The following example program illustrates the use of
454 with most of its features.
457 #include <stdio.h> /* for printf */
458 #include <stdlib.h> /* for exit */
462 main(int argc, char **argv)
465 int digit_optind = 0;
468 int this_option_optind = optind ? optind : 1;
469 int option_index = 0;
470 static struct option long_options[] = {
471 {"add", required_argument, 0, 0 },
472 {"append", no_argument, 0, 0 },
473 {"delete", required_argument, 0, 0 },
474 {"verbose", no_argument, 0, 0 },
475 {"create", required_argument, 0, \(aqc\(aq},
476 {"file", required_argument, 0, 0 },
480 c = getopt_long(argc, argv, "abc:d:012",
481 long_options, &option_index);
487 printf("option %s", long_options[option_index].name);
489 printf(" with arg %s", optarg);
496 if (digit_optind != 0 && digit_optind != this_option_optind)
497 printf("digits occur in two different argv\-elements.\\n");
498 digit_optind = this_option_optind;
499 printf("option %c\\n", c);
503 printf("option a\\n");
507 printf("option b\\n");
511 printf("option c with value \(aq%s\(aq\\n", optarg);
515 printf("option d with value \(aq%s\(aq\\n", optarg);
522 printf("?? getopt returned character code 0%o ??\\n", c);
527 printf("non\-option ARGV\-elements: ");
528 while (optind < argc)
529 printf("%s ", argv[optind++]);