1.\" $OpenBSD: getopt_long.3,v 1.25 2022/09/11 06:38:11 jmc Exp $ 2.\" $NetBSD: getopt_long.3,v 1.11 2002/10/02 10:54:19 wiz 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 $Mdocdate: September 11 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 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.Fn getopt_long "int argc" "char * const *argv" "const char *optstring" "const struct option *longopts" "int *longindex" 49.Ft int 50.Fn getopt_long_only "int argc" "char * const *argv" "const char *optstring" "const struct option *longopts" "int *longindex" 51.Sh DESCRIPTION 52The 53.Fn getopt_long 54function is similar to 55.Xr getopt 3 56but it accepts options in two forms: words and characters. 57The 58.Fn getopt_long 59function provides a superset of the functionality of 60.Xr getopt 3 . 61.Fn getopt_long 62can be used in two ways. 63In the first way, every long option understood by the program has a 64corresponding short option, and the option structure is only used to 65translate from long options to short options. 66When used in this fashion, 67.Fn getopt_long 68behaves identically to 69.Xr getopt 3 . 70This is a good way to add long option processing to an existing program 71with the minimum of rewriting. 72.Pp 73In the second mechanism, a long option sets a flag in the 74.Fa option 75structure passed, or will store a pointer to the command line argument 76in the 77.Fa option 78structure passed to it for options that take arguments. 79Additionally, the long option's argument may be specified as a single 80argument with an equal sign, e.g. 81.Bd -literal -offset indent 82$ myprogram --myoption=somevalue 83.Ed 84.Pp 85When a long option is processed, the call to 86.Fn getopt_long 87will return 0. 88For this reason, long option processing without 89shortcuts is not backwards compatible with 90.Xr getopt 3 . 91.Pp 92It is possible to combine these methods, providing for long options 93processing with short option equivalents for some options. 94Less frequently used options would be processed as long options only. 95.Pp 96Abbreviated long option names are accepted when 97.Fn getopt_long 98processes long options if the abbreviation is unique. 99An exact match is always preferred for a defined long option. 100.Pp 101By default, 102.Fn getopt_long 103permutes 104.Ar argv 105such that all option arguments are evaluated before any non-options arguments. 106If the first character of 107.Fa optstring 108is a plus sign 109.Pq Ql + 110or if the environment variable 111.Ev POSIXLY_CORRECT 112is set, then 113.Ar argv 114is processed in order and option processing stops as soon as the first 115non-option argument is encountered. 116.Pp 117The 118.Fn getopt_long 119call requires an array to be initialized describing the long 120options. 121Each element of the array is a structure: 122.Bd -literal -offset indent 123struct option { 124 char *name; 125 int has_arg; 126 int *flag; 127 int val; 128}; 129.Ed 130.Pp 131The 132.Fa name 133field should contain the option name without the leading double dash. 134.Pp 135The 136.Fa has_arg 137field should be one of: 138.Pp 139.Bl -tag -width "optional_argument" -compact -offset indent 140.It Dv no_argument 141no argument to the option is expected. 142.It Dv required_argument 143an argument to the option is required. 144.It Dv optional_argument 145an argument to the option may be presented. 146.El 147.Pp 148If 149.Fa flag 150is not 151.Dv NULL , 152then the integer pointed to by it will be set to the value in the 153.Fa val 154field. 155If the 156.Fa flag 157field is 158.Dv NULL , 159then the 160.Fa val 161field will be returned. 162Setting 163.Fa flag 164to 165.Dv NULL 166and setting 167.Fa val 168to the corresponding short option will make this function act just 169like 170.Xr getopt 3 . 171.Pp 172If the 173.Fa longindex 174argument is not 175.Dv NULL , 176then the integer pointed to by it will be set to the index of the long 177option relative to 178.Fa longopts . 179.Pp 180The last element of the 181.Fa longopts 182array has to be filled with zeroes. 183.Pp 184The 185.Fn getopt_long_only 186function behaves identically to 187.Fn getopt_long 188with the exception that long options may start with 189.Sq - 190in addition to 191.Sq -- . 192If an option starting with 193.Sq - 194does not match a long option but does match a single-character option, 195the single-character option is returned. 196.Sh RETURN VALUES 197If the 198.Fa flag 199field in 200.Vt struct option 201is 202.Dv NULL , 203.Fn getopt_long 204and 205.Fn getopt_long_only 206return the value specified in the 207.Fa val 208field, which is usually just the corresponding short option. 209If 210.Fa flag 211is not 212.Dv NULL , 213these functions return 0 and store 214.Fa val 215in the location pointed to by 216.Fa flag . 217These functions return 218.Sq \&: 219if there was a missing option argument, 220.Sq \&? 221if the user specified an unknown or ambiguous option, and 222\-1 when the argument list has been exhausted. 223.Sh IMPLEMENTATION DIFFERENCES 224This section describes differences to the GNU implementation 225found in glibc-2.1.3: 226.Bl -bullet 227.It 228handling of 229.Ql - 230within the option string (not the first character): 231.Bl -tag -width "OpenBSD" 232.It GNU 233treats a 234.Ql - 235on the command line as a non-argument. 236.It OpenBSD 237a 238.Ql - 239within the option string matches a 240.Ql - 241(single dash) on the command line. 242This functionality is provided for backward compatibility with 243programs, such as 244.Xr su 1 , 245that use 246.Ql - 247as an option flag. 248This practice is wrong, and should not be used in any current development. 249.El 250.It 251handling of 252.Ql :: 253in the option string in the presence of 254.Ev POSIXLY_CORRECT : 255.Bl -tag -width "OpenBSD" 256.It Both 257GNU and 258.Ox 259ignore 260.Ev POSIXLY_CORRECT 261here and take 262.Ql :: 263to mean the preceding option takes an optional argument. 264.El 265.It 266return value in case of missing argument if first character 267(after 268.Ql + 269or 270.Ql - ) 271in the option string is not 272.Ql \&: : 273.Bl -tag -width "OpenBSD" 274.It GNU 275returns 276.Ql \&? 277.It OpenBSD 278returns 279.Ql \&: 280(since 281.Ox Ns 's 282.Xr getopt 3 283does). 284.El 285.It 286handling of 287.Ql --a 288in 289.Xr getopt 3 : 290.Bl -tag -width "OpenBSD" 291.It GNU 292parses this as option 293.Ql - , 294option 295.Ql a . 296.It OpenBSD 297parses this as 298.Ql -- , 299and returns \-1 (ignoring the 300.Ql a ) 301(because the original 302.Fn getopt 303did.) 304.El 305.It 306setting of 307.Va optopt 308for long options with 309.Va flag 310.No non- Ns Dv NULL : 311.Bl -tag -width "OpenBSD" 312.It GNU 313sets 314.Va optopt 315to 316.Va val . 317.It OpenBSD 318sets 319.Va optopt 320to 0 (since 321.Va val 322would never be returned). 323.El 324.It 325handling of 326.Ql -W 327with 328.Ql W; 329in the option string in 330.Xr getopt 3 331(not 332.Fn getopt_long ) : 333.Bl -tag -width "OpenBSD" 334.It GNU 335causes a segmentation fault. 336.It OpenBSD 337no special handling is done; 338.Ql W; 339is interpreted as two separate options, neither of which take an argument. 340.El 341.It 342setting of 343.Va optarg 344for long options without an argument that are invoked via 345.Ql -W 346(with 347.Ql W; 348in the option string): 349.Bl -tag -width "OpenBSD" 350.It GNU 351sets 352.Va optarg 353to the option name (the argument of 354.Ql -W ) . 355.It OpenBSD 356sets 357.Va optarg 358to 359.Dv NULL 360(the argument of the long option). 361.El 362.It 363handling of 364.Ql -W 365with an argument that is not (a prefix to) a known long option 366(with 367.Ql W; 368in the option string): 369.Bl -tag -width "OpenBSD" 370.It GNU 371returns 372.Ql -W 373with 374.Va optarg 375set to the unknown option. 376.It OpenBSD 377treats this as an error (unknown option) and returns 378.Ql \&? 379with 380.Va optopt 381set to 0 and 382.Va optarg 383set to 384.Dv NULL 385(as GNU's man page documents). 386.El 387.It 388The error messages are different. 389.It 390.Ox 391does not permute the argument vector at the same points in 392the calling sequence as GNU does. 393The aspects normally used by the caller 394(ordering after \-1 is returned, value of 395.Va optind 396relative to current positions) are the same, though. 397(We do fewer variable swaps.) 398.El 399.Sh ENVIRONMENT 400.Bl -tag -width Ev 401.It Ev POSIXLY_CORRECT 402If set, option processing stops when the first non-option is found and 403a leading 404.Sq + 405in the 406.Ar optstring 407is ignored. 408.El 409.Sh EXAMPLES 410.Bd -literal 411int bflag, ch, fd; 412int daggerset; 413 414/* options descriptor */ 415static struct option longopts[] = { 416 { "buffy", no_argument, NULL, 'b' }, 417 { "fluoride", required_argument, NULL, 'f' }, 418 { "daggerset", no_argument, &daggerset, 1 }, 419 { NULL, 0, NULL, 0 } 420}; 421 422bflag = 0; 423while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1) 424 switch (ch) { 425 case 'b': 426 bflag = 1; 427 break; 428 case 'f': 429 if ((fd = open(optarg, O_RDONLY)) == -1) 430 err(1, "unable to open %s", optarg); 431 break; 432 case 0: 433 if (daggerset) 434 fprintf(stderr, "Buffy will use her dagger to " 435 "apply fluoride to dracula's teeth\en"); 436 break; 437 default: 438 usage(); 439 } 440argc -= optind; 441argv += optind; 442.Ed 443.Sh SEE ALSO 444.Xr getopt 3 445.Sh HISTORY 446The 447.Fn getopt_long 448and 449.Fn getopt_long_only 450functions first appeared in GNU libiberty. 451This implementation first appeared in 452.Ox 3.3 . 453.Sh BUGS 454The 455.Ar argv 456argument is not really 457.Dv const 458as its elements may be permuted (unless 459.Ev POSIXLY_CORRECT 460is set). 461