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