| blob | 9226a85e8878ab5a2eeef53c4c0d70229ca7d48e |
1 .\" $OpenBSD: getopt_long.3,v 1.10 2004/01/06 23:44:28 fgsch Exp $
2 .\" $NetBSD: getopt_long.3,v 1.14 2003/08/07 16:43:40 agc Exp $
3 .\"
4 .\" Copyright (c) 1988, 1991, 1993
5 .\" The Regents of the University of California. All rights reserved.
6 .\"
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
15 .\" 3. Neither the name of the University nor the names of its contributors
16 .\" may be used to endorse or promote products derived from this software
17 .\" without specific prior written permission.
18 .\"
19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29 .\" SUCH DAMAGE.
30 .\"
31 .\" @(#)getopt.3 8.5 (Berkeley) 4/27/95
32 .\" $FreeBSD: src/lib/libc/stdlib/getopt_long.3,v 1.13 2005/01/20 09:17:04 ru Exp $
33 .\" $DragonFly: src/lib/libc/stdlib/getopt_long.3,v 1.7 2008/11/23 21:55:52 swildner Exp $
34 .\"
35 .Dd April 1, 2000
36 .Dt GETOPT_LONG 3
37 .Os
38 .Sh NAME
39 .Nm getopt_long ,
40 .Nm getopt_long_only
41 .Nd get long options from command line argument list
42 .Sh LIBRARY
43 .Lb libc
44 .Sh SYNOPSIS
45 .In getopt.h
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 ;
51 .Ft int
52 .Fo getopt_long
53 .Fa "int argc" "char * const *argv" "const char *optstring"
54 .Fa "const struct option *longopts" "int *longindex"
55 .Fc
56 .Ft int
57 .Fo getopt_long_only
58 .Fa "int argc" "char * const *argv" "const char *optstring"
59 .Fa "const struct option *longopts" "int *longindex"
60 .Fc
61 .Sh DESCRIPTION
62 The
63 .Fn getopt_long
64 function is similar to
65 .Xr getopt 3
66 but it accepts options in two forms: words and characters.
67 The
68 .Fn getopt_long
69 function provides a superset of the functionality of
70 .Xr getopt 3 .
71 The
72 .Fn getopt_long
73 function
74 can be used in two ways.
75 In the first way, every long option understood
76 by the program has a corresponding short option, and the option
77 structure is only used to translate from long options to short
78 options.
79 When used in this fashion,
80 .Fn getopt_long
81 behaves identically to
82 .Xr getopt 3 .
83 This is a good way to add long option processing to an existing program
84 with the minimum of rewriting.
85 .Pp
86 In the second mechanism, a long option sets a flag in the
87 .Vt option
88 structure passed, or will store a pointer to the command line argument
89 in the
90 .Vt option
91 structure passed to it for options that take arguments.
92 Additionally,
93 the long option's argument may be specified as a single argument with
94 an equal sign, e.g.,
95 .Pp
96 .Dl "myprogram --myoption=somevalue"
97 .Pp
98 When a long option is processed, the call to
99 .Fn getopt_long
100 will return 0.
101 For this reason, long option processing without
102 shortcuts is not backwards compatible with
103 .Xr getopt 3 .
104 .Pp
105 It is possible to combine these methods, providing for long options
106 processing with short option equivalents for some options.
107 Less
108 frequently used options would be processed as long options only.
109 .Pp
110 The
111 .Fn getopt_long
112 call requires a structure to be initialized describing the long
113 options.
114 The structure is:
115 .Bd -literal -offset indent
116 struct option {
117 char *name;
118 int has_arg;
119 int *flag;
120 int val;
121 };
122 .Ed
123 .Pp
124 The
125 .Va name
126 field should contain the option name without the leading double dash.
127 .Pp
128 The
129 .Va has_arg
130 field should be one of:
131 .Pp
132 .Bl -tag -width ".Dv optional_argument" -offset indent -compact
133 .It Dv no_argument
134 no argument to the option is expect
135 .It Dv required_argument
136 an argument to the option is required
137 .It Dv optional_argument
138 an argument to the option may be presented.
139 .El
140 .Pp
141 If
142 .Va flag
143 is not
144 .Dv NULL ,
145 then the integer pointed to by it will be set to the
146 value in the
147 .Va val
148 field.
149 If the
150 .Va flag
151 field is
152 .Dv NULL ,
153 then the
154 .Va val
155 field will be returned.
156 Setting
157 .Va flag
158 to
159 .Dv NULL
160 and setting
161 .Va val
162 to the corresponding short option will make this function act just
163 like
164 .Xr getopt 3 .
165 .Pp
166 If the
167 .Fa longindex
168 field is not
169 .Dv NULL ,
170 then the integer pointed to by it will be set to the index of the long
171 option relative to
172 .Fa longopts .
173 .Pp
174 The last element of the
175 .Fa longopts
176 array has to be filled with zeroes.
177 .Pp
178 The
179 .Fn getopt_long_only
180 function behaves identically to
181 .Fn getopt_long
182 with the exception that long options may start with
183 .Ql -
184 in addition to
185 .Ql -- .
186 If an option starting with
187 .Ql -
188 does not match a long option but does match a single-character option,
189 the single-character option is returned.
190 .Sh RETURN VALUES
191 If the
192 .Fa flag
193 field in
194 .Vt "struct option"
195 is
196 .Dv NULL ,
197 .Fn getopt_long
198 and
199 .Fn getopt_long_only
200 return the value specified in the
201 .Fa val
202 field, which is usually just the corresponding short option.
203 If
204 .Fa flag
205 is not
206 .Dv NULL ,
207 these functions return 0 and store
208 .Fa val
209 in the location pointed to by
210 .Fa flag .
211 These functions return
212 .Ql \&:
213 if there was a missing option argument,
214 .Ql \&?
215 if the user specified an unknown or ambiguous option, and
216 \-1 when the argument list has been exhausted.
217 .Sh ENVIRONMENT
218 .Bl -tag -width ".Ev POSIXLY_CORRECT"
219 .It Ev POSIXLY_CORRECT
220 If set, option processing stops when the first non-option is found and
221 a leading
222 .Ql -
223 or
224 .Ql +
225 in the
226 .Fa optstring
227 is ignored.
228 .El
229 .Sh EXAMPLES
230 .Bd -literal -compact
231 int bflag, ch, fd;
232 int daggerset;
234 /* options descriptor */
235 static struct option longopts[] = {
236 { "buffy", no_argument, NULL, 'b' },
237 { "fluoride", required_argument, NULL, 'f' },
238 { "daggerset", no_argument, \*[Am]daggerset, 1 },
239 { NULL, 0, NULL, 0 }
240 };
242 bflag = 0;
243 while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1)
244 switch (ch) {
245 case 'b':
246 bflag = 1;
247 break;
248 case 'f':
249 if ((fd = open(optarg, O_RDONLY, 0)) == -1)
250 err(1, "unable to open %s", optarg);
251 break;
252 case 0:
253 if (daggerset) {
254 fprintf(stderr,"Buffy will use her dagger to "
255 "apply fluoride to dracula's teeth\en");
256 }
257 break;
258 default:
259 usage();
260 }
261 argc -= optind;
262 argv += optind;
263 .Ed
264 .Sh IMPLEMENTATION DIFFERENCES
265 This section describes differences to the
266 .Tn GNU
267 implementation
268 found in glibc-2.1.3:
269 .Bl -bullet
270 .\" .It
271 .\" Handling of
272 .\" .Ql -
273 .\" as first char of option string in presence of
274 .\" environment variable
275 .\" .Ev POSIXLY_CORRECT :
276 .\" .Bl -tag -width ".Bx"
277 .\" .It Tn GNU
278 .\" ignores
279 .\" .Ev POSIXLY_CORRECT
280 .\" and returns non-options as
281 .\" arguments to option '\e1'.
282 .\" .It Bx
283 .\" honors
284 .\" .Ev POSIXLY_CORRECT
285 .\" and stops at the first non-option.
286 .\" .El
287 .\" .It
288 .\" Handling of
289 .\" .Ql -
290 .\" within the option string (not the first character):
291 .\" .Bl -tag -width ".Bx"
292 .\" .It Tn GNU
293 .\" treats a
294 .\" .Ql -
295 .\" on the command line as a non-argument.
296 .\" .It Bx
297 .\" a
298 .\" .Ql -
299 .\" within the option string matches a
300 .\" .Ql -
301 .\" (single dash) on the command line.
302 .\" This functionality is provided for backward compatibility with
303 .\" programs, such as
304 .\" .Xr su 1 ,
305 .\" that use
306 .\" .Ql -
307 .\" as an option flag.
308 .\" This practice is wrong, and should not be used in any current development.
309 .\" .El
310 .\" .It
311 .\" Handling of
312 .\" .Ql ::
313 .\" in options string in presence of
314 .\" .Ev POSIXLY_CORRECT :
315 .\" .Bl -tag -width ".Bx"
316 .\" .It Both
317 .\" .Tn GNU
318 .\" and
319 .\" .Bx
320 .\" ignore
321 .\" .Ev POSIXLY_CORRECT
322 .\" here and take
323 .\" .Ql ::
324 .\" to
325 .\" mean the preceding option takes an optional argument.
326 .\" .El
327 .\" .It
328 .\" Return value in case of missing argument if first character
329 .\" (after
330 .\" .Ql +
331 .\" or
332 .\" .Ql - )
333 .\" in option string is not
334 .\" .Ql \&: :
335 .\" .Bl -tag -width ".Bx"
336 .\" .It Tn GNU
337 .\" returns
338 .\" .Ql \&?
339 .\" .It Bx
340 .\" returns
341 .\" .Ql \&:
342 .\" (since
343 .\" .Bx Ns 's
344 .\" .Fn getopt
345 .\" does).
346 .\" .El
347 .\" .It
348 .\" Handling of
349 .\" .Ql --a
350 .\" in getopt:
351 .\" .Bl -tag -width ".Bx"
352 .\" .It Tn GNU
353 .\" parses this as option
354 .\" .Ql - ,
355 .\" option
356 .\" .Ql a .
357 .\" .It Bx
358 .\" parses this as
359 .\" .Ql -- ,
360 .\" and returns \-1 (ignoring the
361 .\" .Ql a ) .
362 .\" (Because the original
363 .\" .Fn getopt
364 .\" does.)
365 .\" .El
366 .It
367 Setting of
368 .Va optopt
369 for long options with
370 .Va flag
371 !=
372 .Dv NULL :
373 .Bl -tag -width ".Bx"
374 .It Tn GNU
375 sets
376 .Va optopt
377 to
378 .Va val .
379 .It Bx
380 sets
381 .Va optopt
382 to 0 (since
383 .Va val
384 would never be returned).
385 .El
386 .\" .It
387 .\" Handling of
388 .\" .Ql -W
389 .\" with
390 .\" .Ql W;
391 .\" in option string in
392 .\" .Fn getopt
393 .\" (not
394 .\" .Fn getopt_long ) :
395 .\" .Bl -tag -width ".Bx"
396 .\" .It Tn GNU
397 .\" causes a segfault.
398 .\" .It Bx
399 .\" no special handling is done;
400 .\" .Ql W;
401 .\" is interpreted as two separate options, neither of which take an argument.
402 .\" .El
403 .It
404 Setting of
405 .Va optarg
406 for long options without an argument that are
407 invoked via
408 .Ql -W
409 .Ql ( W;
410 in option string):
411 .Bl -tag -width ".Bx"
412 .It Tn GNU
413 sets
414 .Va optarg
415 to the option name (the argument of
416 .Ql -W ) .
417 .It Bx
418 sets
419 .Va optarg
420 to
421 .Dv NULL
422 (the argument of the long option).
423 .El
424 .It
425 Handling of
426 .Ql -W
427 with an argument that is not (a prefix to) a known
428 long option
429 .Ql ( W;
430 in option string):
431 .Bl -tag -width ".Bx"
432 .It Tn GNU
433 returns
434 .Ql -W
435 with
436 .Va optarg
437 set to the unknown option.
438 .It Bx
439 treats this as an error (unknown option) and returns
440 .Ql \&?
441 with
442 .Va optopt
443 set to 0 and
444 .Va optarg
445 set to
446 .Dv NULL
447 (as
448 .Tn GNU Ns 's
449 man page documents).
450 .El
451 .\" .It
452 .\" The error messages are different.
453 .It
454 .Bx
455 does not permute the argument vector at the same points in
456 the calling sequence as
457 .Tn GNU
458 does.
459 The aspects normally used by
460 the caller (ordering after \-1 is returned, value of
461 .Va optind
462 relative
463 to current positions) are the same, though.
464 (We do fewer variable swaps.)
465 .El
466 .Sh SEE ALSO
467 .Xr getopt 3
468 .Sh HISTORY
469 The
470 .Fn getopt_long
471 and
472 .Fn getopt_long_only
473 functions first appeared in
474 .Tn GNU
475 libiberty.
476 The first
477 .Bx
478 implementation of
479 .Fn getopt_long
480 appeared in
481 .Nx 1.5 ,
482 the first
483 .Bx
484 implementation of
485 .Fn getopt_long_only
486 in
487 .Ox 3.3 .
488 .Fx
489 first included
490 .Fn getopt_long
491 in
492 .Fx 5.0 ,
493 .Fn getopt_long_only
494 in
495 .Fx 5.2 .
496 .Sh BUGS
497 The
498 .Fa argv
499 argument is not really
500 .Vt const
501 as its elements may be permuted (unless
502 .Ev POSIXLY_CORRECT
503 is set).
504 .Pp
505 The implementation can completely replace
506 .Xr getopt 3 ,
507 but right now we are using separate code.