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.6 2007/05/12 21:22:10 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 getopt does).
 209 .El
 210 .It Li o
 211 handling of --a in getopt:
 212 .Bl -tag -width "NetBSD"
 213 .It Li GNU
 214 parses this as option '-', option 'a'.
 215 .It Li NetBSD
 216 parses this as '--', and returns \-1 (ignoring the a).
 217 (Because the original getopt does.)
 218 .El
 219 .It Li o
 220 setting of optopt for long options with flag !=
 221 .Dv NULL :
 222 .Bl -tag -width "NetBSD"
 223 .It Li GNU
 224 sets optopt to val.
 225 .It Li NetBSD
 226 sets optopt to 0 (since val would never be returned).
 227 .El
 228 .It Li o
 229 handling of -W with W; in option string in getopt (not getopt_long):
 230 .Bl -tag -width "NetBSD"
 231 .It Li GNU
 232 causes a segfault.
 233 .It Li NetBSD
 234 returns \-1, with optind pointing past the argument of -W
 235 (as if `-W arg' were `--arg', and thus '--' had been found).
 236 .\" How should we treat W; in the option string when called via
 237 .\" getopt?  Ignore the ';' or treat it as a ':'? Issue a warning?
 238 .El
 239 .It Li o
 240 setting of optarg for long options without an argument that are
 241 invoked via -W (W; in option string):
 242 .Bl -tag -width "NetBSD"
 243 .It Li GNU
 244 sets optarg to the option name (the argument of -W).
 245 .It Li NetBSD
 246 sets optarg to
 247 .Dv NULL
 248 (the argument of the long option).
 249 .El
 250 .It Li o
 251 handling of -W with an argument that is not (a prefix to) a known
 252 long option (W; in option string):
 253 .Bl -tag -width "NetBSD"
 254 .It Li GNU
 255 returns -W with optarg set to the unknown option.
 256 .It Li NetBSD
 257 treats this as an error (unknown option) and returns '?' with
 258 optopt set to 0 and optarg set to
 259 .Dv NULL
 260 (as GNU's man page documents).
 261 .El
 262 .It Li o
 263 The error messages are different.
 264 .It Li o
 265 .Nx
 266 does not permute the argument vector at the same points in
 267 the calling sequence as GNU does.
 268 The aspects normally used by the caller
 269 (ordering after \-1 is returned, value of optind relative
 270 to current positions) are the same, though.
 271 (We do fewer variable swaps.)
 272 .El
 273 .Sh EXAMPLES
 274 .Bd -literal -compact
 275 extern char *optarg;
 276 extern int optind;
 277 int bflag, ch, fd;
 278 int daggerset;
 279
 280 /* options descriptor */
 281 static struct option longopts[] = {
 282         { "buffy",      no_argument,            0,              'b' },
 283         { "fluoride",   required_argument,      0,              'f' },
 284         { "daggerset",  no_argument,            \*[Am]daggerset,        1 },
 285         { NULL,         0,                      NULL,           0 }
 286 };
 287
 288 bflag = 0;
 289 while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1)
 290         switch (ch) {
 291         case 'b':
 292                 bflag = 1;
 293                 break;
 294         case 'f':
 295                 if ((fd = open(optarg, O_RDONLY, 0)) \*[Lt] 0) {
 296                         (void)fprintf(stderr,
 297                             "myname: %s: %s\en", optarg, strerror(errno));
 298                         exit(1);
 299                 }
 300                 break;
 301         case 0:
 302                 if(daggerset) {
 303                         fprintf(stderr,"Buffy will use her dagger to "
 304                                        "apply fluoride to dracula's teeth\en");
 305                 }
 306                 break;
 307         case '?':
 308         default:
 309                 usage();
 310 }
 311 argc -= optind;
 312 argv += optind;
 313 .Ed
 314 .Sh SEE ALSO
 315 .Xr getopt 3
 316 .Sh HISTORY
 317 The
 318 .Fn getopt_long
 319 function first appeared in GNU libiberty.
 320 The first
 321 .Nx
 322 implementation appeared in 1.5.