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: src/lib/libc/stdlib/getopt_long.3,v 1.13 2005/01/20 09:17:04 ru Exp $
  33 .\" $DragonFly: src/lib/libc/stdlib/getopt_long.3,v 1.7 2008/11/23 21:55:52 swildner Exp $
  34 .\"
  35 .Dd April 1, 2000
  36 .Dt GETOPT_LONG 3
  37 .Os
  38 .Sh NAME
  39 .Nm getopt_long ,
  40 .Nm getopt_long_only
  41 .Nd get long options from command line argument list
  42 .Sh LIBRARY
  43 .Lb libc
  44 .Sh SYNOPSIS
  45 .In getopt.h
  46 .Vt extern char *optarg ;
  47 .Vt extern int optind ;
  48 .Vt extern int optopt ;
  49 .Vt extern int opterr ;
  50 .Vt extern int optreset ;
  51 .Ft int
  52 .Fo getopt_long
  53 .Fa "int argc" "char * const *argv" "const char *optstring"
  54 .Fa "const struct option *longopts" "int *longindex"
  55 .Fc
  56 .Ft int
  57 .Fo getopt_long_only
  58 .Fa "int argc" "char * const *argv" "const char *optstring"
  59 .Fa "const struct option *longopts" "int *longindex"
  60 .Fc
  61 .Sh DESCRIPTION
  62 The
  63 .Fn getopt_long
  64 function is similar to
  65 .Xr getopt 3
  66 but it accepts options in two forms: words and characters.
  67 The
  68 .Fn getopt_long
  69 function provides a superset of the functionality of
  70 .Xr getopt 3 .
  71 The
  72 .Fn getopt_long
  73 function
  74 can be used in two ways.
  75 In the first way, every long option understood
  76 by the program has a corresponding short option, and the option
  77 structure is only used to translate from long options to short
  78 options.
  79 When used in this fashion,
  80 .Fn getopt_long
  81 behaves identically to
  82 .Xr getopt 3 .
  83 This is a good way to add long option processing to an existing program
  84 with the minimum of rewriting.
  85 .Pp
  86 In the second mechanism, a long option sets a flag in the
  87 .Vt option
  88 structure passed, or will store a pointer to the command line argument
  89 in the
  90 .Vt option
  91 structure passed to it for options that take arguments.
  92 Additionally,
  93 the long option's argument may be specified as a single argument with
  94 an equal sign, e.g.,
  95 .Pp
  96 .Dl "myprogram --myoption=somevalue"
  97 .Pp
  98 When a long option is processed, the call to
  99 .Fn getopt_long
 100 will return 0.
 101 For this reason, long option processing without
 102 shortcuts is not backwards compatible with
 103 .Xr getopt 3 .
 104 .Pp
 105 It is possible to combine these methods, providing for long options
 106 processing with short option equivalents for some options.
 107 Less
 108 frequently used options would be processed as long options only.
 109 .Pp
 110 The
 111 .Fn getopt_long
 112 call requires a structure to be initialized describing the long
 113 options.
 114 The structure is:
 115 .Bd -literal -offset indent
 116 struct option {
 117         char *name;
 118         int has_arg;
 119         int *flag;
 120         int val;
 121 };
 122 .Ed
 123 .Pp
 124 The
 125 .Va name
 126 field should contain the option name without the leading double dash.
 127 .Pp
 128 The
 129 .Va has_arg
 130 field should be one of:
 131 .Pp
 132 .Bl -tag -width ".Dv optional_argument" -offset indent -compact
 133 .It Dv no_argument
 134 no argument to the option is expect
 135 .It Dv required_argument
 136 an argument to the option is required
 137 .It Dv optional_argument
 138 an argument to the option may be presented.
 139 .El
 140 .Pp
 141 If
 142 .Va flag
 143 is not
 144 .Dv NULL ,
 145 then the integer pointed to by it will be set to the
 146 value in the
 147 .Va val
 148 field.
 149 If the
 150 .Va flag
 151 field is
 152 .Dv NULL ,
 153 then the
 154 .Va val
 155 field will be returned.
 156 Setting
 157 .Va flag
 158 to
 159 .Dv NULL
 160 and setting
 161 .Va val
 162 to the corresponding short option will make this function act just
 163 like
 164 .Xr getopt 3 .
 165 .Pp
 166 If the
 167 .Fa longindex
 168 field is not
 169 .Dv NULL ,
 170 then the integer pointed to by it will be set to the index of the long
 171 option relative to
 172 .Fa longopts .
 173 .Pp
 174 The last element of the
 175 .Fa longopts
 176 array has to be filled with zeroes.
 177 .Pp
 178 The
 179 .Fn getopt_long_only
 180 function behaves identically to
 181 .Fn getopt_long
 182 with the exception that long options may start with
 183 .Ql -
 184 in addition to
 185 .Ql -- .
 186 If an option starting with
 187 .Ql -
 188 does not match a long option but does match a single-character option,
 189 the single-character option is returned.
 190 .Sh RETURN VALUES
 191 If the
 192 .Fa flag
 193 field in
 194 .Vt "struct option"
 195 is
 196 .Dv NULL ,
 197 .Fn getopt_long
 198 and
 199 .Fn getopt_long_only
 200 return the value specified in the
 201 .Fa val
 202 field, which is usually just the corresponding short option.
 203 If
 204 .Fa flag
 205 is not
 206 .Dv NULL ,
 207 these functions return 0 and store
 208 .Fa val
 209 in the location pointed to by
 210 .Fa flag .
 211 These functions return
 212 .Ql \&:
 213 if there was a missing option argument,
 214 .Ql \&?
 215 if the user specified an unknown or ambiguous option, and
 216 \-1 when the argument list has been exhausted.
 217 .Sh ENVIRONMENT
 218 .Bl -tag -width ".Ev POSIXLY_CORRECT"
 219 .It Ev POSIXLY_CORRECT
 220 If set, option processing stops when the first non-option is found and
 221 a leading
 222 .Ql -
 223 or
 224 .Ql +
 225 in the
 226 .Fa optstring
 227 is ignored.
 228 .El
 229 .Sh EXAMPLES
 230 .Bd -literal -compact
 231 int bflag, ch, fd;
 232 int daggerset;
 233
 234 /* options descriptor */
 235 static struct option longopts[] = {
 236         { "buffy",      no_argument,            NULL,           'b' },
 237         { "fluoride",   required_argument,      NULL,           'f' },
 238         { "daggerset",  no_argument,            \*[Am]daggerset,        1 },
 239         { NULL,         0,                      NULL,           0 }
 240 };
 241
 242 bflag = 0;
 243 while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1)
 244         switch (ch) {
 245         case 'b':
 246                 bflag = 1;
 247                 break;
 248         case 'f':
 249                 if ((fd = open(optarg, O_RDONLY, 0)) == -1)
 250                         err(1, "unable to open %s", optarg);
 251                 break;
 252         case 0:
 253                 if (daggerset) {
 254                         fprintf(stderr,"Buffy will use her dagger to "
 255                             "apply fluoride to dracula's teeth\en");
 256                 }
 257                 break;
 258         default:
 259                 usage();
 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
 474 .Tn GNU
 475 libiberty.
 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.