stdlib/FreeBSD/getopt_long.3

   1 .\"     $NetBSD: getopt_long.3,v 1.8 2002/06/03 12:01:43 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1988, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)getopt.3    8.5 (Berkeley) 4/27/95
  35 .\" $FreeBSD: src/lib/libc/stdlib/getopt_long.3,v 1.3 2002/12/18 12:45:10 ru Exp $
  36 .\"
  37 .Dd April 1, 2000
  38 .Dt GETOPT_LONG 3
  39 .Os
  40 .Sh NAME
  41 .Nm getopt_long
  42 .Nd get long options from command line argument list
  43 .Sh LIBRARY
  44 .Lb libc
  45 .Sh SYNOPSIS
  46 .In getopt.h
  47 .Ft int
  48 .Fo getopt_long
  49 .Fa "int argc" "char * const *argv" "const char *optstring"
  50 .Fa "struct option *long options" "int *index"
  51 .Fc
  52 .Sh DESCRIPTION
  53 The
  54 .Fn getopt_long
  55 function is similar to
  56 .Xr getopt 3
  57 but it accepts options in two forms: words and characters.
  58 The
  59 .Fn getopt_long
  60 function provides a superset of the functionality of
  61 .Xr getopt 3 .
  62 The
  63 .Fn getopt_long
  64 function
  65 can be used in two ways.
  66 In the first way, every long option understood
  67 by the program has a corresponding short option, and the option
  68 structure is only used to translate from long options to short
  69 options.
  70 When used in this fashion,
  71 .Fn getopt_long
  72 behaves identically to
  73 .Xr getopt 3 .
  74 This is a good way to add long option processing to an existing program
  75 with the minimum of rewriting.
  76 .Pp
  77 In the second mechanism, a long option sets a flag in the
  78 .Vt option
  79 structure passed, or will store a pointer to the command line argument
  80 in the
  81 .Vt option
  82 structure passed to it for options that take arguments.
  83 Additionally,
  84 the long option's argument may be specified as a single argument with
  85 an equal sign, e.g.,
  86 .Pp
  87 .Dl "myprogram --myoption=somevalue"
  88 .Pp
  89 When a long option is processed, the call to
  90 .Fn getopt_long
  91 will return 0.
  92 For this reason, long option processing without
  93 shortcuts is not backwards compatible with
  94 .Xr getopt 3 .
  95 .Pp
  96 It is possible to combine these methods, providing for long options
  97 processing with short option equivalents for some options.
  98 Less
  99 frequently used options would be processed as long options only.
 100 .Pp
 101 The
 102 .Fn getopt_long
 103 call requires a structure to be initialized describing the long
 104 options.
 105 The structure is:
 106 .Bd -literal -offset indent
 107 struct option {
 108         char *name;
 109         int has_arg;
 110         int *flag;
 111         int val;
 112 };
 113 .Ed
 114 .Pp
 115 The
 116 .Va name
 117 field should contain the option name without the leading double dash.
 118 .Pp
 119 The
 120 .Va has_arg
 121 field should be one of:
 122 .Pp
 123 .Bl -tag -width ".Dv optional_argument" -offset indent -compact
 124 .It Dv no_argument
 125 no argument to the option is expect
 126 .It Dv required_argument
 127 an argument to the option is required
 128 .It Li optional_argument
 129 an argument to the option may be presented.
 130 .El
 131 .Pp
 132 If
 133 .Va flag
 134 is not
 135 .Dv NULL ,
 136 then the integer pointed to by it will be set to the
 137 value in the
 138 .Va val
 139 field.
 140 If the
 141 .Va flag
 142 field is
 143 .Dv NULL ,
 144 then the
 145 .Va val
 146 field will be returned.
 147 Setting
 148 .Va flag
 149 to
 150 .Dv NULL
 151 and setting
 152 .Va val
 153 to the corresponding short option will make this function act just
 154 like
 155 .Xr getopt 3 .
 156 .Sh EXAMPLES
 157 .Bd -literal -compact
 158 extern char *optarg;
 159 extern int optind;
 160 int bflag, ch, fd;
 161 int daggerset;
 162
 163 /* options descriptor */
 164 static struct option longopts[] = {
 165         { "buffy",      no_argument,            0,              'b' },
 166         { "floride",    required_argument,      0,              'f' },
 167         { "daggerset",  no_argument,            \*[Am]daggerset,        1 },
 168         { 0,            0,                      0,              0 }
 169 };
 170
 171 bflag = 0;
 172 while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1)
 173         switch(ch) {
 174         case 'b':
 175                 bflag = 1;
 176                 break;
 177         case 'f':
 178                 if ((fd = open(optarg, O_RDONLY, 0)) \*[Lt] 0) {
 179                         (void)fprintf(stderr,
 180                             "myname: %s: %s\en", optarg, strerror(errno));
 181                         exit(1);
 182                 }
 183                 break;
 184         case 0:
 185                 if(daggerset) {
 186                         fprintf(stderr,"Buffy will use her dagger to "
 187                                        "apply floride to dracula's teeth\en");
 188                 }
 189                 break;
 190         case '?':
 191         default:
 192                 usage();
 193 }
 194 argc -= optind;
 195 argv += optind;
 196 .Ed
 197 .Sh IMPLEMENTATION DIFFERENCES
 198 This section describes differences to the
 199 .Tn GNU
 200 implementation
 201 found in glibc-2.1.3:
 202 .Bl -bullet
 203 .It
 204 Handling of
 205 .Ql -
 206 as first char of option string in presence of
 207 environment variable
 208 .Ev POSIXLY_CORRECT :
 209 .Bl -tag -width ".Nx"
 210 .It Tn GNU
 211 ignores
 212 .Ev POSIXLY_CORRECT
 213 and returns non-options as
 214 arguments to option '\e1'.
 215 .It Nx
 216 honors
 217 .Ev POSIXLY_CORRECT
 218 and stops at the first non-option.
 219 .El
 220 .It
 221 Handling of
 222 .Ql ::
 223 in options string in presence of
 224 .Ev POSIXLY_CORRECT :
 225 .Bl -tag -width ".Nx"
 226 .It Both
 227 .Tn GNU
 228 and
 229 .Nx
 230 ignore
 231 .Ev POSIXLY_CORRECT
 232 here and take
 233 .Ql ::
 234 to
 235 mean the preceding option takes an optional argument.
 236 .El
 237 .It
 238 Return value in case of missing argument if first character
 239 (after
 240 .Ql +
 241 or
 242 .Ql - )
 243 in option string is not
 244 .Ql \&: :
 245 .Bl -tag -width ".Nx"
 246 .It Tn GNU
 247 returns
 248 .Ql \&?
 249 .It Nx
 250 returns
 251 .Ql \&:
 252 (since
 253 .Nx Ns 's
 254 .Fn getopt
 255 does).
 256 .El
 257 .It
 258 Handling of
 259 .Ql --a
 260 in getopt:
 261 .Bl -tag -width ".Nx"
 262 .It Tn GNU
 263 parses this as option
 264 .Ql - ,
 265 option
 266 .Ql a .
 267 .It Nx
 268 parses this as
 269 .Ql -- ,
 270 and returns \-1 (ignoring the
 271 .Ql a ) .
 272 (Because the original
 273 .Fn getopt
 274 does.)
 275 .El
 276 .It
 277 Setting of
 278 .Va optopt
 279 for long options with
 280 .Va flag
 281 !=
 282 .Dv NULL :
 283 .Bl -tag -width ".Nx"
 284 .It Tn GNU
 285 sets
 286 .Va optopt
 287 to
 288 .Va val .
 289 .It Nx
 290 sets
 291 .Va optopt
 292 to 0 (since
 293 .Va val
 294 would never be returned).
 295 .El
 296 .It
 297 Handling of
 298 .Ql -W
 299 with
 300 .Ql W ;
 301 in option string in
 302 .Fn getopt
 303 (not
 304 .Fn getopt_long ) :
 305 .Bl -tag -width ".Nx"
 306 .It Tn GNU
 307 causes a segfault.
 308 .It Nx
 309 returns \-1, with
 310 .Va optind
 311 pointing past the argument of
 312 .Ql -W
 313 (as if
 314 .Ql "-W arg"
 315 were
 316 .Ql --arg ,
 317 and thus
 318 .Ql --
 319 had been found).
 320 .\" How should we treat W; in the option string when called via
 321 .\" getopt?  Ignore the ';' or treat it as a ':'? Issue a warning?
 322 .El
 323 .It
 324 Setting of
 325 .Va optarg
 326 for long options without an argument that are
 327 invoked via
 328 .Ql -W
 329 .Ql ( W ;
 330 in option string):
 331 .Bl -tag -width ".Nx"
 332 .It Tn GNU
 333 sets
 334 .Va optarg
 335 to the option name (the argument of
 336 .Ql -W ) .
 337 .It Nx
 338 sets
 339 .Va optarg
 340 to
 341 .Dv NULL
 342 (the argument of the long option).
 343 .El
 344 .It
 345 Handling of
 346 .Ql -W
 347 with an argument that is not (a prefix to) a known
 348 long option
 349 .Ql ( W ;
 350 in option string):
 351 .Bl -tag -width ".Nx"
 352 .It Tn GNU
 353 returns
 354 .Ql -W
 355 with
 356 .Va optarg
 357 set to the unknown option.
 358 .It Nx
 359 treats this as an error (unknown option) and returns
 360 .Ql \&?
 361 with
 362 .Va optopt
 363 set to 0 and
 364 .Va optarg
 365 set to
 366 .Dv NULL
 367 (as
 368 .Tn GNU Ns 's
 369 man page documents).
 370 .El
 371 .It
 372 The error messages are different.
 373 .It
 374 .Nx
 375 does not permute the argument vector at the same points in
 376 the calling sequence as
 377 .Tn GNU
 378 does.
 379 The aspects normally used by
 380 the caller (ordering after \-1 is returned, value of
 381 .Va optind
 382 relative
 383 to current positions) are the same, though.
 384 (We do fewer variable swaps.)
 385 .El
 386 .Sh SEE ALSO
 387 .Xr getopt 3
 388 .Sh HISTORY
 389 The
 390 .Fn getopt_long
 391 function first appeared in
 392 .Tn GNU
 393 libiberty.
 394 The first
 395 .Nx
 396 implementation appeared in 1.5.
 397 .Sh BUGS
 398 The implementation can completely replace
 399 .Xr getopt 3 ,
 400 but right now we are using separate code.