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