Debian Codegraph @

upstream/debian-unstable/man3/getopt.3

raw
1 '\" t
2 .\" Copyright 1993, Thomas Koenig <[email protected]>
3 .\" Copyright 2006-2008, Michael Kerrisk <[email protected]>
4 .\" Copyright, the authors of the Linux man-pages project
5 .\"
6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
7 .\"
8 .TH getopt 3 2026-02-08 "Linux man-pages 6.18"
9 .SH NAME
10 getopt,
11 optarg, optind, opterr, optopt \- Parse command-line options
12 .SH LIBRARY
13 Standard C library
14 .RI ( libc ,\~ \-lc )
15 .SH SYNOPSIS
16 .nf
17 .B #include <unistd.h>
18 .P
19 .BI "int getopt(int " argc ", char *" argv [],
20 .BI " const char *" optstring );
21 .P
22 .BI "extern char *" optarg ;
23 .BI "extern int " optind ", " opterr ", " optopt ;
24 .fi
25 .P
26 .RS -4
27 Feature Test Macro Requirements for glibc (see
28 .BR feature_test_macros (7)):
29 .RE
30 .P
31 .BR getopt ():
32 .nf
33 _POSIX_C_SOURCE >= 2 || _XOPEN_SOURCE
34 .fi
35 .SH DESCRIPTION
36 The
37 .BR getopt ()
38 function parses the command-line arguments.
39 Its arguments
40 .I argc
41 and
42 .I argv
43 are the argument count and array as passed to the
44 .IR main ()
45 function on program invocation.
46 An element of
47 .I argv
48 that starts with \[aq]\-\[aq]
49 (and is not exactly "\-" or "\-\-")
50 is an option element.
51 The characters of this element
52 (aside from the initial \[aq]\-\[aq]) are option characters.
53 If
54 .BR getopt ()
55 is called repeatedly, it returns successively each of the option characters
56 from each of the option elements.
57 .P
58 The variable
59 .I optind
60 is the index of the next element to be processed in
61 .IR argv .
62 The system initializes this value to 1.
63 The caller can reset it to 1 to restart scanning of the same
64 .IR argv ,
65 or when scanning a new argument vector.
66 .P
67 If
68 .BR getopt ()
69 finds another option character, it returns that
70 character, updating the external variable
71 .I optind
72 and a static variable
73 .I nextchar
74 so that the next call to
75 .BR getopt ()
76 can
77 resume the scan with the following option character or
78 .IR argv -element.
79 .P
80 If there are no more option characters,
81 .BR getopt ()
82 returns \-1.
83 Then
84 .I optind
85 is the index in
86 .I argv
87 of the first
88 .IR argv -element
89 that is not an option.
90 .P
91 .I optstring
92 is a string containing the legitimate option characters.
93 A legitimate option character is any visible one byte
94 .BR ascii (7)
95 character (for which
96 .BR isgraph (3)
97 would return nonzero) that is not \[aq]\-\[aq], \[aq]:\[aq], or \[aq];\[aq].
98 If such a
99 character is followed by a colon, the option requires an argument, so
100 .BR getopt ()
101 places a pointer to the following text in the same
102 .IR argv -element,
103 or the text of the following
104 .IR argv -element,
105 in
106 .IR optarg .
107 Two colons mean an option takes
108 an optional arg;
109 if there is text in the current
110 .IR argv -element
111 (i.e., in the same word as the option name itself, for example, "\-oarg"),
112 then it is returned in
113 .IR optarg ,
114 otherwise
115 .I optarg
116 is set to zero.
117 This is a GNU extension.
118 If
119 .I optstring
120 contains
121 .B W
122 followed by a semicolon, then
123 .B \-W foo
124 is treated as the long option
125 .BR \-\-foo .
126 (The
127 .B \-W
128 option is reserved by POSIX.2 for implementation extensions.)
129 This behavior is a GNU extension, not available with libraries before
130 glibc 2.
131 .P
132 By default,
133 .BR getopt ()
134 permutes the contents of
135 .I argv
136 as it scans,
137 so that eventually all the nonoptions are at the end.
138 Two other scanning modes are also implemented.
139 If the first character of
140 .I optstring
141 is \[aq]+\[aq] or the environment variable
142 .B \%POSIXLY_CORRECT
143 is set, then option processing stops as soon as a nonoption argument is
144 encountered.
145 If \[aq]+\[aq] is not the first character of
146 .IR optstring ,
147 it is treated as a normal option.
148 If
149 .B \%POSIXLY_CORRECT
150 behavior is required in this case
151 .I optstring
152 will contain two \[aq]+\[aq] symbols.
153 If the first character of
154 .I optstring
155 is \[aq]\-\[aq],
156 then each nonoption
157 .IR argv -element
158 is handled as if it were the argument of
159 an option with character code 1.
160 (This is used by programs that were
161 written to expect options and other
162 .IR argv -elements
163 in any order
164 and that care about the ordering of the two.)
165 The special argument "\-\-" forces an end of option-scanning regardless
166 of the scanning mode.
167 .P
168 While processing the option list,
169 .BR getopt ()
170 can detect two kinds of errors:
171 (1) an option character that was not specified in
172 .I optstring
173 and (2) a missing option argument
174 (i.e., an option at the end of the command line without an expected argument).
175 Such errors are handled and reported as follows:
176 .IP \[bu] 3
177 By default,
178 .BR getopt ()
179 prints an error message on standard error,
180 places the erroneous option character in
181 .IR optopt ,
182 and returns \[aq]?\[aq] as the function result.
183 .IP \[bu]
184 If the caller has set the global variable
185 .I opterr
186 to zero, then
187 .BR getopt ()
188 does not print an error message.
189 The caller can determine that there was an error by testing whether
190 the function return value is \[aq]?\[aq].
191 (By default,
192 .I opterr
193 has a nonzero value.)
194 .IP \[bu]
195 If the first character
196 (following any optional \[aq]+\[aq] or \[aq]\-\[aq] described above)
197 of
198 .I optstring
199 is a colon (\[aq]:\[aq]), then
200 .BR getopt ()
201 likewise does not print an error message.
202 In addition, it returns \[aq]:\[aq] instead of \[aq]?\[aq] to
203 indicate a missing option argument.
204 This allows the caller to distinguish the two different types of errors.
205 .SH RETURN VALUE
206 If an option was successfully found, then
207 .BR getopt ()
208 returns the option character.
209 If all command-line options have been parsed, then
210 .BR getopt ()
211 returns \-1.
212 If
213 .BR getopt ()
214 encounters an option character that was not in
215 .IR optstring ,
216 then \[aq]?\[aq] is returned.
217 If
218 .BR getopt ()
219 encounters an option with a missing argument,
220 then the return value depends on the first character in
221 .IR optstring :
222 if it is \[aq]:\[aq], then \[aq]:\[aq] is returned;
223 otherwise \[aq]?\[aq] is returned.
224 .SH ENVIRONMENT
225 .TP
226 .B \%POSIXLY_CORRECT
227 If this is set, then option processing stops as soon as a nonoption
228 argument is encountered.
229 .SH ATTRIBUTES
230 For an explanation of the terms used in this section, see
231 .BR attributes (7).
232 .TS
233 allbox;
234 lb lb lbx
235 l l l.
236 Interface Attribute Value
237 T{
238 .na
239 .nh
240 .BR getopt ()
241 T} Thread safety T{
242 .na
243 .nh
244 MT-Unsafe race:getopt env
245 T}
246 .TE
247 .SH VERSIONS
248 POSIX specifies that the
249 .I argv
250 array argument should be
251 .IR const ,
252 but these functions permute its elements
253 unless the environment variable
254 .B \%POSIXLY_CORRECT
255 is set.
256 .I const
257 is used in the actual prototype to be compatible with other systems;
258 however, this page doesn't show the qualifier,
259 to avoid confusing readers.
260 .SH STANDARDS
261 .TP
262 .BR getopt ()
263 POSIX.1-2008.
264 .IP
265 The use of \[aq]+\[aq] and \[aq]\-\[aq] in
266 .I optstring
267 is a GNU extension.
268 .SH HISTORY
269 .TP
270 .BR getopt ()
271 POSIX.1-2001, and POSIX.2.
272 .P
273 On some older implementations,
274 .BR getopt ()
275 was declared in
276 .IR <stdio.h> .
277 SUSv1 permitted the declaration to appear in either
278 .I <unistd.h>
279 or
280 .IR <stdio.h> .
281 POSIX.1-1996 marked the use of
282 .I <stdio.h>
283 for this purpose as LEGACY.
284 POSIX.1-2001 does not require the declaration to appear in
285 .IR <stdio.h> .
286 .P
287 Very old versions of glibc were affected by a
288 .UR https:\://\:sourceware.org/\:git/\:?p=glibc.git;a=commitdiff;h=bf079e19f50d64aa5e05
289 .BI \%_ PID _GNU_nonoption_argv_flags_
290 environment variable
291 .UE .
292 .SH NOTES
293 A program that scans multiple argument vectors,
294 or rescans the same vector more than once,
295 and wants to make use of GNU extensions such as \[aq]+\[aq]
296 and \[aq]\-\[aq] at the start of
297 .IR optstring ,
298 or changes the value of
299 .B \%POSIXLY_CORRECT
300 between scans,
301 must reinitialize
302 .BR getopt ()
303 by resetting
304 .I optind
305 to 0, rather than the traditional value of 1.
306 (Resetting to 0 forces the invocation of an internal initialization
307 routine that rechecks
308 .B \%POSIXLY_CORRECT
309 and checks for GNU extensions in
310 .IR optstring .)
311 .P
312 Command-line arguments are parsed in strict order
313 meaning that an option requiring an argument will consume the next argument,
314 regardless of whether that argument is the correctly specified option argument
315 or simply the next option
316 (in the scenario the user mis-specifies the command line).
317 For example, if
318 .I optstring
319 is specified as "1n:"
320 and the user specifies the command line arguments incorrectly as
321 .IR "prog\ \-n\ \-1" ,
322 the
323 .I \-n
324 option will be given the
325 .B optarg
326 value "\-1", and the
327 .I \-1
328 option will be considered to have not been specified.
329 .SH EXAMPLES
330 .SS getopt()
331 The following trivial example program uses
332 .BR getopt ()
333 to handle two program options:
334 .IR \-n ,
335 with no associated value;
336 and
337 .IR \-t\~val ,
338 which expects an associated value.
339 .P
340 .\" SRC BEGIN (getopt.c)
341 .EX
342 #include <stdio.h>
343 #include <stdlib.h>
344 #include <unistd.h>
345 \&
346 int
347 main(int argc, char *argv[])
348 {
349 int flags, opt;
350 int nsecs, tfnd;
351 \&
352 nsecs = 0;
353 tfnd = 0;
354 flags = 0;
355 while ((opt = getopt(argc, argv, "nt:")) != \-1) {
356 switch (opt) {
357 case \[aq]n\[aq]:
358 flags = 1;
359 break;
360 case \[aq]t\[aq]:
361 nsecs = atoi(optarg);
362 tfnd = 1;
363 break;
364 default: /* \[aq]?\[aq] */
365 fprintf(stderr, "Usage: %s [\-t nsecs] [\-n] name\[rs]n",
366 argv[0]);
367 exit(EXIT_FAILURE);
368 }
369 }
370 \&
371 printf("flags=%d; tfnd=%d; nsecs=%d; optind=%d\[rs]n",
372 flags, tfnd, nsecs, optind);
373 \&
374 if (optind >= argc) {
375 fprintf(stderr, "Expected argument after options\[rs]n");
376 exit(EXIT_FAILURE);
377 }
378 \&
379 printf("name argument = %s\[rs]n", argv[optind]);
380 \&
381 /* Other code omitted */
382 \&
383 exit(EXIT_SUCCESS);
384 }
385 .EE
386 .\" SRC END
387 .SH SEE ALSO
388 .BR getopt (1),
389 .BR getopt_long (3),
390 .BR getopt_long_only (3),
391 .BR getsubopt (3)