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 $
4 .\" Copyright (c) 1988, 1991, 1993
5 .\" The Regents of the University of California. All rights reserved.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
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.
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
31 .\" @(#)getopt.3 8.5 (Berkeley) 4/27/95
40 .Nd get long options from command line argument list
45 .Vt extern char *optarg ;
46 .Vt extern int optind ;
47 .Vt extern int optopt ;
48 .Vt extern int opterr ;
49 .Vt extern int optreset ;
52 .Fa "int argc" "char * const *argv" "const char *optstring"
53 .Fa "const struct option *longopts" "int *longindex"
57 .Fa "int argc" "char * const *argv" "const char *optstring"
58 .Fa "const struct option *longopts" "int *longindex"
63 function is similar to
65 but it accepts options in two forms: words and characters.
68 function provides a superset of the functionality of
73 can be used in two ways.
74 In the first way, every long option understood
75 by the program has a corresponding short option, and the option
76 structure is only used to translate from long options to short
78 When used in this fashion,
80 behaves identically to
82 This is a good way to add long option processing to an existing program
83 with the minimum of rewriting.
85 In the second mechanism, a long option sets a flag in the
87 structure passed, or will store a pointer to the command line argument
90 structure passed to it for options that take arguments.
92 the long option's argument may be specified as a single argument with
95 .Dl "myprogram --myoption=somevalue"
97 When a long option is processed, the call to
100 For this reason, long option processing without
101 shortcuts is not backwards compatible with
104 It is possible to combine these methods, providing for long options
105 processing with short option equivalents for some options.
107 frequently used options would be processed as long options only.
111 call requires a structure to be initialized describing the long
114 .Bd -literal -offset indent
125 field should contain the option name without the leading double dash.
129 field should be one of:
131 .Bl -tag -width ".Dv optional_argument" -offset indent -compact
133 no argument to the option is expected
134 .It Dv required_argument
135 an argument to the option is required
136 .It Dv optional_argument
137 an argument to the option may be presented
144 then the integer pointed to by it will be set to the
154 field will be returned.
161 to the corresponding short option will make this function act just
169 then the integer pointed to by it will be set to the index of the long
173 The last element of the
175 array has to be filled with zeroes.
179 function behaves identically to
181 with the exception that long options may start with
185 If an option starting with
187 does not match a long option but does match a single-character option,
188 the single-character option is returned.
199 return the value specified in the
201 field, which is usually just the corresponding short option.
206 these functions return 0 and store
208 in the location pointed to by
211 These functions return
213 if there was a missing option argument and error messages are suppressed,
215 if the user specified an unknown or ambiguous option, and
216 \-1 when the argument list has been exhausted.
217 The default behavior when a missing option argument is encountered is to write
224 will cause the error message to be suppressed and
226 to be returned instead.
236 also has special meaning.
237 If either of these are specified, they must appear before
242 indicates that processing should be halted at the first non-option argument,
243 matching the default behavior of
245 The default behavior without
247 is to permute non-option arguments to the end of
252 indicates that all non-option arguments should be treated as if they are
253 arguments to a literal
255 flag (i.e., the function call will return the value 1, rather than the char
258 .Bl -tag -width ".Ev POSIXLY_CORRECT"
259 .It Ev POSIXLY_CORRECT
260 If set, option processing stops when the first non-option is found and
270 .Bd -literal -compact
274 /* options descriptor */
275 static struct option longopts[] = {
276 { "buffy", no_argument, NULL, 'b' },
277 { "fluoride", required_argument, NULL, 'f' },
278 { "daggerset", no_argument, \*[Am]daggerset, 1 },
283 while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1) {
289 if ((fd = open(optarg, O_RDONLY, 0)) == -1)
290 err(1, "unable to open %s", optarg);
294 fprintf(stderr,"Buffy will use her dagger to "
295 "apply fluoride to dracula's teeth\en");
305 .Sh IMPLEMENTATION DIFFERENCES
306 This section describes differences to the
309 found in glibc-2.1.3:
314 .\" as first char of option string in presence of
315 .\" environment variable
316 .\" .Ev POSIXLY_CORRECT :
317 .\" .Bl -tag -width ".Bx"
320 .\" .Ev POSIXLY_CORRECT
321 .\" and returns non-options as
322 .\" arguments to option '\e1'.
325 .\" .Ev POSIXLY_CORRECT
326 .\" and stops at the first non-option.
331 .\" within the option string (not the first character):
332 .\" .Bl -tag -width ".Bx"
336 .\" on the command line as a non-argument.
340 .\" within the option string matches a
342 .\" (single dash) on the command line.
343 .\" This functionality is provided for backward compatibility with
344 .\" programs, such as
348 .\" as an option flag.
349 .\" This practice is wrong, and should not be used in any current development.
354 .\" in options string in presence of
355 .\" .Ev POSIXLY_CORRECT :
356 .\" .Bl -tag -width ".Bx"
362 .\" .Ev POSIXLY_CORRECT
366 .\" mean the preceding option takes an optional argument.
369 .\" Return value in case of missing argument if first character
374 .\" in option string is not
376 .\" .Bl -tag -width ".Bx"
392 .\" .Bl -tag -width ".Bx"
394 .\" parses this as option
401 .\" and returns \-1 (ignoring the
403 .\" (Because the original
410 for long options with
414 .Bl -tag -width ".Bx"
425 would never be returned).
432 .\" in option string in
435 .\" .Fn getopt_long ) :
436 .\" .Bl -tag -width ".Bx"
438 .\" causes a segfault.
440 .\" no special handling is done;
442 .\" is interpreted as two separate options, neither of which take an argument.
447 for long options without an argument that are
452 .Bl -tag -width ".Bx"
456 to the option name (the argument of
463 (the argument of the long option).
468 with an argument that is not (a prefix to) a known
472 .Bl -tag -width ".Bx"
478 set to the unknown option.
480 treats this as an error (unknown option) and returns
493 .\" The error messages are different.
496 does not permute the argument vector at the same points in
497 the calling sequence as
500 The aspects normally used by
501 the caller (ordering after \-1 is returned, value of
504 to current positions) are the same, though.
505 (We do fewer variable swaps.)
514 functions first appeared in the
540 argument is not really
542 as its elements may be permuted (unless
546 The implementation can completely replace
548 but right now we are using separate code.