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 December 25, 2011
  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 expect
 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 These functions return
 211 .Ql \&:
 212 if there was a missing option argument,
 213 .Ql \&?
 214 if the user specified an unknown or ambiguous option, and
 215 \-1 when the argument list has been exhausted.
 216 .Sh ENVIRONMENT
 217 .Bl -tag -width ".Ev POSIXLY_CORRECT"
 218 .It Ev POSIXLY_CORRECT
 219 If set, option processing stops when the first non-option is found and
 220 a leading
 221 .Ql -
 222 or
 223 .Ql +
 224 in the
 225 .Fa optstring
 226 is ignored.
 227 .El
 228 .Sh EXAMPLES
 229 .Bd -literal -compact
 230 int bflag, ch, fd;
 231 int daggerset;
 232
 233 /* options descriptor */
 234 static struct option longopts[] = {
 235         { "buffy",      no_argument,            NULL,           'b' },
 236         { "fluoride",   required_argument,      NULL,           'f' },
 237         { "daggerset",  no_argument,            \*[Am]daggerset,        1 },
 238         { NULL,         0,                      NULL,           0 }
 239 };
 240
 241 bflag = 0;
 242 while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1) {
 243         switch (ch) {
 244         case 'b':
 245                 bflag = 1;
 246                 break;
 247         case 'f':
 248                 if ((fd = open(optarg, O_RDONLY, 0)) == -1)
 249                         err(1, "unable to open %s", optarg);
 250                 break;
 251         case 0:
 252                 if (daggerset) {
 253                         fprintf(stderr,"Buffy will use her dagger to "
 254                             "apply fluoride to dracula's teeth\en");
 255                 }
 256                 break;
 257         default:
 258                 usage();
 259         }
 260 }
 261 argc -= optind;
 262 argv += optind;
 263 .Ed
 264 .Sh IMPLEMENTATION DIFFERENCES
 265 This section describes differences to the
 266 .Tn GNU
 267 implementation
 268 found in glibc-2.1.3:
 269 .Bl -bullet
 270 .\" .It
 271 .\" Handling of
 272 .\" .Ql -
 273 .\" as first char of option string in presence of
 274 .\" environment variable
 275 .\" .Ev POSIXLY_CORRECT :
 276 .\" .Bl -tag -width ".Bx"
 277 .\" .It Tn GNU
 278 .\" ignores
 279 .\" .Ev POSIXLY_CORRECT
 280 .\" and returns non-options as
 281 .\" arguments to option '\e1'.
 282 .\" .It Bx
 283 .\" honors
 284 .\" .Ev POSIXLY_CORRECT
 285 .\" and stops at the first non-option.
 286 .\" .El
 287 .\" .It
 288 .\" Handling of
 289 .\" .Ql -
 290 .\" within the option string (not the first character):
 291 .\" .Bl -tag -width ".Bx"
 292 .\" .It Tn GNU
 293 .\" treats a
 294 .\" .Ql -
 295 .\" on the command line as a non-argument.
 296 .\" .It Bx
 297 .\" a
 298 .\" .Ql -
 299 .\" within the option string matches a
 300 .\" .Ql -
 301 .\" (single dash) on the command line.
 302 .\" This functionality is provided for backward compatibility with
 303 .\" programs, such as
 304 .\" .Xr su 1 ,
 305 .\" that use
 306 .\" .Ql -
 307 .\" as an option flag.
 308 .\" This practice is wrong, and should not be used in any current development.
 309 .\" .El
 310 .\" .It
 311 .\" Handling of
 312 .\" .Ql ::
 313 .\" in options string in presence of
 314 .\" .Ev POSIXLY_CORRECT :
 315 .\" .Bl -tag -width ".Bx"
 316 .\" .It Both
 317 .\" .Tn GNU
 318 .\" and
 319 .\" .Bx
 320 .\" ignore
 321 .\" .Ev POSIXLY_CORRECT
 322 .\" here and take
 323 .\" .Ql ::
 324 .\" to
 325 .\" mean the preceding option takes an optional argument.
 326 .\" .El
 327 .\" .It
 328 .\" Return value in case of missing argument if first character
 329 .\" (after
 330 .\" .Ql +
 331 .\" or
 332 .\" .Ql - )
 333 .\" in option string is not
 334 .\" .Ql \&: :
 335 .\" .Bl -tag -width ".Bx"
 336 .\" .It Tn GNU
 337 .\" returns
 338 .\" .Ql \&?
 339 .\" .It Bx
 340 .\" returns
 341 .\" .Ql \&:
 342 .\" (since
 343 .\" .Bx Ns 's
 344 .\" .Fn getopt
 345 .\" does).
 346 .\" .El
 347 .\" .It
 348 .\" Handling of
 349 .\" .Ql --a
 350 .\" in getopt:
 351 .\" .Bl -tag -width ".Bx"
 352 .\" .It Tn GNU
 353 .\" parses this as option
 354 .\" .Ql - ,
 355 .\" option
 356 .\" .Ql a .
 357 .\" .It Bx
 358 .\" parses this as
 359 .\" .Ql -- ,
 360 .\" and returns \-1 (ignoring the
 361 .\" .Ql a ) .
 362 .\" (Because the original
 363 .\" .Fn getopt
 364 .\" does.)
 365 .\" .El
 366 .It
 367 Setting of
 368 .Va optopt
 369 for long options with
 370 .Va flag
 371 !=
 372 .Dv NULL :
 373 .Bl -tag -width ".Bx"
 374 .It Tn GNU
 375 sets
 376 .Va optopt
 377 to
 378 .Va val .
 379 .It Bx
 380 sets
 381 .Va optopt
 382 to 0 (since
 383 .Va val
 384 would never be returned).
 385 .El
 386 .\" .It
 387 .\" Handling of
 388 .\" .Ql -W
 389 .\" with
 390 .\" .Ql W;
 391 .\" in option string in
 392 .\" .Fn getopt
 393 .\" (not
 394 .\" .Fn getopt_long ) :
 395 .\" .Bl -tag -width ".Bx"
 396 .\" .It Tn GNU
 397 .\" causes a segfault.
 398 .\" .It Bx
 399 .\" no special handling is done;
 400 .\" .Ql W;
 401 .\" is interpreted as two separate options, neither of which take an argument.
 402 .\" .El
 403 .It
 404 Setting of
 405 .Va optarg
 406 for long options without an argument that are
 407 invoked via
 408 .Ql -W
 409 .Ql ( W;
 410 in option string):
 411 .Bl -tag -width ".Bx"
 412 .It Tn GNU
 413 sets
 414 .Va optarg
 415 to the option name (the argument of
 416 .Ql -W ) .
 417 .It Bx
 418 sets
 419 .Va optarg
 420 to
 421 .Dv NULL
 422 (the argument of the long option).
 423 .El
 424 .It
 425 Handling of
 426 .Ql -W
 427 with an argument that is not (a prefix to) a known
 428 long option
 429 .Ql ( W;
 430 in option string):
 431 .Bl -tag -width ".Bx"
 432 .It Tn GNU
 433 returns
 434 .Ql -W
 435 with
 436 .Va optarg
 437 set to the unknown option.
 438 .It Bx
 439 treats this as an error (unknown option) and returns
 440 .Ql \&?
 441 with
 442 .Va optopt
 443 set to 0 and
 444 .Va optarg
 445 set to
 446 .Dv NULL
 447 (as
 448 .Tn GNU Ns 's
 449 man page documents).
 450 .El
 451 .\" .It
 452 .\" The error messages are different.
 453 .It
 454 .Bx
 455 does not permute the argument vector at the same points in
 456 the calling sequence as
 457 .Tn GNU
 458 does.
 459 The aspects normally used by
 460 the caller (ordering after \-1 is returned, value of
 461 .Va optind
 462 relative
 463 to current positions) are the same, though.
 464 (We do fewer variable swaps.)
 465 .El
 466 .Sh SEE ALSO
 467 .Xr getopt 3
 468 .Sh HISTORY
 469 The
 470 .Fn getopt_long
 471 and
 472 .Fn getopt_long_only
 473 functions first appeared in the
 474 .Tn GNU
 475 libiberty library.
 476 The first
 477 .Bx
 478 implementation of
 479 .Fn getopt_long
 480 appeared in
 481 .Nx 1.5 ,
 482 the first
 483 .Bx
 484 implementation of
 485 .Fn getopt_long_only
 486 in
 487 .Ox 3.3 .
 488 .Fx
 489 first included
 490 .Fn getopt_long
 491 in
 492 .Fx 5.0 ,
 493 .Fn getopt_long_only
 494 in
 495 .Fx 5.2 .
 496 .Sh BUGS
 497 The
 498 .Fa argv
 499 argument is not really
 500 .Vt const
 501 as its elements may be permuted (unless
 502 .Ev POSIXLY_CORRECT
 503 is set).
 504 .Pp
 505 The implementation can completely replace
 506 .Xr getopt 3 ,
 507 but right now we are using separate code.