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