1.\" 2.\" Copyright (c) 1988, 1991, 1993 3.\" The Regents of the University of California. All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 3. Neither the name of the University nor the names of its contributors 14.\" may be used to endorse or promote products derived from this software 15.\" without specific prior written permission. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.\" 30.\" Copyright 2018 Jason King 31.\" Copyright 2018, Joyent, Inc. 32.\" 33.Dd July 17, 2018 34.Dt GETOPT_LONG 3C 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 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.Ft int 47.Fo getopt_long 48.Fa "int argc" 49.Fa "char * const *argv" 50.Fa "const char *optstring" 51.Fa "const struct option *longopts" 52.Fa "int *longindex" 53.Fc 54.Ft int 55.Fo getopt_long_only 56.Fa "int argc" 57.Fa "char * const *argv" 58.Fa "const char *optstring" 59.Fa "const struct option *longopts" 60.Fa "int *longindex" 61.Fc 62.Ft int 63.Fo getopt_long_clip 64.Fa "int argc" 65.Fa "char * const *argv" 66.Fa "const char *optstring" 67.Fa "const struct option *longopts" 68.Fa "int *longindex" 69.Fc 70.Sh DESCRIPTION 71The 72.Fn getopt_long 73function is similar to 74.Xr getopt 3C 75but it accepts options in two forms: words and characters. 76The 77.Fn getopt_long 78function provides a superset of the functionality of 79.Xr getopt 3C . 80The 81.Fn getopt_long 82function 83can be used in two ways. 84.Pp 85In the first way, every long option understood 86by the program has a corresponding short option, and the option 87structure is only used to translate from long options to short 88options. 89When used in this fashion, 90.Fn getopt_long 91behaves identically to 92.Xr getopt 3C . 93This is a good way to add long option processing to an existing program 94with the minimum of rewriting. 95.Pp 96In the second mechanism, a long option sets a flag in the 97.Vt option 98structure passed, or will store a pointer to the command line argument 99in the 100.Vt option 101structure passed to it for options that take arguments. 102Additionally, 103the long option's argument may be specified as a single argument with 104an equal sign, e.g., 105.Pp 106.Dl "myprogram --myoption=somevalue" 107.Pp 108When a long option is processed, the call to 109.Fn getopt_long 110will return 0. 111For this reason, long option processing without 112shortcuts is not backwards compatible with 113.Xr getopt 3C . 114.Pp 115It is possible to combine these methods, providing for long options 116processing with short option equivalents for some options. 117Less 118frequently used options would be processed as long options only. 119.Pp 120In 121.Fn getopt_long 122and 123.Fn getopt_long_only , 124.Fa optstring 125acts similar to 126.Fa optstring 127in 128.Xr getopt 3C . 129In addition, 130.Fa optstring 131can begin with 132.Ql + 133or 134.Ql - . 135If 136.Fa optstring 137begins with 138.Ql + , 139the first non-option terminates option processing. 140This is equivalent to setting the environment variable 141.Ev POSIXLY_CORRECT . 142If 143.Fa optstring 144begins with 145.Ql - , 146non-options are treated as options to the argument 147.Ql \e1 . 148.Pp 149If 150.Fa optstring 151does not begin with 152.Ql + 153and 154.Ev POSIXLY_CORRECT 155is not set, if 156.Ql W\&; 157appears in 158.Fa optstring , 159.Ql "-W myoption" 160is treated the same as 161.Ql "--myoption" 162and 163.Va optarg 164is set to 165.Ql myoption . 166.Pp 167In 168.Fn getopt_long_clip , 169.Ql + 170and 171.Ql - 172are ignored at the beginning of a string. 173.Pp 174The 175.Fn getopt_long , 176.Fn getopt_long_only , 177and 178.Fn getopt_long_clip 179functions require a structure to be initialized describing the long 180options. 181The structure is: 182.Bd -literal -offset indent 183struct option { 184 char *name; 185 int has_arg; 186 int *flag; 187 int val; 188}; 189.Ed 190.Pp 191The 192.Fa name 193field should contain the option name without the leading double dash. 194.Pp 195The 196.Fa has_arg 197field should be one of: 198.Pp 199.Bl -tag -width ".Dv optional_argument" -offset indent -compact 200.It Dv no_argument 201no argument to the option is expected 202.It Dv required_argument 203an argument to the option is required 204.It Dv optional_argument 205an argument to the option may be presented 206.El 207.Pp 208If 209.Fa flag 210is not 211.Dv NULL , 212then the integer pointed to by it will be set to the 213value in the 214.Fa val 215field and 216.Va optopt 217will be set to 218.Sy 0 . 219If the 220.Fa flag 221field is 222.Dv NULL , 223then the 224.Fa val 225field will be returned and 226.Va optopt 227is set to the value in the 228.Fa val 229field. 230Setting 231.Fa flag 232to 233.Dv NULL 234and setting 235.Fa val 236to the corresponding short option will make this function act just 237like 238.Xr getopt 3C . 239.Pp 240If the 241.Fa longindex 242field is not 243.Dv NULL , 244then the integer pointed to by it will be set to the index of the long 245option relative to 246.Fa longopts . 247.Pp 248The last element of the 249.Fa longopts 250array has to be filled with zeroes. 251.Pp 252The 253.Fn getopt_long_only 254function behaves identically to 255.Fn getopt_long 256with the exception that long options may start with 257.Ql - 258in addition to 259.Ql -- . 260If an option starting with 261.Ql - 262does not match a long option but does match a single-character option, 263the single-character option is returned. 264.Pp 265The 266.Fn getopt_long_clip 267function is a variation of 268.Fn getopt_long 269except that options must also adhere to the Sun CLIP specification. 270Specifically, the major differences from 271.Fn getopt_long 272are: 273.Bl -bullet -offset indent 274.It 275All option arguments are required 276.Po 277.Dv optional_argument 278is treated the same as 279.Dv required_argument 280.Pc . 281.It 282Long options cannot be abbreviated on the command line. 283.It 284Long options must use a double dash 285.Pq Ql -- . 286.It 287Option processing stops at the first non-option. 288.It 289All long options must have an eqivalent short option (single character) and 290vice-versa. 291.It 292A leading 293.Ql + 294or 295.Ql - 296in 297.Fa optstring 298is ignored. 299.Fa optstring 300is treated as if it began after the leading 301.Ql + 302or 303.Ql - . 304.El 305.Pp 306On each call to 307.Fn getopt_long , 308.Fn getopt_long_only , 309or 310.Fn getopt_long , 311.Va optind 312is set to the 313.Va argv 314index of the 315.Em next 316argument to be processed. 317.Va optind 318is initialized to 319.Sy 1 320prior to the first invocation of 321.Fn getopt_long , 322.Fn getopt_long_only , 323or 324.Fn getopt_long_clip . 325.Pp 326If 327.Va opterr 328is set to a non-zero value and 329.Fa optstring 330does not start with 331.Ql \&: , 332.Fn getopt_long , 333.Fn getopt_long_only , 334and 335.Fn getopt_long_clip 336will print an error message to 337.Sy stderr 338when an error or invalid option is encountered. 339.Sh RETURN VALUES 340If the 341.Fa flag 342field in 343.Vt "struct option" 344is 345.Dv NULL , 346.Fn getopt_long 347and 348.Fn getopt_long_only 349return the value specified in the 350.Fa val 351field, which is usually just the corresponding short option. 352If 353.Fa flag 354is not 355.Dv NULL , 356these functions return 0 and store 357.Fa val 358in the location pointed to by 359.Fa flag . 360These functions return 361.Ql \&: 362if there was a missing option argument, 363.Ql \&? 364if the user specified an unknown or ambiguous option, and 365\-1 when the argument list has been exhausted. 366.Pp 367If a long option to 368.Fn getopt_long_clip 369is missing its equivalent short option (or vice-versa),\-1 is returned on the 370first call to 371.Fn getopt_long_clip , 372and 373.Dv errno 374is set to 375.Er EINVAL . 376If 377.Va opterr 378is set to a non-zero value and 379.Fa optstring 380does not start with 381.Ql \&: , 382an error message will be written to 383.Sy stderr . 384.Pp 385If 386.Fa optstring 387does not start with 388.Ql \&: 389and 390.Fn getopt_long , 391.Fn getopt_long_only , 392or 393.Fn getopt_long_clip 394return 395.Ql \&: 396or 397.Ql \&? , 398if 399.Va opterr 400is set to a non-zero value, an error message is written to 401.Dv stderr . 402.Sh ENVIRONMENT 403The following environment variables can effect the execution of 404.Nm getopt_long , 405.Nm getopt_long_only , 406and 407.Nm getopt_long_clip : 408.Ev LANG , 409.Ev LC_ALL , 410.Ev LC_MESSAGES . 411See 412.Xr environ 5 . 413.Bl -tag -width ".Ev POSIXLY_CORRECT" 414.It Ev POSIXLY_CORRECT 415If set, option processing stops when the first non-option is found and 416a leading 417.Ql - 418or 419.Ql + 420in the 421.Fa optstring 422is ignored. 423.El 424.Sh USAGE 425Similar to 426.Xr getopt 3C , 427since there is no unambiguous way to detect a missing option-argument except when the 428option is the last option on the command line, the 429.Fn getopt_long , 430.Fn getopt_long_only , 431and 432.Fn getopt_long_clip 433functions cannot fully check for mandatory arguments. 434For example, the option string 435.Ql ho\&: 436with an input of 437.Ql Fl o Fl h 438will assume that 439.Ql Fl h 440is the required argument to 441.Fl o 442instead of assuming that 443.Fl o 444is missing its option-argument. 445.Pp 446Like 447.Xr getopt 3C , 448grouping options taking or requiring arguments with other options is a violation of the 449Basic Utility Command syntax standard (see 450.Xr Intro 1 ) . 451For example, given the option string 452.Ql cde\&: , 453running: 454.Pp 455.Dl cmd Fl cde Ar ieio 456.Pp 457is incorrect. 458Current versions of 459.Nm getopt_long , 460.Nm getopt_long_only , 461and 462.Nm getopt_long_clip 463accept this, however future versions may not support this. 464The correct invocation would be: 465.Pp 466.Dl cmd Fl cd Fl e Ar ieio 467.Sh EXAMPLES 468.Bd -literal -compact 469int bflag, ch, fd; 470int daggerset; 471 472/* options descriptor */ 473static struct option longopts[] = { 474 { "buffy", no_argument, NULL, 'b' }, 475 { "fluoride", required_argument, NULL, 'f' }, 476 { "daggerset", no_argument, \*[Am]daggerset, 1 }, 477 { NULL, 0, NULL, 0 } 478}; 479 480bflag = 0; 481while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1) { 482 switch (ch) { 483 case 'b': 484 bflag = 1; 485 break; 486 case 'f': 487 if ((fd = open(optarg, O_RDONLY, 0)) == -1) 488 err(1, "unable to open %s", optarg); 489 break; 490 case 0: 491 if (daggerset) { 492 fprintf(stderr,"Buffy will use her dagger to " 493 "apply fluoride to dracula's teeth\en"); 494 } 495 break; 496 default: 497 usage(); 498 } 499} 500argc -= optind; 501argv += optind; 502.Ed 503.Sh ERRORS 504The 505.Fn getopt_long_clip 506function will fail if: 507.Bl -tag -width EINVAL 508.It Er EINVAL 509A short option is missing a corresponding long option, or vice-versa. 510.El 511.Pp 512There are no errors defined for 513.Fn getopt_long 514and 515.Fn getopt_long_only . 516.Sh IMPLEMENTATION DIFFERENCES 517While the illumos implementations of 518.Nm getopt_long 519and 520.Nm getopt_long_only 521are broadly compatible with other implementations, the following edge cases 522have historically been known to vary among implementations: 523.Bl -bullet 524.It 525The setting of 526.Va optopt 527for long options with 528.Fa flag 529!= 530.Dv NULL 531in 532.Vt struct option . 533In illumos, 534.Va optopt 535is set to 0 (since 536.Fa val 537would never be returned). 538.It 539The setting of 540.Va optarg 541for long options without an argument that are 542invoked via 543.Ql -W 544.Ql ( W\&; 545in 546.Fa optstring ) . 547illumos sets 548.Va optarg 549to the option name (the argument of 550.Ql -W ) . 551.It 552The handling of 553.Ql -W 554with an argument that is not (a prefix to) a known 555long option 556.Ql ( W\&; 557in 558.Fa optstring ) . 559illumos treats this as an error (unknown option) and returns 560.Ql \&? 561with 562.Va optopt 563set to 0 and 564.Va optarg 565set to 566.Dv NULL . 567.It 568illumos 569may not permute the argument vector at the same points in 570the calling sequence as other implementations. 571The aspects normally used by 572the caller (ordering after \-1 is returned, the value of 573.Va optind 574relative 575to current positions) are the same, though. 576(We often do fewer variable swaps.) 577.El 578.Sh INTERFACE STABILITY 579Committed 580.Sh MT-LEVEL 581Unsafe 582.Sh SEE ALSO 583.Xr getopt 3C 584.Sh BUGS 585The 586.Fa argv 587argument is not really 588.Vt const 589as its elements may be permuted (unless 590.Ev POSIXLY_CORRECT 591is set). 592