lib/libc/stdlib/getopt_long.3

   1 .\"     $NetBSD: getopt_long.3,v 1.14 2003/08/07 16:43:40 agc Exp $
   2 .\"     $DragonFly: src/lib/libc/stdlib/getopt_long.3,v 1.7 2008/11/23 21:55:52 swildner 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 .\"
  33 .Dd March 14, 2007
  34 .Dt GETOPT_LONG 3
  35 .Os
  36 .Sh NAME
  37 .Nm getopt_long
  38 .Nd get long options from command line argument list
  39 .Sh LIBRARY
  40 .Lb libc
  41 .Sh SYNOPSIS
  42 .In getopt.h
  43 .Ft int
  44 .Fn getopt_long "int argc" "char * const *argv" "const char *optstring" "struct option *long_options" "int *index"
  45 .Fn getopt_long_only "int argc" "char * const *argv" "const char *optstring" "struct option *long_options" "int *index"
  46 .Sh DESCRIPTION
  47 The
  48 .Fn getopt_long
  49 function is similar to
  50 .Xr getopt 3
  51 but it accepts options in two forms: words and characters.
  52 The
  53 .Fn getopt_long
  54 function provides a superset of the functionality of
  55 .Xr getopt 3 .
  56 .Fn getopt_long
  57 can be used in two ways.
  58 In the first way, every long option understood by the program has a
  59 corresponding short option, and the option structure is only used to
  60 translate from long options to short options.
  61 When used in this fashion,
  62 .Fn getopt_long
  63 behaves identically to
  64 .Xr getopt 3 .
  65 This is a good way to add long option processing to an existing program
  66 with the minimum of rewriting.
  67 .Pp
  68 In the second mechanism, a long option sets a flag in the
  69 .Fa option
  70 structure passed, or will store a pointer to the command line argument
  71 in the
  72 .Fa option
  73 structure passed to it for options that take arguments.
  74 Additionally, the long option's argument may be specified as a single
  75 argument with an equal sign, e.g.
  76 .Bd -literal
  77 myprogram --myoption=somevalue
  78 .Ed
  79 .Pp
  80 When a long option is processed the call to
  81 .Fn getopt_long
  82 will return 0.
  83 For this reason, long option processing without
  84 shortcuts is not backwards compatible with
  85 .Xr getopt 3 .
  86 .Pp
  87 It is possible to combine these methods, providing for long options
  88 processing with short option equivalents for some options.
  89 Less frequently used options would be processed as long options only.
  90 .Pp
  91 The
  92 .Fn getopt_long
  93 call requires a structure to be initialized describing the long options.
  94 The structure is:
  95 .Bd -literal
  96 struct option {
  97         char *name;
  98         int has_arg;
  99         int *flag;
 100         int val;
 101 };
 102 .Ed
 103 .Pp
 104 The
 105 .Fa name
 106 field should contain the option name without the leading double dash.
 107 .Pp
 108 The
 109 .Fa has_arg
 110 field should be one of:
 111 .Bl -tag -width "optional_argument"
 112 .It Li no_argument
 113 no argument to the option is expect.
 114 .It Li required_argument
 115 an argument to the option is required.
 116 .It Li optional_argument
 117 an argument to the option may be presented.
 118 .El
 119 .Pp
 120 If
 121 .Fa flag
 122 is not
 123 .Dv NULL ,
 124 then the integer pointed to by it will be set to the value in the
 125 .Fa val
 126 field.
 127 If the
 128 .Fa flag
 129 field is
 130 .Dv NULL ,
 131 then the
 132 .Fa val
 133 field will be returned.
 134 Setting
 135 .Fa flag
 136 to
 137 .Dv NULL
 138 and setting
 139 .Fa val
 140 to the corresponding short option will make this function act just
 141 like
 142 .Xr getopt 3 .
 143 .Pp
 144 If the
 145 .Fa index
 146 field is not
 147 .Dv NULL ,
 148 the integer it points to will be set to the index of the long option
 149 in the
 150 .Fa long_options
 151 array.
 152 .Pp
 153 The last element of the
 154 .Fa long_options
 155 array has to be filled with zeroes (see
 156 .Sx EXAMPLES
 157 section).
 158 .Pp
 159 The
 160 .Fn getopt_long_only
 161 function behaves identically to
 162 .Fn getopt_long
 163 with the exception that long options may start with
 164 .Ql -
 165 in addition to
 166 .Ql -- .
 167 If an option starting with
 168 .Ql -
 169 does not match a long option but does match a single-character option,
 170 the single-character option is returned.
 171 Note that the
 172 .Fn getopt_long_only
 173 function is deprecated.
 174 New programs should use
 175 .Fn getopt_long .
 176 .Sh IMPLEMENTATION DIFFERENCES
 177 This section describes differences to the GNU implementation
 178 found in glibc-2.1.3:
 179 .Bl -tag -width "xxx"
 180 .It Li o
 181 handling of - as first char of option string in presence of
 182 environment variable POSIXLY_CORRECT:
 183 .Bl -tag -width "NetBSD"
 184 .It Li GNU
 185 ignores POSIXLY_CORRECT and returns non-options as
 186 arguments to option '\e1'.
 187 .It Li NetBSD
 188 honors POSIXLY_CORRECT and stops at the first non-option.
 189 .El
 190 .It Li o
 191 handling of :: in options string in presence of POSIXLY_CORRECT:
 192 .Bl -tag -width "NetBSD"
 193 .It Li Both
 194 GNU and
 195 .Nx
 196 ignore POSIXLY_CORRECT here and take :: to
 197 mean the preceding option takes an optional argument.
 198 .El
 199 .It Li o
 200 return value in case of missing argument if first character
 201 (after + or -) in option string is not ':':
 202 .Bl -tag -width "NetBSD"
 203 .It Li GNU
 204 returns '?'
 205 .It NetBSD
 206 returns ':' (since
 207 .Nx Ap s
 208 .Fn getopt
 209 does).
 210 .El
 211 .It Li o
 212 handling of --a in
 213 .Fn getopt :
 214 .Bl -tag -width "NetBSD"
 215 .It Li GNU
 216 parses this as option '-', option 'a'.
 217 .It Li NetBSD
 218 parses this as '--', and returns \-1 (ignoring the a).
 219 (Because the original
 220 .Fn getopt
 221 does.)
 222 .El
 223 .It Li o
 224 setting of optopt for long options with flag !=
 225 .Dv NULL :
 226 .Bl -tag -width "NetBSD"
 227 .It Li GNU
 228 sets optopt to val.
 229 .It Li NetBSD
 230 sets optopt to 0 (since val would never be returned).
 231 .El
 232 .It Li o
 233 handling of -W with W; in option string in
 234 .Fn getopt
 235 (not
 236 .Fn getopt_long ) :
 237 .Bl -tag -width "NetBSD"
 238 .It Li GNU
 239 causes a segfault.
 240 .It Li NetBSD
 241 returns \-1, with optind pointing past the argument of -W
 242 (as if `-W arg' were `--arg', and thus '--' had been found).
 243 .\" How should we treat W; in the option string when called via
 244 .\" getopt?  Ignore the ';' or treat it as a ':'? Issue a warning?
 245 .El
 246 .It Li o
 247 setting of optarg for long options without an argument that are
 248 invoked via -W (W; in option string):
 249 .Bl -tag -width "NetBSD"
 250 .It Li GNU
 251 sets optarg to the option name (the argument of -W).
 252 .It Li NetBSD
 253 sets optarg to
 254 .Dv NULL
 255 (the argument of the long option).
 256 .El
 257 .It Li o
 258 handling of -W with an argument that is not (a prefix to) a known
 259 long option (W; in option string):
 260 .Bl -tag -width "NetBSD"
 261 .It Li GNU
 262 returns -W with optarg set to the unknown option.
 263 .It Li NetBSD
 264 treats this as an error (unknown option) and returns '?' with
 265 optopt set to 0 and optarg set to
 266 .Dv NULL
 267 (as GNU's man page documents).
 268 .El
 269 .It Li o
 270 The error messages are different.
 271 .It Li o
 272 .Nx
 273 does not permute the argument vector at the same points in
 274 the calling sequence as GNU does.
 275 The aspects normally used by the caller
 276 (ordering after \-1 is returned, value of optind relative
 277 to current positions) are the same, though.
 278 (We do fewer variable swaps.)
 279 .El
 280 .Sh EXAMPLES
 281 .Bd -literal -compact
 282 extern char *optarg;
 283 extern int optind;
 284 int bflag, ch, fd;
 285 int daggerset;
 286
 287 /* options descriptor */
 288 static struct option longopts[] = {
 289         { "buffy",      no_argument,            0,              'b' },
 290         { "fluoride",   required_argument,      0,              'f' },
 291         { "daggerset",  no_argument,            \*[Am]daggerset,        1 },
 292         { NULL,         0,                      NULL,           0 }
 293 };
 294
 295 bflag = 0;
 296 while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1)
 297         switch (ch) {
 298         case 'b':
 299                 bflag = 1;
 300                 break;
 301         case 'f':
 302                 if ((fd = open(optarg, O_RDONLY, 0)) \*[Lt] 0) {
 303                         (void)fprintf(stderr,
 304                             "myname: %s: %s\en", optarg, strerror(errno));
 305                         exit(1);
 306                 }
 307                 break;
 308         case 0:
 309                 if(daggerset) {
 310                         fprintf(stderr,"Buffy will use her dagger to "
 311                                        "apply fluoride to dracula's teeth\en");
 312                 }
 313                 break;
 314         case '?':
 315         default:
 316                 usage();
 317 }
 318 argc -= optind;
 319 argv += optind;
 320 .Ed
 321 .Sh SEE ALSO
 322 .Xr getopt 3
 323 .Sh HISTORY
 324 The
 325 .Fn getopt_long
 326 function first appeared in GNU libiberty.
 327 The first
 328 .Nx
 329 implementation appeared in 1.5.