1.\" $OpenBSD: getopt_long.3,v 1.19 2011/03/21 13:41:50 espie 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: March 21 2011 $ 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.Fd #include <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 101The 102.Fn getopt_long 103call requires an array to be initialized describing the long 104options. 105Each element of the array is a structure: 106.Bd -literal -offset indent 107struct option { 108 char *name; 109 int has_arg; 110 int *flag; 111 int val; 112}; 113.Ed 114.Pp 115The 116.Fa name 117field should contain the option name without the leading double dash. 118.Pp 119The 120.Fa has_arg 121field should be one of: 122.Pp 123.Bl -tag -width "optional_argument" -compact -offset indent 124.It Dv no_argument 125no argument to the option is expected. 126.It Dv required_argument 127an argument to the option is required. 128.It Dv optional_argument 129an argument to the option may be presented. 130.El 131.Pp 132If 133.Fa flag 134is not 135.Dv NULL , 136then the integer pointed to by it will be set to the value in the 137.Fa val 138field. 139If the 140.Fa flag 141field is 142.Dv NULL , 143then the 144.Fa val 145field will be returned. 146Setting 147.Fa flag 148to 149.Dv NULL 150and setting 151.Fa val 152to the corresponding short option will make this function act just 153like 154.Xr getopt 3 . 155.Pp 156If the 157.Fa longindex 158field is not 159.Dv NULL , 160then the integer pointed to by it will be set to the index of the long 161option relative to 162.Fa longopts . 163.Pp 164The last element of the 165.Fa longopts 166array has to be filled with zeroes. 167.Pp 168The 169.Fn getopt_long_only 170function behaves identically to 171.Fn getopt_long 172with the exception that long options may start with 173.Sq - 174in addition to 175.Sq -- . 176If an option starting with 177.Sq - 178does not match a long option but does match a single-character option, 179the single-character option is returned. 180.Sh RETURN VALUES 181If the 182.Fa flag 183field in 184.Li struct option 185is 186.Dv NULL , 187.Fn getopt_long 188and 189.Fn getopt_long_only 190return the value specified in the 191.Fa val 192field, which is usually just the corresponding short option. 193If 194.Fa flag 195is not 196.Dv NULL , 197these functions return 0 and store 198.Fa val 199in the location pointed to by 200.Fa flag . 201These functions return 202.Sq \&: 203if there was a missing option argument, 204.Sq \&? 205if the user specified an unknown or ambiguous option, and 206\-1 when the argument list has been exhausted. 207.Sh IMPLEMENTATION DIFFERENCES 208This section describes differences to the GNU implementation 209found in glibc-2.1.3: 210.Bl -bullet 211.It 212handling of 213.Ql - 214within the option string (not the first character): 215.Bl -tag -width "OpenBSD" 216.It GNU 217treats a 218.Ql - 219on the command line as a non-argument. 220.It OpenBSD 221a 222.Ql - 223within the option string matches a 224.Ql - 225(single dash) on the command line. 226This functionality is provided for backward compatibility with 227programs, such as 228.Xr su 1 , 229that use 230.Ql - 231as an option flag. 232This practice is wrong, and should not be used in any current development. 233.El 234.It 235handling of 236.Ql :: 237in the option string in the presence of 238.Ev POSIXLY_CORRECT : 239.Bl -tag -width "OpenBSD" 240.It Both 241GNU and 242.Ox 243ignore 244.Ev POSIXLY_CORRECT 245here and take 246.Ql :: 247to mean the preceding option takes an optional argument. 248.El 249.It 250return value in case of missing argument if first character 251(after 252.Ql + 253or 254.Ql - ) 255in the option string is not 256.Ql \&: : 257.Bl -tag -width "OpenBSD" 258.It GNU 259returns 260.Ql \&? 261.It OpenBSD 262returns 263.Ql \&: 264(since 265.Ox Ns 's 266.Xr getopt 3 267does). 268.El 269.It 270handling of 271.Ql --a 272in 273.Xr getopt 3 : 274.Bl -tag -width "OpenBSD" 275.It GNU 276parses this as option 277.Ql - , 278option 279.Ql a . 280.It OpenBSD 281parses this as 282.Ql -- , 283and returns \-1 (ignoring the 284.Ql a ) 285(because the original 286.Fn getopt 287did.) 288.El 289.It 290setting of 291.Va optopt 292for long options with 293.Va flag 294.No non- Ns Dv NULL : 295.Bl -tag -width "OpenBSD" 296.It GNU 297sets 298.Va optopt 299to 300.Va val . 301.It OpenBSD 302sets 303.Va optopt 304to 0 (since 305.Va val 306would never be returned). 307.El 308.It 309handling of 310.Ql -W 311with 312.Ql W; 313in the option string in 314.Xr getopt 3 315(not 316.Fn getopt_long ) : 317.Bl -tag -width "OpenBSD" 318.It GNU 319causes a segmentation fault. 320.It OpenBSD 321no special handling is done; 322.Ql W; 323is interpreted as two separate options, neither of which take an argument. 324.El 325.It 326setting of 327.Va optarg 328for long options without an argument that are invoked via 329.Ql -W 330(with 331.Ql W; 332in the option string): 333.Bl -tag -width "OpenBSD" 334.It GNU 335sets 336.Va optarg 337to the option name (the argument of 338.Ql -W ) . 339.It OpenBSD 340sets 341.Va optarg 342to 343.Dv NULL 344(the argument of the long option). 345.El 346.It 347handling of 348.Ql -W 349with an argument that is not (a prefix to) a known long option 350(with 351.Ql W; 352in the option string): 353.Bl -tag -width "OpenBSD" 354.It GNU 355returns 356.Ql -W 357with 358.Va optarg 359set to the unknown option. 360.It OpenBSD 361treats this as an error (unknown option) and returns 362.Ql \&? 363with 364.Va optopt 365set to 0 and 366.Va optarg 367set to 368.Dv NULL 369(as GNU's man page documents). 370.El 371.It 372The error messages are different. 373.It 374.Ox 375does not permute the argument vector at the same points in 376the calling sequence as GNU does. 377The aspects normally used by the caller 378(ordering after \-1 is returned, value of 379.Va optind 380relative to current positions) are the same, though. 381(We do fewer variable swaps.) 382.El 383.Sh ENVIRONMENT 384.Bl -tag -width Ev 385.It Ev POSIXLY_CORRECT 386If set, option processing stops when the first non-option is found and 387a leading 388.Sq + 389in the 390.Ar optstring 391is ignored. 392.El 393.Sh EXAMPLES 394.Bd -literal 395int bflag, ch, fd; 396int daggerset; 397 398/* options descriptor */ 399static struct option longopts[] = { 400 { "buffy", no_argument, NULL, 'b' }, 401 { "fluoride", required_argument, NULL, 'f' }, 402 { "daggerset", no_argument, &daggerset, 1 }, 403 { NULL, 0, NULL, 0 } 404}; 405 406bflag = 0; 407while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1) 408 switch (ch) { 409 case 'b': 410 bflag = 1; 411 break; 412 case 'f': 413 if ((fd = open(optarg, O_RDONLY, 0)) == -1) 414 err(1, "unable to open %s", optarg); 415 break; 416 case 0: 417 if (daggerset) 418 fprintf(stderr, "Buffy will use her dagger to " 419 "apply fluoride to dracula's teeth\en"); 420 break; 421 default: 422 usage(); 423 /* NOTREACHED */ 424 } 425argc -= optind; 426argv += optind; 427.Ed 428.Sh SEE ALSO 429.Xr getopt 3 430.Sh HISTORY 431The 432.Fn getopt_long 433and 434.Fn getopt_long_only 435functions first appeared in GNU libiberty. 436This implementation first appeared in 437.Ox 3.3 . 438.Sh BUGS 439The 440.Ar argv 441argument is not really 442.Dv const 443as its elements may be permuted (unless 444.Ev POSIXLY_CORRECT 445is set). 446