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
39 .Nd get long options from command line argument list
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 ;
51 .Fa "int argc" "char * const *argv" "const char *optstring"
52 .Fa "const struct option *longopts" "int *longindex"
56 .Fa "int argc" "char * const *argv" "const char *optstring"
57 .Fa "const struct option *longopts" "int *longindex"
62 function is similar to
64 but it accepts options in two forms: words and characters.
67 function provides a superset of the functionality of
72 can be used in two ways.
73 In the first way, every long option understood
74 by the program has a corresponding short option, and the option
75 structure is only used to translate from long options to short
77 When used in this fashion,
79 behaves identically to
81 This is a good way to add long option processing to an existing program
82 with the minimum of rewriting.
84 In the second mechanism, a long option sets a flag in the
86 structure passed, or will store a pointer to the command line argument
89 structure passed to it for options that take arguments.
91 the long option's argument may be specified as a single argument with
94 .Dl "myprogram --myoption=somevalue"
96 When a long option is processed, the call to
99 For this reason, long option processing without
100 shortcuts is not backwards compatible with
103 It is possible to combine these methods, providing for long options
104 processing with short option equivalents for some options.
106 frequently used options would be processed as long options only.
110 call requires a structure to be initialized describing the long
113 .Bd -literal -offset indent
124 field should contain the option name without the leading double dash.
128 field should be one of:
130 .Bl -tag -width ".Dv optional_argument" -offset indent -compact
132 no argument to the option is expected
133 .It Dv required_argument
134 an argument to the option is required
135 .It Dv optional_argument
136 an argument to the option may be presented
143 then the integer pointed to by it will be set to the
153 field will be returned.
160 to the corresponding short option will make this function act just
168 then the integer pointed to by it will be set to the index of the long
172 The last element of the
174 array has to be filled with zeroes.
178 function behaves identically to
180 with the exception that long options may start with
184 If an option starting with
186 does not match a long option but does match a single-character option,
187 the single-character option is returned.
198 return the value specified in the
200 field, which is usually just the corresponding short option.
205 these functions return 0 and store
207 in the location pointed to by
210 These functions return
212 if there was a missing option argument and error messages are suppressed,
214 if the user specified an unknown or ambiguous option, and
215 \-1 when the argument list has been exhausted.
216 The default behavior when a missing option argument is encountered is to write
223 will cause the error message to be suppressed and
225 to be returned instead.
235 also has special meaning.
236 If either of these are specified, they must appear before
241 indicates that processing should be halted at the first non-option argument,
242 matching the default behavior of
244 The default behavior without
246 is to permute non-option arguments to the end of
251 indicates that all non-option arguments should be treated as if they are
252 arguments to a literal
254 flag (i.e., the function call will return the value 1, rather than the char
257 .Bl -tag -width ".Ev POSIXLY_CORRECT"
258 .It Ev POSIXLY_CORRECT
259 If set, option processing stops when the first non-option is found and
269 .Bd -literal -compact
273 /* options descriptor */
274 static struct option longopts[] = {
275 { "buffy", no_argument, NULL, 'b' },
276 { "fluoride", required_argument, NULL, 'f' },
277 { "daggerset", no_argument, \*[Am]daggerset, 1 },
282 while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1) {
288 if ((fd = open(optarg, O_RDONLY, 0)) == -1)
289 err(1, "unable to open %s", optarg);
293 fprintf(stderr,"Buffy will use her dagger to "
294 "apply fluoride to dracula's teeth\en");
304 .Sh IMPLEMENTATION DIFFERENCES
305 This section describes differences to the
308 found in glibc-2.1.3:
313 .\" as first char of option string in presence of
314 .\" environment variable
315 .\" .Ev POSIXLY_CORRECT :
316 .\" .Bl -tag -width ".Bx"
319 .\" .Ev POSIXLY_CORRECT
320 .\" and returns non-options as
321 .\" arguments to option '\e1'.
324 .\" .Ev POSIXLY_CORRECT
325 .\" and stops at the first non-option.
330 .\" within the option string (not the first character):
331 .\" .Bl -tag -width ".Bx"
335 .\" on the command line as a non-argument.
339 .\" within the option string matches a
341 .\" (single dash) on the command line.
342 .\" This functionality is provided for backward compatibility with
343 .\" programs, such as
347 .\" as an option flag.
348 .\" This practice is wrong, and should not be used in any current development.
353 .\" in options string in presence of
354 .\" .Ev POSIXLY_CORRECT :
355 .\" .Bl -tag -width ".Bx"
361 .\" .Ev POSIXLY_CORRECT
365 .\" mean the preceding option takes an optional argument.
368 .\" Return value in case of missing argument if first character
373 .\" in option string is not
375 .\" .Bl -tag -width ".Bx"
391 .\" .Bl -tag -width ".Bx"
393 .\" parses this as option
400 .\" and returns \-1 (ignoring the
402 .\" (Because the original
409 for long options with
413 .Bl -tag -width ".Bx"
424 would never be returned).
431 .\" in option string in
434 .\" .Fn getopt_long ) :
435 .\" .Bl -tag -width ".Bx"
437 .\" causes a segfault.
439 .\" no special handling is done;
441 .\" is interpreted as two separate options, neither of which take an argument.
446 for long options without an argument that are
451 .Bl -tag -width ".Bx"
455 to the option name (the argument of
462 (the argument of the long option).
467 with an argument that is not (a prefix to) a known
471 .Bl -tag -width ".Bx"
477 set to the unknown option.
479 treats this as an error (unknown option) and returns
492 .\" The error messages are different.
495 does not permute the argument vector at the same points in
496 the calling sequence as
499 The aspects normally used by
500 the caller (ordering after \-1 is returned, value of
503 to current positions) are the same, though.
504 (We do fewer variable swaps.)
513 functions first appeared in the
539 argument is not really
541 as its elements may be permuted (unless
545 The implementation can completely replace
547 but right now we are using separate code.
550 makes the assumption that the first argument should always be skipped because
551 it's typically the program name.
554 to 0 will indicate that
558 will be set to 1 in the process.
559 This behavior differs from
563 value of 0 as expected and process the first element.