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