| blob | 1e51d0381520689e7677a5638db0176b628c9b7d |
1 .\" $NetBSD: getopt.3,v 1.32 2010/03/22 19:30:54 joerg Exp $
2 .\"
3 .\" Copyright (c) 1988, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
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.
17 .\"
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
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)getopt.3 8.5 (Berkeley) 4/27/95
31 .\"
32 .Dd September 10, 2003
33 .Dt GETOPT 3
34 .Os
35 .Sh NAME
36 .Nm getopt
37 .Nd get option character from command line argument list
38 .Sh LIBRARY
39 .Lb libc
40 .Sh SYNOPSIS
41 .In unistd.h
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;
47 .Ft int
48 .Fn getopt "int argc" "char * const argv[]" "const char *optstring"
49 .Sh DESCRIPTION
50 The
51 .Fn getopt
52 function incrementally parses a command line argument list
53 .Fa argv
54 and returns the next
55 .Em known
56 option character.
57 An option character is
58 .Em known
59 if it has been specified in the string of accepted option characters,
60 .Fa optstring .
61 .Pp
62 The option string
63 .Fa optstring
64 may contain the following elements: individual characters, and
65 characters followed by a colon to indicate an option argument
66 is to follow.
67 For example, an option string
68 .Qq x
69 recognizes an option
70 .Dq Fl x ,
71 and an option string
72 .Qq x:
73 recognizes an option and argument
74 .Dq Fl x Ar argument .
75 It does not matter to
76 .Fn getopt
77 if a following argument has leading whitespace.
78 .Pp
79 On return from
80 .Fn getopt ,
81 .Va optarg
82 points to an option argument, if it is anticipated,
83 and the variable
84 .Va optind
85 contains the index to the next
86 .Fa argv
87 argument for a subsequent call
88 to
89 .Fn getopt .
90 The variable
91 .Va optopt
92 saves the last
93 .Em known
94 option character returned by
95 .Fn getopt .
96 .Pp
97 The variables
98 .Va opterr
99 and
100 .Va optind
101 are both initialized to 1.
102 The
103 .Va optind
104 variable may be set to another value before a set of calls to
105 .Fn getopt
106 in order to skip over more or less argv entries.
107 .Pp
108 In order to use
109 .Fn getopt
110 to evaluate multiple sets of arguments, or to evaluate a single set of
111 arguments multiple times,
112 the variable
113 .Va optreset
114 must be set to 1 before the second and each additional set of calls to
115 .Fn getopt ,
116 and the variable
117 .Va optind
118 must be reinitialized.
119 .Pp
120 The
121 .Fn getopt
122 function returns \-1 when the argument list is exhausted.
123 The interpretation of options in the argument list may be cancelled
124 by the option
125 .Dq --
126 (double dash) which causes
127 .Fn getopt
128 to signal the end of argument processing and return \-1.
129 When all options have been processed (i.e., up to the first non-option
130 argument),
131 .Fn getopt
132 returns \-1.
133 .Sh RETURN VALUES
134 The
135 .Fn getopt
136 function returns the next known option character in
137 .Fa optstring .
138 If
139 .Fn getopt
140 encounters a character not found in
141 .Fa optstring
142 or if it detects a missing option argument,
143 it returns
144 .Sq \&?
145 (question mark).
146 If
147 .Fa optstring
148 has a leading
149 .Sq \&:
150 then a missing option argument causes
151 .Sq \&:
152 to be returned instead of
153 .Sq \&? .
154 In either case, the variable
155 .Va optopt
156 is set to the character that caused the error.
157 The
158 .Fn getopt
159 function returns \-1 when the argument list is exhausted.
160 .Sh EXAMPLES
161 .Bd -literal -compact
162 extern char *optarg;
163 extern int optind;
164 int bflag, ch, fd;
166 bflag = 0;
167 while ((ch = getopt(argc, argv, "bf:")) != -1) {
168 switch (ch) {
169 case 'b':
170 bflag = 1;
171 break;
172 case 'f':
173 if ((fd = open(optarg, O_RDONLY, 0)) \*[Lt] 0) {
174 (void)fprintf(stderr,
175 "myname: %s: %s\en", optarg, strerror(errno));
176 exit(1);
177 }
178 break;
179 case '?':
180 default:
181 usage();
182 }
183 }
184 argc -= optind;
185 argv += optind;
186 .Ed
187 .Sh DIAGNOSTICS
188 If the
189 .Fn getopt
190 function encounters a character not found in the string
191 .Fa optstring
192 or detects
193 a missing option argument it writes an error message to
194 .Em stderr
195 and returns
196 .Sq \&? .
197 Setting
198 .Va opterr
199 to a zero will disable these error messages.
200 If
201 .Fa optstring
202 has a leading
203 .Sq \&:
204 then a missing option argument causes a
205 .Sq \&:
206 to be returned in addition to suppressing any error messages.
207 .Pp
208 Option arguments are allowed to begin with
209 .Sq - ;
210 this is reasonable but reduces the amount of error checking possible.
211 .Sh SEE ALSO
212 .Xr getopt 1 ,
213 .Xr getopt_long 3 ,
214 .Xr getsubopt 3
215 .Sh STANDARDS
216 The
217 .Va optreset
218 variable was added to make it possible to call the
219 .Fn getopt
220 function multiple times.
221 This is an extension to the
222 .St -p1003.2
223 specification.
224 .Sh HISTORY
225 The
226 .Fn getopt
227 function appeared in
228 .Bx 4.3 .
229 .Sh BUGS
230 The
231 .Fn getopt
232 function was once specified to return
233 .Dv EOF
234 instead of \-1.
235 This was changed by
236 .St -p1003.2-92
237 to decouple
238 .Fn getopt
239 from
240 .In stdio.h .
241 .Pp
242 A single dash
243 .Pq Sq -
244 may be specified as a character in
245 .Fa optstring ,
246 however it should
247 .Em never
248 have an argument associated with it.
249 This allows
250 .Fn getopt
251 to be used with programs that expect
252 .Sq -
253 as an option flag.
254 This practice is wrong, and should not be used in any current development.
255 It is provided for backward compatibility
256 .Em only .
257 Care should be taken not to use
258 .Sq -
259 as the first character in
260 .Fa optstring
261 to avoid a semantic conflict with
262 .Tn GNU
263 .Fn getopt ,
264 which assigns different meaning to an
265 .Fa optstring
266 that begins with a
267 .Sq - .
268 By default, a single dash causes
269 .Fn getopt
270 to return \-1.
271 .Pp
272 It is also possible to handle digits as option letters.
273 This allows
274 .Fn getopt
275 to be used with programs that expect a number
276 .Pq Dq Li \-3
277 as an option.
278 This practice is wrong, and should not be used in any current development.
279 It is provided for backward compatibility
280 .Em only .
281 The following code fragment works in most cases.
282 .Bd -literal -offset indent
283 int ch;
284 long length;
285 char *p;
287 while ((ch = getopt(argc, argv, "0123456789")) != -1) {
288 switch (ch) {
289 case '0': case '1': case '2': case '3': case '4':
290 case '5': case '6': case '7': case '8': case '9':
291 p = argv[optind - 1];
292 if (p[0] == '-' \*[Am]\*[Am] p[1] == ch \*[Am]\*[Am] !p[2])
293 length = ch - '0';
294 else
295 length = strtol(argv[optind] + 1, NULL, 10);
296 break;
297 }
298 }
299 .Ed