gdb - Local mods (compile)
[dragonfly.git] / lib / libc / stdlib / getopt.3
1 .\"     $NetBSD: getopt.3,v 1.31 2003/09/23 10:26:54 wiz 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 .\" $FreeBSD: src/lib/libc/stdlib/getopt.3,v 1.26 2007/01/09 00:28:10 imp Exp $
32 .\" $DragonFly: src/lib/libc/stdlib/getopt.3,v 1.5 2006/05/26 19:39:37 swildner Exp $
33 .\"
34 .Dd April 27, 1995
35 .Dt GETOPT 3
36 .Os
37 .Sh NAME
38 .Nm getopt
39 .Nd get option character from command line argument list
40 .Sh LIBRARY
41 .Lb libc
42 .Sh SYNOPSIS
43 .In unistd.h
44 .Vt extern char *optarg ;
45 .Vt extern int optind ;
46 .Vt extern int optopt ;
47 .Vt extern int opterr ;
48 .Vt extern int optreset ;
49 .Ft int
50 .Fn getopt "int argc" "char * const argv[]" "const char *optstring"
51 .Sh DESCRIPTION
52 The
53 .Fn getopt
54 function incrementally parses a command line argument list
55 .Fa argv
56 and returns the next
57 .Em known
58 option character.
59 An option character is
60 .Em known
61 if it has been specified in the string of accepted option characters,
62 .Fa optstring .
63 .Pp
64 The option string
65 .Fa optstring
66 may contain the following elements: individual characters, and
67 characters followed by a colon to indicate an option argument
68 is to follow.
69 For example, an option string
70 .Li \&"x"
71 recognizes an option
72 .Dq Fl x ,
73 and an option string
74 .Li \&"x:"
75 recognizes an option and argument
76 .Dq Fl x Ar argument .
77 It does not matter to
78 .Fn getopt
79 if a following argument has leading white space.
80 .Pp
81 On return from
82 .Fn getopt ,
83 .Va optarg
84 points to an option argument, if it is anticipated,
85 and the variable
86 .Va optind
87 contains the index to the next
88 .Fa argv
89 argument for a subsequent call
90 to
91 .Fn getopt .
92 The variable
93 .Va optopt
94 saves the last
95 .Em known
96 option character returned by
97 .Fn getopt .
98 .Pp
99 The variables
100 .Va opterr
101 and
102 .Va optind
103 are both initialized to 1.
104 The
105 .Va optind
106 variable may be set to another value before a set of calls to
107 .Fn getopt
108 in order to skip over more or less argv entries.
109 .Pp
110 In order to use
111 .Fn getopt
112 to evaluate multiple sets of arguments, or to evaluate a single set of
113 arguments multiple times,
114 the variable
115 .Va optreset
116 must be set to 1 before the second and each additional set of calls to
117 .Fn getopt ,
118 and the variable
119 .Va optind
120 must be reinitialized.
121 .Pp
122 The
123 .Fn getopt
124 function returns \-1 when the argument list is exhausted.
125 The interpretation of options in the argument list may be cancelled
126 by the option
127 .Ql --
128 (double dash) which causes
129 .Fn getopt
130 to signal the end of argument processing and return \-1.
131 When all options have been processed (i.e., up to the first non-option
132 argument),
133 .Fn getopt
134 returns \-1.
135 .Sh RETURN VALUES
136 The
137 .Fn getopt
138 function returns the next known option character in
139 .Fa optstring .
140 If
141 .Fn getopt
142 encounters a character not found in
143 .Fa optstring
144 or if it detects a missing option argument,
145 it returns
146 .Ql \&?
147 (question mark).
148 If
149 .Fa optstring
150 has a leading
151 .Ql \&:
152 then a missing option argument causes
153 .Ql \&:
154 to be returned instead of
155 .Ql \&? .
156 In either case, the variable
157 .Va optopt
158 is set to the character that caused the error.
159 The
160 .Fn getopt
161 function returns \-1 when the argument list is exhausted.
162 .Sh EXAMPLES
163 .Bd -literal -compact
164 #include <unistd.h>
165 int bflag, ch, fd;
166
167 bflag = 0;
168 while ((ch = getopt(argc, argv, "bf:")) != -1) {
169         switch (ch) {
170         case 'b':
171                 bflag = 1;
172                 break;
173         case 'f':
174                 if ((fd = open(optarg, O_RDONLY, 0)) \*[Lt] 0) {
175                         fprintf(stderr,
176                             "myname: %s: %s\en", optarg, strerror(errno));
177                         exit(1);
178                 }
179                 break;
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 the
194 .Dv stderr
195 and returns
196 .Ql \&? .
197 Setting
198 .Va opterr
199 to a zero will disable these error messages.
200 If
201 .Fa optstring
202 has a leading
203 .Ql \&:
204 then a missing option argument causes a
205 .Ql \&:
206 to be returned in addition to suppressing any error messages.
207 .Pp
208 Option arguments are allowed to begin with
209 .Dq Li \- ;
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 .Dq Li -
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 .Dq Li -
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 .Ql \&-
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 .Ql \&- .
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, *ep;
286
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                         ep = "";
295                 } else if (argv[optind] \*[Am]\*[Am] argv[optind][1] == ch) {
296                         length = strtol((p = argv[optind] + 1),
297                             \*[Am]ep, 10);
298                         optind++;
299                         optreset = 1;
300                 } else
301                         usage();
302                 if (*ep != '\e0')
303                         errx(EX_USAGE, "illegal number -- %s", p);
304                 break;
305         }
306 }
307 .Ed