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 April 1, 2000
  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 argc -= optind;
 261 argv += optind;
 262 .Ed
 263 .Sh IMPLEMENTATION DIFFERENCES
 264 This section describes differences to the
 265 .Tn GNU
 266 implementation
 267 found in glibc-2.1.3:
 268 .Bl -bullet
 269 .\" .It
 270 .\" Handling of
 271 .\" .Ql -
 272 .\" as first char of option string in presence of
 273 .\" environment variable
 274 .\" .Ev POSIXLY_CORRECT :
 275 .\" .Bl -tag -width ".Bx"
 276 .\" .It Tn GNU
 277 .\" ignores
 278 .\" .Ev POSIXLY_CORRECT
 279 .\" and returns non-options as
 280 .\" arguments to option '\e1'.
 281 .\" .It Bx
 282 .\" honors
 283 .\" .Ev POSIXLY_CORRECT
 284 .\" and stops at the first non-option.
 285 .\" .El
 286 .\" .It
 287 .\" Handling of
 288 .\" .Ql -
 289 .\" within the option string (not the first character):
 290 .\" .Bl -tag -width ".Bx"
 291 .\" .It Tn GNU
 292 .\" treats a
 293 .\" .Ql -
 294 .\" on the command line as a non-argument.
 295 .\" .It Bx
 296 .\" a
 297 .\" .Ql -
 298 .\" within the option string matches a
 299 .\" .Ql -
 300 .\" (single dash) on the command line.
 301 .\" This functionality is provided for backward compatibility with
 302 .\" programs, such as
 303 .\" .Xr su 1 ,
 304 .\" that use
 305 .\" .Ql -
 306 .\" as an option flag.
 307 .\" This practice is wrong, and should not be used in any current development.
 308 .\" .El
 309 .\" .It
 310 .\" Handling of
 311 .\" .Ql ::
 312 .\" in options string in presence of
 313 .\" .Ev POSIXLY_CORRECT :
 314 .\" .Bl -tag -width ".Bx"
 315 .\" .It Both
 316 .\" .Tn GNU
 317 .\" and
 318 .\" .Bx
 319 .\" ignore
 320 .\" .Ev POSIXLY_CORRECT
 321 .\" here and take
 322 .\" .Ql ::
 323 .\" to
 324 .\" mean the preceding option takes an optional argument.
 325 .\" .El
 326 .\" .It
 327 .\" Return value in case of missing argument if first character
 328 .\" (after
 329 .\" .Ql +
 330 .\" or
 331 .\" .Ql - )
 332 .\" in option string is not
 333 .\" .Ql \&: :
 334 .\" .Bl -tag -width ".Bx"
 335 .\" .It Tn GNU
 336 .\" returns
 337 .\" .Ql \&?
 338 .\" .It Bx
 339 .\" returns
 340 .\" .Ql \&:
 341 .\" (since
 342 .\" .Bx Ns 's
 343 .\" .Fn getopt
 344 .\" does).
 345 .\" .El
 346 .\" .It
 347 .\" Handling of
 348 .\" .Ql --a
 349 .\" in getopt:
 350 .\" .Bl -tag -width ".Bx"
 351 .\" .It Tn GNU
 352 .\" parses this as option
 353 .\" .Ql - ,
 354 .\" option
 355 .\" .Ql a .
 356 .\" .It Bx
 357 .\" parses this as
 358 .\" .Ql -- ,
 359 .\" and returns \-1 (ignoring the
 360 .\" .Ql a ) .
 361 .\" (Because the original
 362 .\" .Fn getopt
 363 .\" does.)
 364 .\" .El
 365 .It
 366 Setting of
 367 .Va optopt
 368 for long options with
 369 .Va flag
 370 !=
 371 .Dv NULL :
 372 .Bl -tag -width ".Bx"
 373 .It Tn GNU
 374 sets
 375 .Va optopt
 376 to
 377 .Va val .
 378 .It Bx
 379 sets
 380 .Va optopt
 381 to 0 (since
 382 .Va val
 383 would never be returned).
 384 .El
 385 .\" .It
 386 .\" Handling of
 387 .\" .Ql -W
 388 .\" with
 389 .\" .Ql W;
 390 .\" in option string in
 391 .\" .Fn getopt
 392 .\" (not
 393 .\" .Fn getopt_long ) :
 394 .\" .Bl -tag -width ".Bx"
 395 .\" .It Tn GNU
 396 .\" causes a segfault.
 397 .\" .It Bx
 398 .\" no special handling is done;
 399 .\" .Ql W;
 400 .\" is interpreted as two separate options, neither of which take an argument.
 401 .\" .El
 402 .It
 403 Setting of
 404 .Va optarg
 405 for long options without an argument that are
 406 invoked via
 407 .Ql -W
 408 .Ql ( W;
 409 in option string):
 410 .Bl -tag -width ".Bx"
 411 .It Tn GNU
 412 sets
 413 .Va optarg
 414 to the option name (the argument of
 415 .Ql -W ) .
 416 .It Bx
 417 sets
 418 .Va optarg
 419 to
 420 .Dv NULL
 421 (the argument of the long option).
 422 .El
 423 .It
 424 Handling of
 425 .Ql -W
 426 with an argument that is not (a prefix to) a known
 427 long option
 428 .Ql ( W;
 429 in option string):
 430 .Bl -tag -width ".Bx"
 431 .It Tn GNU
 432 returns
 433 .Ql -W
 434 with
 435 .Va optarg
 436 set to the unknown option.
 437 .It Bx
 438 treats this as an error (unknown option) and returns
 439 .Ql \&?
 440 with
 441 .Va optopt
 442 set to 0 and
 443 .Va optarg
 444 set to
 445 .Dv NULL
 446 (as
 447 .Tn GNU Ns 's
 448 man page documents).
 449 .El
 450 .\" .It
 451 .\" The error messages are different.
 452 .It
 453 .Bx
 454 does not permute the argument vector at the same points in
 455 the calling sequence as
 456 .Tn GNU
 457 does.
 458 The aspects normally used by
 459 the caller (ordering after \-1 is returned, value of
 460 .Va optind
 461 relative
 462 to current positions) are the same, though.
 463 (We do fewer variable swaps.)
 464 .El
 465 .Sh SEE ALSO
 466 .Xr getopt 3
 467 .Sh HISTORY
 468 The
 469 .Fn getopt_long
 470 and
 471 .Fn getopt_long_only
 472 functions first appeared in
 473 .Tn GNU
 474 libiberty.
 475 The first
 476 .Bx
 477 implementation of
 478 .Fn getopt_long
 479 appeared in
 480 .Nx 1.5 ,
 481 the first
 482 .Bx
 483 implementation of
 484 .Fn getopt_long_only
 485 in
 486 .Ox 3.3 .
 487 .Fx
 488 first included
 489 .Fn getopt_long
 490 in
 491 .Fx 5.0 ,
 492 .Fn getopt_long_only
 493 in
 494 .Fx 5.2 .
 495 .Sh BUGS
 496 The
 497 .Fa argv
 498 argument is not really
 499 .Vt const
 500 as its elements may be permuted (unless
 501 .Ev POSIXLY_CORRECT
 502 is set).
 503 .Pp
 504 The implementation can completely replace
 505 .Xr getopt 3 ,
 506 but right now we are using separate code.