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