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.Dd December 24, 2022 32.Dt GETOPT_LONG 3 33.Os 34.Sh NAME 35.Nm getopt_long , 36.Nm getopt_long_only 37.Nd get long options from command line argument list 38.Sh LIBRARY 39.Lb libc 40.Sh SYNOPSIS 41.In getopt.h 42.Vt extern char *optarg ; 43.Vt extern int optind ; 44.Vt extern int optopt ; 45.Vt extern int opterr ; 46.Vt extern int optreset ; 47.Ft int 48.Fo getopt_long 49.Fa "int argc" "char * const *argv" "const char *optstring" 50.Fa "const struct option *longopts" "int *longindex" 51.Fc 52.Ft int 53.Fo getopt_long_only 54.Fa "int argc" "char * const *argv" "const char *optstring" 55.Fa "const struct option *longopts" "int *longindex" 56.Fc 57.Sh DESCRIPTION 58The 59.Fn getopt_long 60function is similar to 61.Xr getopt 3 62but it accepts options in two forms: words and characters. 63The 64.Fn getopt_long 65function provides a superset of the functionality of 66.Xr getopt 3 . 67The 68.Fn getopt_long 69function 70can be used in two ways. 71In the first way, every long option understood 72by the program has a corresponding short option, and the option 73structure is only used to translate from long options to short 74options. 75When used in this fashion, 76.Fn getopt_long 77behaves identically to 78.Xr getopt 3 . 79This is a good way to add long option processing to an existing program 80with the minimum of rewriting. 81.Pp 82In the second mechanism, a long option sets a flag in the 83.Vt option 84structure passed, or will store a pointer to the command line argument 85in the 86.Vt option 87structure passed to it for options that take arguments. 88Additionally, 89the long option's argument may be specified as a single argument with 90an equal sign, e.g., 91.Pp 92.Dl "myprogram --myoption=somevalue" 93.Pp 94When a long option is processed, the call to 95.Fn getopt_long 96will return 0. 97For this reason, long option processing without 98shortcuts is not backwards compatible with 99.Xr getopt 3 . 100.Pp 101It is possible to combine these methods, providing for long options 102processing with short option equivalents for some options. 103Less 104frequently used options would be processed as long options only. 105.Pp 106The 107.Fn getopt_long 108call requires a structure to be initialized describing the long 109options. 110The structure is: 111.Bd -literal -offset indent 112struct option { 113 char *name; 114 int has_arg; 115 int *flag; 116 int val; 117}; 118.Ed 119.Pp 120The 121.Va name 122field should contain the option name without the leading double dash. 123.Pp 124The 125.Va has_arg 126field should be one of: 127.Pp 128.Bl -tag -width ".Dv optional_argument" -offset indent -compact 129.It Dv no_argument 130no argument to the option is expected 131.It Dv required_argument 132an argument to the option is required 133.It Dv optional_argument 134an argument to the option may be presented 135.El 136.Pp 137If 138.Va flag 139is not 140.Dv NULL , 141then the integer pointed to by it will be set to the 142value in the 143.Va val 144field. 145If the 146.Va flag 147field is 148.Dv NULL , 149then the 150.Va val 151field will be returned. 152Setting 153.Va flag 154to 155.Dv NULL 156and setting 157.Va val 158to the corresponding short option will make this function act just 159like 160.Xr getopt 3 . 161.Pp 162If the 163.Fa longindex 164field is not 165.Dv NULL , 166then the integer pointed to by it will be set to the index of the long 167option relative to 168.Fa longopts . 169.Pp 170The last element of the 171.Fa longopts 172array has to be filled with zeroes. 173.Pp 174The 175.Fn getopt_long_only 176function behaves identically to 177.Fn getopt_long 178with the exception that long options may start with 179.Ql - 180in addition to 181.Ql -- . 182If an option starting with 183.Ql - 184does not match a long option but does match a single-character option, 185the single-character option is returned. 186.Sh RETURN VALUES 187If the 188.Fa flag 189field in 190.Vt "struct option" 191is 192.Dv NULL , 193.Fn getopt_long 194and 195.Fn getopt_long_only 196return the value specified in the 197.Fa val 198field, which is usually just the corresponding short option. 199If 200.Fa flag 201is not 202.Dv NULL , 203these functions return 0 and store 204.Fa val 205in the location pointed to by 206.Fa flag . 207.Pp 208These functions return 209.Ql \&: 210if there was a missing option argument and error messages are suppressed, 211.Ql \&? 212if the user specified an unknown or ambiguous option, and 213\-1 when the argument list has been exhausted. 214The default behavior when a missing option argument is encountered is to write 215an error and return 216.Ql \&? . 217Specifying 218.Ql \&: 219in 220.Fa optstr 221will cause the error message to be suppressed and 222.Ql \&: 223to be returned instead. 224.Pp 225In addition to 226.Ql \&: , 227a leading 228.Ql \&+ 229or 230.Ql \&- 231in 232.Fa optstr 233also has special meaning. 234If either of these are specified, they must appear before 235.Ql \&: . 236.Pp 237A leading 238.Ql \&+ 239indicates that processing should be halted at the first non-option argument, 240matching the default behavior of 241.Xr getopt 3 . 242The default behavior without 243.Ql \&+ 244is to permute non-option arguments to the end of 245.Fa argv . 246.Pp 247A leading 248.Ql \&- 249indicates that all non-option arguments should be treated as if they are 250arguments to a literal 251.Ql \&1 252flag (i.e., the function call will return the value 1, rather than the char 253literal '1'). 254.Sh ENVIRONMENT 255.Bl -tag -width ".Ev POSIXLY_CORRECT" 256.It Ev POSIXLY_CORRECT 257If set, option processing stops when the first non-option is found and 258a leading 259.Ql - 260or 261.Ql + 262in the 263.Fa optstring 264is ignored. 265.El 266.Sh EXAMPLES 267.Bd -literal -compact 268int bflag, ch, fd; 269int daggerset; 270 271/* options descriptor */ 272static struct option longopts[] = { 273 { "buffy", no_argument, NULL, 'b' }, 274 { "fluoride", required_argument, NULL, 'f' }, 275 { "daggerset", no_argument, \*[Am]daggerset, 1 }, 276 { NULL, 0, NULL, 0 } 277}; 278 279bflag = 0; 280while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1) { 281 switch (ch) { 282 case 'b': 283 bflag = 1; 284 break; 285 case 'f': 286 if ((fd = open(optarg, O_RDONLY, 0)) == -1) 287 err(1, "unable to open %s", optarg); 288 break; 289 case 0: 290 if (daggerset) { 291 fprintf(stderr,"Buffy will use her dagger to " 292 "apply fluoride to dracula's teeth\en"); 293 } 294 break; 295 default: 296 usage(); 297 } 298} 299argc -= optind; 300argv += optind; 301.Ed 302.Sh IMPLEMENTATION DIFFERENCES 303This section describes differences to the 304.Tn GNU 305implementation 306found in glibc-2.1.3: 307.Bl -bullet 308.\" .It 309.\" Handling of 310.\" .Ql - 311.\" as first char of option string in presence of 312.\" environment variable 313.\" .Ev POSIXLY_CORRECT : 314.\" .Bl -tag -width ".Bx" 315.\" .It Tn GNU 316.\" ignores 317.\" .Ev POSIXLY_CORRECT 318.\" and returns non-options as 319.\" arguments to option '\e1'. 320.\" .It Bx 321.\" honors 322.\" .Ev POSIXLY_CORRECT 323.\" and stops at the first non-option. 324.\" .El 325.\" .It 326.\" Handling of 327.\" .Ql - 328.\" within the option string (not the first character): 329.\" .Bl -tag -width ".Bx" 330.\" .It Tn GNU 331.\" treats a 332.\" .Ql - 333.\" on the command line as a non-argument. 334.\" .It Bx 335.\" a 336.\" .Ql - 337.\" within the option string matches a 338.\" .Ql - 339.\" (single dash) on the command line. 340.\" This functionality is provided for backward compatibility with 341.\" programs, such as 342.\" .Xr su 1 , 343.\" that use 344.\" .Ql - 345.\" as an option flag. 346.\" This practice is wrong, and should not be used in any current development. 347.\" .El 348.\" .It 349.\" Handling of 350.\" .Ql :: 351.\" in options string in presence of 352.\" .Ev POSIXLY_CORRECT : 353.\" .Bl -tag -width ".Bx" 354.\" .It Both 355.\" .Tn GNU 356.\" and 357.\" .Bx 358.\" ignore 359.\" .Ev POSIXLY_CORRECT 360.\" here and take 361.\" .Ql :: 362.\" to 363.\" mean the preceding option takes an optional argument. 364.\" .El 365.\" .It 366.\" Return value in case of missing argument if first character 367.\" (after 368.\" .Ql + 369.\" or 370.\" .Ql - ) 371.\" in option string is not 372.\" .Ql \&: : 373.\" .Bl -tag -width ".Bx" 374.\" .It Tn GNU 375.\" returns 376.\" .Ql \&? 377.\" .It Bx 378.\" returns 379.\" .Ql \&: 380.\" (since 381.\" .Bx Ns 's 382.\" .Fn getopt 383.\" does). 384.\" .El 385.\" .It 386.\" Handling of 387.\" .Ql --a 388.\" in getopt: 389.\" .Bl -tag -width ".Bx" 390.\" .It Tn GNU 391.\" parses this as option 392.\" .Ql - , 393.\" option 394.\" .Ql a . 395.\" .It Bx 396.\" parses this as 397.\" .Ql -- , 398.\" and returns \-1 (ignoring the 399.\" .Ql a ) . 400.\" (Because the original 401.\" .Fn getopt 402.\" does.) 403.\" .El 404.It 405Setting of 406.Va optopt 407for long options with 408.Va flag 409!= 410.Dv NULL : 411.Bl -tag -width ".Bx" 412.It Tn GNU 413sets 414.Va optopt 415to 416.Va val . 417.It Bx 418sets 419.Va optopt 420to 0 (since 421.Va val 422would never be returned). 423.El 424.\" .It 425.\" Handling of 426.\" .Ql -W 427.\" with 428.\" .Ql W; 429.\" in option string in 430.\" .Fn getopt 431.\" (not 432.\" .Fn getopt_long ) : 433.\" .Bl -tag -width ".Bx" 434.\" .It Tn GNU 435.\" causes a segfault. 436.\" .It Bx 437.\" no special handling is done; 438.\" .Ql W; 439.\" is interpreted as two separate options, neither of which take an argument. 440.\" .El 441.It 442Setting of 443.Va optarg 444for long options without an argument that are 445invoked via 446.Ql -W 447.Ql ( W; 448in option string): 449.Bl -tag -width ".Bx" 450.It Tn GNU 451sets 452.Va optarg 453to the option name (the argument of 454.Ql -W ) . 455.It Bx 456sets 457.Va optarg 458to 459.Dv NULL 460(the argument of the long option). 461.El 462.It 463Handling of 464.Ql -W 465with an argument that is not (a prefix to) a known 466long option 467.Ql ( W; 468in option string): 469.Bl -tag -width ".Bx" 470.It Tn GNU 471returns 472.Ql -W 473with 474.Va optarg 475set to the unknown option. 476.It Bx 477treats this as an error (unknown option) and returns 478.Ql \&? 479with 480.Va optopt 481set to 0 and 482.Va optarg 483set to 484.Dv NULL 485(as 486.Tn GNU Ns 's 487man page documents). 488.El 489.\" .It 490.\" The error messages are different. 491.It 492.Bx 493does not permute the argument vector at the same points in 494the calling sequence as 495.Tn GNU 496does. 497The aspects normally used by 498the caller (ordering after \-1 is returned, value of 499.Va optind 500relative 501to current positions) are the same, though. 502(We do fewer variable swaps.) 503.El 504.Sh SEE ALSO 505.Xr getopt 3 506.Sh HISTORY 507The 508.Fn getopt_long 509and 510.Fn getopt_long_only 511functions first appeared in the 512.Tn GNU 513libiberty library. 514The first 515.Bx 516implementation of 517.Fn getopt_long 518appeared in 519.Nx 1.5 , 520the first 521.Bx 522implementation of 523.Fn getopt_long_only 524in 525.Ox 3.3 . 526.Fx 527first included 528.Fn getopt_long 529in 530.Fx 5.0 , 531.Fn getopt_long_only 532in 533.Fx 5.2 . 534.Sh BUGS 535The 536.Fa argv 537argument is not really 538.Vt const 539as its elements may be permuted (unless 540.Ev POSIXLY_CORRECT 541is set). 542.Pp 543The implementation can completely replace 544.Xr getopt 3 , 545but right now we are using separate code. 546.Pp 547.Nm 548makes the assumption that the first argument should always be skipped because 549it's typically the program name. 550As a result, setting 551.Va optind 552to 0 will indicate that 553.Nm 554should reset, and 555.Va optind 556will be set to 1 in the process. 557This behavior differs from 558.Xr getopt 3 , 559which will handle an 560.Va optind 561value of 0 as expected and process the first element. 562