lib/libc/stdlib/getopt_long.3

   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 .\"
  33 .Dd December 24, 2022
  34 .Dt GETOPT_LONG 3
  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 LIBRARY
  41 .Lb libc
  42 .Sh SYNOPSIS
  43 .In getopt.h
  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 ;
  49 .Ft int
  50 .Fo getopt_long
  51 .Fa "int argc" "char * const *argv" "const char *optstring"
  52 .Fa "const struct option *longopts" "int *longindex"
  53 .Fc
  54 .Ft int
  55 .Fo getopt_long_only
  56 .Fa "int argc" "char * const *argv" "const char *optstring"
  57 .Fa "const struct option *longopts" "int *longindex"
  58 .Fc
  59 .Sh DESCRIPTION
  60 The
  61 .Fn getopt_long
  62 function is similar to
  63 .Xr getopt 3
  64 but it accepts options in two forms: words and characters.
  65 The
  66 .Fn getopt_long
  67 function provides a superset of the functionality of
  68 .Xr getopt 3 .
  69 The
  70 .Fn getopt_long
  71 function
  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
  76 options.
  77 When used in this fashion,
  78 .Fn getopt_long
  79 behaves identically to
  80 .Xr getopt 3 .
  81 This is a good way to add long option processing to an existing program
  82 with the minimum of rewriting.
  83 .Pp
  84 In the second mechanism, a long option sets a flag in the
  85 .Vt option
  86 structure passed, or will store a pointer to the command line argument
  87 in the
  88 .Vt option
  89 structure passed to it for options that take arguments.
  90 Additionally,
  91 the long option's argument may be specified as a single argument with
  92 an equal sign, e.g.,
  93 .Pp
  94 .Dl "myprogram --myoption=somevalue"
  95 .Pp
  96 When a long option is processed, the call to
  97 .Fn getopt_long
  98 will return 0.
  99 For this reason, long option processing without
 100 shortcuts is not backwards compatible with
 101 .Xr getopt 3 .
 102 .Pp
 103 It is possible to combine these methods, providing for long options
 104 processing with short option equivalents for some options.
 105 Less
 106 frequently used options would be processed as long options only.
 107 .Pp
 108 The
 109 .Fn getopt_long
 110 call requires a structure to be initialized describing the long
 111 options.
 112 The structure is:
 113 .Bd -literal -offset indent
 114 struct option {
 115         char *name;
 116         int has_arg;
 117         int *flag;
 118         int val;
 119 };
 120 .Ed
 121 .Pp
 122 The
 123 .Va name
 124 field should contain the option name without the leading double dash.
 125 .Pp
 126 The
 127 .Va has_arg
 128 field should be one of:
 129 .Pp
 130 .Bl -tag -width ".Dv optional_argument" -offset indent -compact
 131 .It Dv no_argument
 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
 137 .El
 138 .Pp
 139 If
 140 .Va flag
 141 is not
 142 .Dv NULL ,
 143 then the integer pointed to by it will be set to the
 144 value in the
 145 .Va val
 146 field.
 147 If the
 148 .Va flag
 149 field is
 150 .Dv NULL ,
 151 then the
 152 .Va val
 153 field will be returned.
 154 Setting
 155 .Va flag
 156 to
 157 .Dv NULL
 158 and setting
 159 .Va val
 160 to the corresponding short option will make this function act just
 161 like
 162 .Xr getopt 3 .
 163 .Pp
 164 If the
 165 .Fa longindex
 166 field is not
 167 .Dv NULL ,
 168 then the integer pointed to by it will be set to the index of the long
 169 option relative to
 170 .Fa longopts .
 171 .Pp
 172 The last element of the
 173 .Fa longopts
 174 array has to be filled with zeroes.
 175 .Pp
 176 The
 177 .Fn getopt_long_only
 178 function behaves identically to
 179 .Fn getopt_long
 180 with the exception that long options may start with
 181 .Ql -
 182 in addition to
 183 .Ql -- .
 184 If an option starting with
 185 .Ql -
 186 does not match a long option but does match a single-character option,
 187 the single-character option is returned.
 188 .Sh RETURN VALUES
 189 If the
 190 .Fa flag
 191 field in
 192 .Vt "struct option"
 193 is
 194 .Dv NULL ,
 195 .Fn getopt_long
 196 and
 197 .Fn getopt_long_only
 198 return the value specified in the
 199 .Fa val
 200 field, which is usually just the corresponding short option.
 201 If
 202 .Fa flag
 203 is not
 204 .Dv NULL ,
 205 these functions return 0 and store
 206 .Fa val
 207 in the location pointed to by
 208 .Fa flag .
 209 .Pp
 210 These functions return
 211 .Ql \&:
 212 if there was a missing option argument and error messages are suppressed,
 213 .Ql \&?
 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
 217 an error and return
 218 .Ql \&? .
 219 Specifying
 220 .Ql \&:
 221 in
 222 .Fa optstr
 223 will cause the error message to be suppressed and
 224 .Ql \&:
 225 to be returned instead.
 226 .Pp
 227 In addition to
 228 .Ql \&: ,
 229 a leading
 230 .Ql \&+
 231 or
 232 .Ql \&-
 233 in
 234 .Fa optstr
 235 also has special meaning.
 236 If either of these are specified, they must appear before
 237 .Ql \&: .
 238 .Pp
 239 A leading
 240 .Ql \&+
 241 indicates that processing should be halted at the first non-option argument,
 242 matching the default behavior of
 243 .Xr getopt 3 .
 244 The default behavior without
 245 .Ql \&+
 246 is to permute non-option arguments to the end of
 247 .Fa argv .
 248 .Pp
 249 A leading
 250 .Ql \&-
 251 indicates that all non-option arguments should be treated as if they are
 252 arguments to a literal
 253 .Ql \&1
 254 flag (i.e., the function call will return the value 1, rather than the char
 255 literal '1').
 256 .Sh ENVIRONMENT
 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
 260 a leading
 261 .Ql -
 262 or
 263 .Ql +
 264 in the
 265 .Fa optstring
 266 is ignored.
 267 .El
 268 .Sh EXAMPLES
 269 .Bd -literal -compact
 270 int bflag, ch, fd;
 271 int daggerset;
 272
 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 },
 278         { NULL,         0,                      NULL,           0 }
 279 };
 280
 281 bflag = 0;
 282 while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1) {
 283         switch (ch) {
 284         case 'b':
 285                 bflag = 1;
 286                 break;
 287         case 'f':
 288                 if ((fd = open(optarg, O_RDONLY, 0)) == -1)
 289                         err(1, "unable to open %s", optarg);
 290                 break;
 291         case 0:
 292                 if (daggerset) {
 293                         fprintf(stderr,"Buffy will use her dagger to "
 294                             "apply fluoride to dracula's teeth\en");
 295                 }
 296                 break;
 297         default:
 298                 usage();
 299         }
 300 }
 301 argc -= optind;
 302 argv += optind;
 303 .Ed
 304 .Sh IMPLEMENTATION DIFFERENCES
 305 This section describes differences to the
 306 .Tn GNU
 307 implementation
 308 found in glibc-2.1.3:
 309 .Bl -bullet
 310 .\" .It
 311 .\" Handling of
 312 .\" .Ql -
 313 .\" as first char of option string in presence of
 314 .\" environment variable
 315 .\" .Ev POSIXLY_CORRECT :
 316 .\" .Bl -tag -width ".Bx"
 317 .\" .It Tn GNU
 318 .\" ignores
 319 .\" .Ev POSIXLY_CORRECT
 320 .\" and returns non-options as
 321 .\" arguments to option '\e1'.
 322 .\" .It Bx
 323 .\" honors
 324 .\" .Ev POSIXLY_CORRECT
 325 .\" and stops at the first non-option.
 326 .\" .El
 327 .\" .It
 328 .\" Handling of
 329 .\" .Ql -
 330 .\" within the option string (not the first character):
 331 .\" .Bl -tag -width ".Bx"
 332 .\" .It Tn GNU
 333 .\" treats a
 334 .\" .Ql -
 335 .\" on the command line as a non-argument.
 336 .\" .It Bx
 337 .\" a
 338 .\" .Ql -
 339 .\" within the option string matches a
 340 .\" .Ql -
 341 .\" (single dash) on the command line.
 342 .\" This functionality is provided for backward compatibility with
 343 .\" programs, such as
 344 .\" .Xr su 1 ,
 345 .\" that use
 346 .\" .Ql -
 347 .\" as an option flag.
 348 .\" This practice is wrong, and should not be used in any current development.
 349 .\" .El
 350 .\" .It
 351 .\" Handling of
 352 .\" .Ql ::
 353 .\" in options string in presence of
 354 .\" .Ev POSIXLY_CORRECT :
 355 .\" .Bl -tag -width ".Bx"
 356 .\" .It Both
 357 .\" .Tn GNU
 358 .\" and
 359 .\" .Bx
 360 .\" ignore
 361 .\" .Ev POSIXLY_CORRECT
 362 .\" here and take
 363 .\" .Ql ::
 364 .\" to
 365 .\" mean the preceding option takes an optional argument.
 366 .\" .El
 367 .\" .It
 368 .\" Return value in case of missing argument if first character
 369 .\" (after
 370 .\" .Ql +
 371 .\" or
 372 .\" .Ql - )
 373 .\" in option string is not
 374 .\" .Ql \&: :
 375 .\" .Bl -tag -width ".Bx"
 376 .\" .It Tn GNU
 377 .\" returns
 378 .\" .Ql \&?
 379 .\" .It Bx
 380 .\" returns
 381 .\" .Ql \&:
 382 .\" (since
 383 .\" .Bx Ns 's
 384 .\" .Fn getopt
 385 .\" does).
 386 .\" .El
 387 .\" .It
 388 .\" Handling of
 389 .\" .Ql --a
 390 .\" in getopt:
 391 .\" .Bl -tag -width ".Bx"
 392 .\" .It Tn GNU
 393 .\" parses this as option
 394 .\" .Ql - ,
 395 .\" option
 396 .\" .Ql a .
 397 .\" .It Bx
 398 .\" parses this as
 399 .\" .Ql -- ,
 400 .\" and returns \-1 (ignoring the
 401 .\" .Ql a ) .
 402 .\" (Because the original
 403 .\" .Fn getopt
 404 .\" does.)
 405 .\" .El
 406 .It
 407 Setting of
 408 .Va optopt
 409 for long options with
 410 .Va flag
 411 !=
 412 .Dv NULL :
 413 .Bl -tag -width ".Bx"
 414 .It Tn GNU
 415 sets
 416 .Va optopt
 417 to
 418 .Va val .
 419 .It Bx
 420 sets
 421 .Va optopt
 422 to 0 (since
 423 .Va val
 424 would never be returned).
 425 .El
 426 .\" .It
 427 .\" Handling of
 428 .\" .Ql -W
 429 .\" with
 430 .\" .Ql W;
 431 .\" in option string in
 432 .\" .Fn getopt
 433 .\" (not
 434 .\" .Fn getopt_long ) :
 435 .\" .Bl -tag -width ".Bx"
 436 .\" .It Tn GNU
 437 .\" causes a segfault.
 438 .\" .It Bx
 439 .\" no special handling is done;
 440 .\" .Ql W;
 441 .\" is interpreted as two separate options, neither of which take an argument.
 442 .\" .El
 443 .It
 444 Setting of
 445 .Va optarg
 446 for long options without an argument that are
 447 invoked via
 448 .Ql -W
 449 .Ql ( W;
 450 in option string):
 451 .Bl -tag -width ".Bx"
 452 .It Tn GNU
 453 sets
 454 .Va optarg
 455 to the option name (the argument of
 456 .Ql -W ) .
 457 .It Bx
 458 sets
 459 .Va optarg
 460 to
 461 .Dv NULL
 462 (the argument of the long option).
 463 .El
 464 .It
 465 Handling of
 466 .Ql -W
 467 with an argument that is not (a prefix to) a known
 468 long option
 469 .Ql ( W;
 470 in option string):
 471 .Bl -tag -width ".Bx"
 472 .It Tn GNU
 473 returns
 474 .Ql -W
 475 with
 476 .Va optarg
 477 set to the unknown option.
 478 .It Bx
 479 treats this as an error (unknown option) and returns
 480 .Ql \&?
 481 with
 482 .Va optopt
 483 set to 0 and
 484 .Va optarg
 485 set to
 486 .Dv NULL
 487 (as
 488 .Tn GNU Ns 's
 489 man page documents).
 490 .El
 491 .\" .It
 492 .\" The error messages are different.
 493 .It
 494 .Bx
 495 does not permute the argument vector at the same points in
 496 the calling sequence as
 497 .Tn GNU
 498 does.
 499 The aspects normally used by
 500 the caller (ordering after \-1 is returned, value of
 501 .Va optind
 502 relative
 503 to current positions) are the same, though.
 504 (We do fewer variable swaps.)
 505 .El
 506 .Sh SEE ALSO
 507 .Xr getopt 3
 508 .Sh HISTORY
 509 The
 510 .Fn getopt_long
 511 and
 512 .Fn getopt_long_only
 513 functions first appeared in the
 514 .Tn GNU
 515 libiberty library.
 516 The first
 517 .Bx
 518 implementation of
 519 .Fn getopt_long
 520 appeared in
 521 .Nx 1.5 ,
 522 the first
 523 .Bx
 524 implementation of
 525 .Fn getopt_long_only
 526 in
 527 .Ox 3.3 .
 528 .Fx
 529 first included
 530 .Fn getopt_long
 531 in
 532 .Fx 5.0 ,
 533 .Fn getopt_long_only
 534 in
 535 .Fx 5.2 .
 536 .Sh BUGS
 537 The
 538 .Fa argv
 539 argument is not really
 540 .Vt const
 541 as its elements may be permuted (unless
 542 .Ev POSIXLY_CORRECT
 543 is set).
 544 .Pp
 545 The implementation can completely replace
 546 .Xr getopt 3 ,
 547 but right now we are using separate code.
 548 .Pp
 549 .Nm
 550 makes the assumption that the first argument should always be skipped because
 551 it's typically the program name.
 552 As a result, setting
 553 .Va optind
 554 to 0 will indicate that
 555 .Nm
 556 should reset, and
 557 .Va optind
 558 will be set to 1 in the process.
 559 This behavior differs from
 560 .Xr getopt 3 ,
 561 which will handle an
 562 .Va optind
 563 value of 0 as expected and process the first element.