| blob | 757d916f110adcd9da2bdd116390a6416688b062 |
1 .\" $NetBSD: getopt_long.3,v 1.14 2003/08/07 16:43:40 agc Exp $
2 .\" $DragonFly: src/lib/libc/stdlib/getopt_long.3,v 1.6 2007/05/12 21:22:10 swildner 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 .\"
33 .Dd March 14, 2007
34 .Dt GETOPT_LONG 3
35 .Os
36 .Sh NAME
37 .Nm getopt_long
38 .Nd get long options from command line argument list
39 .Sh LIBRARY
40 .Lb libc
41 .Sh SYNOPSIS
42 .In getopt.h
43 .Ft int
44 .Fn getopt_long "int argc" "char * const *argv" "const char *optstring" "struct option *long_options" "int *index"
45 .Fn getopt_long_only "int argc" "char * const *argv" "const char *optstring" "struct option *long_options" "int *index"
46 .Sh DESCRIPTION
47 The
48 .Fn getopt_long
49 function is similar to
50 .Xr getopt 3
51 but it accepts options in two forms: words and characters.
52 The
53 .Fn getopt_long
54 function provides a superset of the functionality of
55 .Xr getopt 3 .
56 .Fn getopt_long
57 can be used in two ways.
58 In the first way, every long option understood by the program has a
59 corresponding short option, and the option structure is only used to
60 translate from long options to short options.
61 When used in this fashion,
62 .Fn getopt_long
63 behaves identically to
64 .Xr getopt 3 .
65 This is a good way to add long option processing to an existing program
66 with the minimum of rewriting.
67 .Pp
68 In the second mechanism, a long option sets a flag in the
69 .Fa option
70 structure passed, or will store a pointer to the command line argument
71 in the
72 .Fa option
73 structure passed to it for options that take arguments.
74 Additionally, the long option's argument may be specified as a single
75 argument with an equal sign, e.g.
76 .Bd -literal
77 myprogram --myoption=somevalue
78 .Ed
79 .Pp
80 When a long option is processed the call to
81 .Fn getopt_long
82 will return 0.
83 For this reason, long option processing without
84 shortcuts is not backwards compatible with
85 .Xr getopt 3 .
86 .Pp
87 It is possible to combine these methods, providing for long options
88 processing with short option equivalents for some options.
89 Less frequently used options would be processed as long options only.
90 .Pp
91 The
92 .Fn getopt_long
93 call requires a structure to be initialized describing the long options.
94 The structure is:
95 .Bd -literal
96 struct option {
97 char *name;
98 int has_arg;
99 int *flag;
100 int val;
101 };
102 .Ed
103 .Pp
104 The
105 .Fa name
106 field should contain the option name without the leading double dash.
107 .Pp
108 The
109 .Fa has_arg
110 field should be one of:
111 .Bl -tag -width "optional_argument"
112 .It Li no_argument
113 no argument to the option is expect.
114 .It Li required_argument
115 an argument to the option is required.
116 .It Li optional_argument
117 an argument to the option may be presented.
118 .El
119 .Pp
120 If
121 .Fa flag
122 is not
123 .Dv NULL ,
124 then the integer pointed to by it will be set to the value in the
125 .Fa val
126 field.
127 If the
128 .Fa flag
129 field is
130 .Dv NULL ,
131 then the
132 .Fa val
133 field will be returned.
134 Setting
135 .Fa flag
136 to
137 .Dv NULL
138 and setting
139 .Fa val
140 to the corresponding short option will make this function act just
141 like
142 .Xr getopt 3 .
143 .Pp
144 If the
145 .Fa index
146 field is not
147 .Dv NULL ,
148 the integer it points to will be set to the index of the long option
149 in the
150 .Fa long_options
151 array.
152 .Pp
153 The last element of the
154 .Fa long_options
155 array has to be filled with zeroes (see
156 .Sx EXAMPLES
157 section).
158 .Pp
159 The
160 .Fn getopt_long_only
161 function behaves identically to
162 .Fn getopt_long
163 with the exception that long options may start with
164 .Ql -
165 in addition to
166 .Ql -- .
167 If an option starting with
168 .Ql -
169 does not match a long option but does match a single-character option,
170 the single-character option is returned.
171 Note that the
172 .Fn getopt_long_only
173 function is deprecated.
174 New programs should use
175 .Fn getopt_long .
176 .Sh IMPLEMENTATION DIFFERENCES
177 This section describes differences to the GNU implementation
178 found in glibc-2.1.3:
179 .Bl -tag -width "xxx"
180 .It Li o
181 handling of - as first char of option string in presence of
182 environment variable POSIXLY_CORRECT:
183 .Bl -tag -width "NetBSD"
184 .It Li GNU
185 ignores POSIXLY_CORRECT and returns non-options as
186 arguments to option '\e1'.
187 .It Li NetBSD
188 honors POSIXLY_CORRECT and stops at the first non-option.
189 .El
190 .It Li o
191 handling of :: in options string in presence of POSIXLY_CORRECT:
192 .Bl -tag -width "NetBSD"
193 .It Li Both
194 GNU and
195 .Nx
196 ignore POSIXLY_CORRECT here and take :: to
197 mean the preceding option takes an optional argument.
198 .El
199 .It Li o
200 return value in case of missing argument if first character
201 (after + or -) in option string is not ':':
202 .Bl -tag -width "NetBSD"
203 .It Li GNU
204 returns '?'
205 .It NetBSD
206 returns ':' (since
207 .Nx Ap s
208 getopt does).
209 .El
210 .It Li o
211 handling of --a in getopt:
212 .Bl -tag -width "NetBSD"
213 .It Li GNU
214 parses this as option '-', option 'a'.
215 .It Li NetBSD
216 parses this as '--', and returns \-1 (ignoring the a).
217 (Because the original getopt does.)
218 .El
219 .It Li o
220 setting of optopt for long options with flag !=
221 .Dv NULL :
222 .Bl -tag -width "NetBSD"
223 .It Li GNU
224 sets optopt to val.
225 .It Li NetBSD
226 sets optopt to 0 (since val would never be returned).
227 .El
228 .It Li o
229 handling of -W with W; in option string in getopt (not getopt_long):
230 .Bl -tag -width "NetBSD"
231 .It Li GNU
232 causes a segfault.
233 .It Li NetBSD
234 returns \-1, with optind pointing past the argument of -W
235 (as if `-W arg' were `--arg', and thus '--' had been found).
236 .\" How should we treat W; in the option string when called via
237 .\" getopt? Ignore the ';' or treat it as a ':'? Issue a warning?
238 .El
239 .It Li o
240 setting of optarg for long options without an argument that are
241 invoked via -W (W; in option string):
242 .Bl -tag -width "NetBSD"
243 .It Li GNU
244 sets optarg to the option name (the argument of -W).
245 .It Li NetBSD
246 sets optarg to
247 .Dv NULL
248 (the argument of the long option).
249 .El
250 .It Li o
251 handling of -W with an argument that is not (a prefix to) a known
252 long option (W; in option string):
253 .Bl -tag -width "NetBSD"
254 .It Li GNU
255 returns -W with optarg set to the unknown option.
256 .It Li NetBSD
257 treats this as an error (unknown option) and returns '?' with
258 optopt set to 0 and optarg set to
259 .Dv NULL
260 (as GNU's man page documents).
261 .El
262 .It Li o
263 The error messages are different.
264 .It Li o
265 .Nx
266 does not permute the argument vector at the same points in
267 the calling sequence as GNU does.
268 The aspects normally used by the caller
269 (ordering after \-1 is returned, value of optind relative
270 to current positions) are the same, though.
271 (We do fewer variable swaps.)
272 .El
273 .Sh EXAMPLES
274 .Bd -literal -compact
275 extern char *optarg;
276 extern int optind;
277 int bflag, ch, fd;
278 int daggerset;
280 /* options descriptor */
281 static struct option longopts[] = {
282 { "buffy", no_argument, 0, 'b' },
283 { "fluoride", required_argument, 0, 'f' },
284 { "daggerset", no_argument, \*[Am]daggerset, 1 },
285 { NULL, 0, NULL, 0 }
286 };
288 bflag = 0;
289 while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1)
290 switch (ch) {
291 case 'b':
292 bflag = 1;
293 break;
294 case 'f':
295 if ((fd = open(optarg, O_RDONLY, 0)) \*[Lt] 0) {
296 (void)fprintf(stderr,
297 "myname: %s: %s\en", optarg, strerror(errno));
298 exit(1);
299 }
300 break;
301 case 0:
302 if(daggerset) {
303 fprintf(stderr,"Buffy will use her dagger to "
304 "apply fluoride to dracula's teeth\en");
305 }
306 break;
307 case '?':
308 default:
309 usage();
310 }
311 argc -= optind;
312 argv += optind;
313 .Ed
314 .Sh SEE ALSO
315 .Xr getopt 3
316 .Sh HISTORY
317 The
318 .Fn getopt_long
319 function first appeared in GNU libiberty.
320 The first
321 .Nx
322 implementation appeared in 1.5.