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