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