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