| blob | adf48e67503c339695abbb6d19de43ae8fa8e944 |
1 .\"
2 .\" Copyright (c) 1988, 1991, 1993
3 .\" The Regents of the University of California. All rights reserved.
4 .\"
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
7 .\" are met:
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
13 .\" 3. Neither the name of the University nor the names of its contributors
14 .\" may be used to endorse or promote products derived from this software
15 .\" without specific prior written permission.
16 .\"
17 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27 .\" SUCH DAMAGE.
28 .\"
29 .\"
30 .\" Copyright 2018 Jason King
31 .\" Copyright 2018, Joyent, Inc.
32 .\"
33 .Dd July 17, 2018
34 .Dt GETOPT_LONG 3C
35 .Os
36 .Sh NAME
37 .Nm getopt_long ,
38 .Nm getopt_long_only
39 .Nd get long options from command line argument list
40 .Sh SYNOPSIS
41 .In getopt.h
42 .Vt extern char *optarg ;
43 .Vt extern int optind ;
44 .Vt extern int optopt ;
45 .Vt extern int opterr ;
46 .Ft int
47 .Fo getopt_long
48 .Fa "int argc"
49 .Fa "char * const *argv"
50 .Fa "const char *optstring"
51 .Fa "const struct option *longopts"
52 .Fa "int *longindex"
53 .Fc
54 .Ft int
55 .Fo getopt_long_only
56 .Fa "int argc"
57 .Fa "char * const *argv"
58 .Fa "const char *optstring"
59 .Fa "const struct option *longopts"
60 .Fa "int *longindex"
61 .Fc
62 .Ft int
63 .Fo getopt_long_clip
64 .Fa "int argc"
65 .Fa "char * const *argv"
66 .Fa "const char *optstring"
67 .Fa "const struct option *longopts"
68 .Fa "int *longindex"
69 .Fc
70 .Sh DESCRIPTION
71 The
72 .Fn getopt_long
73 function is similar to
74 .Xr getopt 3C
75 but it accepts options in two forms: words and characters.
76 The
77 .Fn getopt_long
78 function provides a superset of the functionality of
79 .Xr getopt 3C .
80 The
81 .Fn getopt_long
82 function
83 can be used in two ways.
84 .Pp
85 In the first way, every long option understood
86 by the program has a corresponding short option, and the option
87 structure is only used to translate from long options to short
88 options.
89 When used in this fashion,
90 .Fn getopt_long
91 behaves identically to
92 .Xr getopt 3C .
93 This is a good way to add long option processing to an existing program
94 with the minimum of rewriting.
95 .Pp
96 In the second mechanism, a long option sets a flag in the
97 .Vt option
98 structure passed, or will store a pointer to the command line argument
99 in the
100 .Vt option
101 structure passed to it for options that take arguments.
102 Additionally,
103 the long option's argument may be specified as a single argument with
104 an equal sign, e.g.,
105 .Pp
106 .Dl "myprogram --myoption=somevalue"
107 .Pp
108 When a long option is processed, the call to
109 .Fn getopt_long
110 will return 0.
111 For this reason, long option processing without
112 shortcuts is not backwards compatible with
113 .Xr getopt 3C .
114 .Pp
115 It is possible to combine these methods, providing for long options
116 processing with short option equivalents for some options.
117 Less
118 frequently used options would be processed as long options only.
119 .Pp
120 In
121 .Fn getopt_long
122 and
123 .Fn getopt_long_only ,
124 .Fa optstring
125 acts similar to
126 .Fa optstring
127 in
128 .Xr getopt 3C .
129 In addition,
130 .Fa optstring
131 can begin with
132 .Ql +
133 or
134 .Ql - .
135 If
136 .Fa optstring
137 begins with
138 .Ql + ,
139 the first non-option terminates option processing.
140 This is equivalent to setting the environment variable
141 .Ev POSIXLY_CORRECT .
142 If
143 .Fa optstring
144 begins with
145 .Ql - ,
146 non-options are treated as options to the argument
147 .Ql \e1 .
148 .Pp
149 If
150 .Fa optstring
151 does not begin with
152 .Ql +
153 and
154 .Ev POSIXLY_CORRECT
155 is not set, if
156 .Ql W\&;
157 appears in
158 .Fa optstring ,
159 .Ql "-W myoption"
160 is treated the same as
161 .Ql "--myoption"
162 and
163 .Va optarg
164 is set to
165 .Ql myoption .
166 .Pp
167 In
168 .Fn getopt_long_clip ,
169 .Ql +
170 and
171 .Ql -
172 are ignored at the beginning of a string.
173 .Pp
174 The
175 .Fn getopt_long ,
176 .Fn getopt_long_only ,
177 and
178 .Fn getopt_long_clip
179 functions require a structure to be initialized describing the long
180 options.
181 The structure is:
182 .Bd -literal -offset indent
183 struct option {
184 char *name;
185 int has_arg;
186 int *flag;
187 int val;
188 };
189 .Ed
190 .Pp
191 The
192 .Fa name
193 field should contain the option name without the leading double dash.
194 .Pp
195 The
196 .Fa has_arg
197 field should be one of:
198 .Pp
199 .Bl -tag -width ".Dv optional_argument" -offset indent -compact
200 .It Dv no_argument
201 no argument to the option is expected
202 .It Dv required_argument
203 an argument to the option is required
204 .It Dv optional_argument
205 an argument to the option may be presented
206 .El
207 .Pp
208 If
209 .Fa flag
210 is not
211 .Dv NULL ,
212 then the integer pointed to by it will be set to the
213 value in the
214 .Fa val
215 field and
216 .Va optopt
217 will be set to
218 .Sy 0 .
219 If the
220 .Fa flag
221 field is
222 .Dv NULL ,
223 then the
224 .Fa val
225 field will be returned and
226 .Va optopt
227 is set to the value in the
228 .Fa val
229 field.
230 Setting
231 .Fa flag
232 to
233 .Dv NULL
234 and setting
235 .Fa val
236 to the corresponding short option will make this function act just
237 like
238 .Xr getopt 3C .
239 .Pp
240 If the
241 .Fa longindex
242 field is not
243 .Dv NULL ,
244 then the integer pointed to by it will be set to the index of the long
245 option relative to
246 .Fa longopts .
247 .Pp
248 The last element of the
249 .Fa longopts
250 array has to be filled with zeroes.
251 .Pp
252 The
253 .Fn getopt_long_only
254 function behaves identically to
255 .Fn getopt_long
256 with the exception that long options may start with
257 .Ql -
258 in addition to
259 .Ql -- .
260 If an option starting with
261 .Ql -
262 does not match a long option but does match a single-character option,
263 the single-character option is returned.
264 .Pp
265 The
266 .Fn getopt_long_clip
267 function is a variation of
268 .Fn getopt_long
269 except that options must also adhere to the Sun CLIP specification.
270 Specifically, the major differences from
271 .Fn getopt_long
272 are:
273 .Bl -bullet -offset indent
274 .It
275 All option arguments are required
276 .Po
277 .Dv optional_argument
278 is treated the same as
279 .Dv required_argument
280 .Pc .
281 .It
282 Long options cannot be abbreviated on the command line.
283 .It
284 Long options must use a double dash
285 .Pq Ql -- .
286 .It
287 Option processing stops at the first non-option.
288 .It
289 All long options must have an eqivalent short option (single character) and
290 vice-versa.
291 .It
292 A leading
293 .Ql +
294 or
295 .Ql -
296 in
297 .Fa optstring
298 is ignored.
299 .Fa optstring
300 is treated as if it began after the leading
301 .Ql +
302 or
303 .Ql - .
304 .El
305 .Pp
306 On each call to
307 .Fn getopt_long ,
308 .Fn getopt_long_only ,
309 or
310 .Fn getopt_long ,
311 .Va optind
312 is set to the
313 .Va argv
314 index of the
315 .Em next
316 argument to be processed.
317 .Va optind
318 is initialized to
319 .Sy 1
320 prior to the first invocation of
321 .Fn getopt_long ,
322 .Fn getopt_long_only ,
323 or
324 .Fn getopt_long_clip .
325 .Pp
326 If
327 .Va opterr
328 is set to a non-zero value and
329 .Fa optstring
330 does not start with
331 .Ql \&: ,
332 .Fn getopt_long ,
333 .Fn getopt_long_only ,
334 and
335 .Fn getopt_long_clip
336 will print an error message to
337 .Sy stderr
338 when an error or invalid option is encountered.
339 .Sh RETURN VALUES
340 If the
341 .Fa flag
342 field in
343 .Vt "struct option"
344 is
345 .Dv NULL ,
346 .Fn getopt_long
347 and
348 .Fn getopt_long_only
349 return the value specified in the
350 .Fa val
351 field, which is usually just the corresponding short option.
352 If
353 .Fa flag
354 is not
355 .Dv NULL ,
356 these functions return 0 and store
357 .Fa val
358 in the location pointed to by
359 .Fa flag .
360 These functions return
361 .Ql \&:
362 if there was a missing option argument,
363 .Ql \&?
364 if the user specified an unknown or ambiguous option, and
365 \-1 when the argument list has been exhausted.
366 .Pp
367 If a long option to
368 .Fn getopt_long_clip
369 is missing its equivalent short option (or vice-versa),\-1 is returned on the
370 first call to
371 .Fn getopt_long_clip ,
372 and
373 .Dv errno
374 is set to
375 .Er EINVAL .
376 If
377 .Va opterr
378 is set to a non-zero value and
379 .Fa optstring
380 does not start with
381 .Ql \&: ,
382 an error message will be written to
383 .Sy stderr .
384 .Pp
385 If
386 .Fa optstring
387 does not start with
388 .Ql \&:
389 and
390 .Fn getopt_long ,
391 .Fn getopt_long_only ,
392 or
393 .Fn getopt_long_clip
394 return
395 .Ql \&:
396 or
397 .Ql \&? ,
398 if
399 .Va opterr
400 is set to a non-zero value, an error message is written to
401 .Dv stderr .
402 .Sh ENVIRONMENT
403 The following environment variables can effect the execution of
404 .Nm getopt_long ,
405 .Nm getopt_long_only ,
406 and
407 .Nm getopt_long_clip :
408 .Ev LANG ,
409 .Ev LC_ALL ,
410 .Ev LC_MESSAGES .
411 See
412 .Xr environ 5 .
413 .Bl -tag -width ".Ev POSIXLY_CORRECT"
414 .It Ev POSIXLY_CORRECT
415 If set, option processing stops when the first non-option is found and
416 a leading
417 .Ql -
418 or
419 .Ql +
420 in the
421 .Fa optstring
422 is ignored.
423 .El
424 .Sh USAGE
425 Similar to
426 .Xr getopt 3C ,
427 since there is no unambiguous way to detect a missing option-argument except when the
428 option is the last option on the command line, the
429 .Fn getopt_long ,
430 .Fn getopt_long_only ,
431 and
432 .Fn getopt_long_clip
433 functions cannot fully check for mandatory arguments.
434 For example, the option string
435 .Ql ho\&:
436 with an input of
437 .Ql Fl o Fl h
438 will assume that
439 .Ql Fl h
440 is the required argument to
441 .Fl o
442 instead of assuming that
443 .Fl o
444 is missing its option-argument.
445 .Pp
446 Like
447 .Xr getopt 3C ,
448 grouping options taking or requiring arguments with other options is a violation of the
449 Basic Utility Command syntax standard (see
450 .Xr Intro 1 ) .
451 For example, given the option string
452 .Ql cde\&: ,
453 running:
454 .Pp
455 .Dl cmd Fl cde Ar ieio
456 .Pp
457 is incorrect.
458 Current versions of
459 .Nm getopt_long ,
460 .Nm getopt_long_only ,
461 and
462 .Nm getopt_long_clip
463 accept this, however future versions may not support this.
464 The correct invocation would be:
465 .Pp
466 .Dl cmd Fl cd Fl e Ar ieio
467 .Sh EXAMPLES
468 .Bd -literal -compact
469 int bflag, ch, fd;
470 int daggerset;
472 /* options descriptor */
473 static struct option longopts[] = {
474 { "buffy", no_argument, NULL, 'b' },
475 { "fluoride", required_argument, NULL, 'f' },
476 { "daggerset", no_argument, \*[Am]daggerset, 1 },
477 { NULL, 0, NULL, 0 }
478 };
480 bflag = 0;
481 while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1) {
482 switch (ch) {
483 case 'b':
484 bflag = 1;
485 break;
486 case 'f':
487 if ((fd = open(optarg, O_RDONLY, 0)) == -1)
488 err(1, "unable to open %s", optarg);
489 break;
490 case 0:
491 if (daggerset) {
492 fprintf(stderr,"Buffy will use her dagger to "
493 "apply fluoride to dracula's teeth\en");
494 }
495 break;
496 default:
497 usage();
498 }
499 }
500 argc -= optind;
501 argv += optind;
502 .Ed
503 .Sh ERRORS
504 The
505 .Fn getopt_long_clip
506 function will fail if:
507 .Bl -tag -width EINVAL
508 .It Er EINVAL
509 A short option is missing a corresponding long option, or vice-versa.
510 .El
511 .Pp
512 There are no errors defined for
513 .Fn getopt_long
514 and
515 .Fn getopt_long_only .
516 .Sh IMPLEMENTATION DIFFERENCES
517 While the illumos implementations of
518 .Nm getopt_long
519 and
520 .Nm getopt_long_only
521 are broadly compatible with other implementations, the following edge cases
522 have historically been known to vary among implementations:
523 .Bl -bullet
524 .It
525 The setting of
526 .Va optopt
527 for long options with
528 .Fa flag
529 !=
530 .Dv NULL
531 in
532 .Vt struct option .
533 In illumos,
534 .Va optopt
535 is set to 0 (since
536 .Fa val
537 would never be returned).
538 .It
539 The setting of
540 .Va optarg
541 for long options without an argument that are
542 invoked via
543 .Ql -W
544 .Ql ( W\&;
545 in
546 .Fa optstring ) .
547 illumos sets
548 .Va optarg
549 to the option name (the argument of
550 .Ql -W ) .
551 .It
552 The handling of
553 .Ql -W
554 with an argument that is not (a prefix to) a known
555 long option
556 .Ql ( W\&;
557 in
558 .Fa optstring ) .
559 illumos treats this as an error (unknown option) and returns
560 .Ql \&?
561 with
562 .Va optopt
563 set to 0 and
564 .Va optarg
565 set to
566 .Dv NULL .
567 .It
568 illumos
569 may not permute the argument vector at the same points in
570 the calling sequence as other implementations.
571 The aspects normally used by
572 the caller (ordering after \-1 is returned, the value of
573 .Va optind
574 relative
575 to current positions) are the same, though.
576 (We often do fewer variable swaps.)
577 .El
578 .Sh INTERFACE STABILITY
579 Committed
580 .Sh MT-LEVEL
581 Unsafe
582 .Sh SEE ALSO
583 .Xr getopt 3C
584 .Sh BUGS
585 The
586 .Fa argv
587 argument is not really
588 .Vt const
589 as its elements may be permuted (unless
590 .Ev POSIXLY_CORRECT
591 is set).