1 .\" Copyright (c) 1988, 1991, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 3. All advertising materials mentioning features or use of this software
13 .\" must display the following acknowledgement:
14 .\" This product includes software developed by the University of
15 .\" California, Berkeley and its contributors.
16 .\" 4. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" @(#)getopt.3 8.5 (Berkeley) 4/27/95
33 .\" $FreeBSD: src/lib/libc/stdlib/getopt.3,v 1.11.2.8 2001/12/14 18:33:58 ru Exp $
34 .\" $DragonFly: src/lib/libc/stdlib/getopt.3,v 1.5 2006/05/26 19:39:37 swildner Exp $
41 .Nd get option character from command line argument list
46 .Vt extern char *optarg ;
47 .Vt extern int optind ;
48 .Vt extern int optopt ;
49 .Vt extern int opterr ;
50 .Vt extern int optreset ;
52 .Fn getopt "int argc" "char * const *argv" "const char *optstring"
56 function incrementally parses a command line argument list
61 An option character is
63 if it has been specified in the string of accepted option characters,
68 may contain the following elements: individual characters, and
69 characters followed by a colon to indicate an option argument
71 For example, an option string
77 recognizes an option and argument
78 .Dq Fl x Ar argument .
81 if a following argument has leading white space.
86 points to an option argument, if it is anticipated,
89 contains the index to the next
91 argument for a subsequent call
98 option character returned by
105 are both initialized to 1.
108 variable may be set to another value before a set of calls to
110 in order to skip over more or less argv entries.
114 to evaluate multiple sets of arguments, or to evaluate a single set of
115 arguments multiple times,
118 must be set to 1 before the second and each additional set of calls to
122 must be reinitialized.
128 when the argument list is exhausted, or
131 option is encountered.
132 The interpretation of options in the argument list may be cancelled
135 (double dash) which causes
137 to signal the end of argument processing and return \-1.
138 When all options have been processed (i.e., up to the first non-option
143 .Bd -literal -compact
147 while ((ch = getopt(argc, argv, "bf:")) != -1) {
153 if ((fd = open(optarg, O_RDONLY, 0)) < 0)
154 err(1, "%s", optarg);
166 function encounters a character not found in the string
169 a missing option argument it writes an error message to the
175 to a zero will disable these error messages.
180 then a missing option argument causes a
182 to be returned in addition to suppressing any error messages.
184 Option arguments are allowed to begin with
186 this is reasonable but
187 reduces the amount of error checking possible.
191 variable was added to make it possible to call the
193 function multiple times.
194 This is an extension to the
205 function was once specified to return
217 may be specified as a character in
221 have an argument associated with it.
224 to be used with programs that expect
227 This practice is wrong, and should not be used in any current development.
228 It is provided for backward compatibility
230 By default, a single dash causes
233 This is, we believe, compatible with System V.
235 It is also possible to handle digits as option letters.
238 to be used with programs that expect a number
241 This practice is wrong, and should not be used in any current development.
242 It is provided for backward compatibility
244 The following code fragment works in most (but not all) cases.
245 .Bd -literal -offset indent
249 while ((ch = getopt(argc, argv, "0123456789")) != -1) {
251 case '0': case '1': case '2': case '3': case '4':
252 case '5': case '6': case '7': case '8': case '9':
253 p = argv[optind - 1];
254 if (p[0] == '-' && p[1] == ch && !p[2])
255 length = strtol(++p, &ep, 10);
256 else if (argv[optind] && argv[optind][1] == ch) {
257 length = strtol((p = argv[optind] + 1),
264 errx(EX_USAGE, "illegal number -- %s", p);