1 .\" $NetBSD: getopt.3,v 1.34 2014/06/05 22:09:50 wiz Exp $
3 .\" Copyright (c) 1988, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" @(#)getopt.3 8.5 (Berkeley) 4/27/95
37 .Nd get option character from command line argument list
42 .Vt extern char *optarg;
43 .Vt extern int optind;
44 .Vt extern int optopt;
45 .Vt extern int opterr;
46 .Vt extern int optreset;
48 .Fn getopt "int argc" "char * const argv[]" "const char *optstring"
52 function incrementally parses a command line argument list
57 An option character is
59 if it has been specified in the string of accepted option characters,
64 may contain the following elements: individual characters, and
65 characters followed by a colon to indicate an option argument
67 If an individual character is followed by two colons, then the
68 option argument is optional;
70 is set to the rest of the current
74 if there were no more characters in the current word.
78 For example, an option string
84 recognizes an option and argument
85 .Dq Fl x Ar argument .
88 if a following argument has leading whitespace.
93 points to an option argument, if it is anticipated,
96 contains the index to the next
98 argument for a subsequent call
105 option character returned by
112 are both initialized to 1.
115 variable may be set to another value before a set of calls to
117 in order to skip over more or less argv entries.
121 to evaluate multiple sets of arguments, or to evaluate a single set of
122 arguments multiple times,
125 must be set to 1 before the second and each additional set of calls to
129 must be reinitialized.
133 function returns \-1 when the argument list is exhausted.
134 The interpretation of options in the argument list may be cancelled
137 (double dash) which causes
139 to signal the end of argument processing and return \-1.
140 When all options have been processed (i.e., up to the first non-option
147 function returns the next known option character in
151 encounters a character not found in
153 or if it detects a missing option argument,
161 then a missing option argument causes
163 to be returned instead of
165 In either case, the variable
167 is set to the character that caused the error.
170 function returns \-1 when the argument list is exhausted.
172 .Bd -literal -compact
178 while ((ch = getopt(argc, argv, "bf:")) != -1) {
184 if ((fd = open(optarg, O_RDONLY, 0)) \*[Lt] 0) {
185 (void)fprintf(stderr,
186 "myname: %s: %s\en", optarg, strerror(errno));
201 function encounters a character not found in the string
204 a missing option argument it writes an error message to
210 to a zero will disable these error messages.
215 then a missing option argument causes a
217 to be returned in addition to suppressing any error messages.
219 Option arguments are allowed to begin with
221 this is reasonable but reduces the amount of error checking possible.
229 variable was added to make it possible to call the
231 function multiple times.
232 This is an extension to the
243 function was once specified to return
255 may be specified as a character in
259 have an argument associated with it.
262 to be used with programs that expect
265 This practice is wrong, and should not be used in any current development.
266 It is provided for backward compatibility
268 Care should be taken not to use
270 as the first character in
272 to avoid a semantic conflict with
275 which assigns different meaning to an
279 By default, a single dash causes
283 It is also possible to handle digits as option letters.
286 to be used with programs that expect a number
289 This practice is wrong, and should not be used in any current development.
290 It is provided for backward compatibility
292 The following code fragment works in most cases.
293 .Bd -literal -offset indent
298 while ((ch = getopt(argc, argv, "0123456789")) != -1) {
300 case '0': case '1': case '2': case '3': case '4':
301 case '5': case '6': case '7': case '8': case '9':
302 p = argv[optind - 1];
303 if (p[0] == '-' \*[Am]\*[Am] p[1] == ch \*[Am]\*[Am] !p[2])
306 length = strtol(argv[optind] + 1, NULL, 10);