1.\" $OpenBSD: getopt_long.3,v 1.15 2007/07/03 12:06:07 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: July 3 2007 $ 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 a structure to be initialized describing the long 104options. 105The structure is: 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 EXAMPLES 208.Bd -literal 209int bflag, ch, fd; 210int daggerset; 211 212/* options descriptor */ 213static struct option longopts[] = { 214 { "buffy", no_argument, NULL, 'b' }, 215 { "fluoride", required_argument, NULL, 'f' }, 216 { "daggerset", no_argument, &daggerset, 1 }, 217 { NULL, 0, NULL, 0 } 218}; 219 220bflag = 0; 221while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1) 222 switch (ch) { 223 case 'b': 224 bflag = 1; 225 break; 226 case 'f': 227 if ((fd = open(optarg, O_RDONLY, 0)) == -1) 228 err(1, "unable to open %s", optarg); 229 break; 230 case 0: 231 if (daggerset) 232 fprintf(stderr, "Buffy will use her dagger to " 233 "apply fluoride to dracula's teeth\en"); 234 break; 235 default: 236 usage(); 237 /* NOTREACHED */ 238 } 239argc -= optind; 240argv += optind; 241.Ed 242.Sh IMPLEMENTATION DIFFERENCES 243This section describes differences to the GNU implementation 244found in glibc-2.1.3: 245.Bl -bullet 246.It 247handling of 248.Ql - 249as the first character of the option string in the presence of the 250environment variable 251.Ev POSIXLY_CORRECT : 252.Bl -tag -width "OpenBSD" 253.It GNU 254ignores 255.Ev POSIXLY_CORRECT 256and returns non-options as arguments to option 257.Ql \e1 . 258.It OpenBSD 259honors 260.Ev POSIXLY_CORRECT 261and stops at the first non-option. 262.El 263.It 264handling of 265.Ql - 266within the option string (not the first character): 267.Bl -tag -width "OpenBSD" 268.It GNU 269treats a 270.Ql - 271on the command line as a non-argument. 272.It OpenBSD 273a 274.Ql - 275within the option string matches a 276.Ql - 277(single dash) on the command line. 278This functionality is provided for backward compatibility with 279programs, such as 280.Xr su 1 , 281that use 282.Ql - 283as an option flag. 284This practice is wrong, and should not be used in any current development. 285.El 286.It 287handling of 288.Ql :: 289in the option string in the presence of 290.Ev POSIXLY_CORRECT : 291.Bl -tag -width "OpenBSD" 292.It Both 293GNU and 294.Ox 295ignore 296.Ev POSIXLY_CORRECT 297here and take 298.Ql :: 299to mean the preceding option takes an optional argument. 300.El 301.It 302return value in case of missing argument if first character 303(after 304.Ql + 305or 306.Ql - ) 307in the option string is not 308.Ql \&: : 309.Bl -tag -width "OpenBSD" 310.It GNU 311returns 312.Ql \&? 313.It OpenBSD 314returns 315.Ql \&: 316(since 317.Ox Ns 's 318.Xr getopt 3 319does). 320.El 321.It 322handling of 323.Ql --a 324in 325.Xr getopt 3 : 326.Bl -tag -width "OpenBSD" 327.It GNU 328parses this as option 329.Ql - , 330option 331.Ql a . 332.It OpenBSD 333parses this as 334.Ql -- , 335and returns \-1 (ignoring the 336.Ql a ) 337(because the original 338.Fn getopt 339did.) 340.El 341.It 342setting of 343.Va optopt 344for long options with 345.Va flag 346.No non- Ns Dv NULL : 347.Bl -tag -width "OpenBSD" 348.It GNU 349sets 350.Va optopt 351to 352.Va val . 353.It OpenBSD 354sets 355.Va optopt 356to 0 (since 357.Va val 358would never be returned). 359.El 360.It 361handling of 362.Ql -W 363with 364.Ql W; 365in the option string in 366.Xr getopt 3 367(not 368.Fn getopt_long ) : 369.Bl -tag -width "OpenBSD" 370.It GNU 371causes a segmentation fault. 372.It OpenBSD 373no special handling is done; 374.Ql W; 375is interpreted as two separate options, neither of which take an argument. 376.El 377.It 378setting of 379.Va optarg 380for long options without an argument that are invoked via 381.Ql -W 382(with 383.Ql W; 384in the option string): 385.Bl -tag -width "OpenBSD" 386.It GNU 387sets 388.Va optarg 389to the option name (the argument of 390.Ql -W ) . 391.It OpenBSD 392sets 393.Va optarg 394to 395.Dv NULL 396(the argument of the long option). 397.El 398.It 399handling of 400.Ql -W 401with an argument that is not (a prefix to) a known long option 402(with 403.Ql W; 404in the option string): 405.Bl -tag -width "OpenBSD" 406.It GNU 407returns 408.Ql -W 409with 410.Va optarg 411set to the unknown option. 412.It OpenBSD 413treats this as an error (unknown option) and returns 414.Ql \&? 415with 416.Va optopt 417set to 0 and 418.Va optarg 419set to 420.Dv NULL 421(as GNU's man page documents). 422.El 423.It 424The error messages are different. 425.It 426.Ox 427does not permute the argument vector at the same points in 428the calling sequence as GNU does. 429The aspects normally used by the caller 430(ordering after \-1 is returned, value of 431.Va optind 432relative to current positions) are the same, though. 433(We do fewer variable swaps.) 434.El 435.Sh ENVIRONMENT 436.Bl -tag -width Ev 437.It Ev POSIXLY_CORRECT 438If set, option processing stops when the first non-option is found and 439a leading 440.Sq - 441or 442.Sq + 443in the 444.Ar optstring 445is ignored. 446.El 447.Sh SEE ALSO 448.Xr getopt 3 449.Sh HISTORY 450The 451.Fn getopt_long 452and 453.Fn getopt_long_only 454functions first appeared in GNU libiberty. 455This implementation first appeared in 456.Ox 3.3 . 457.Sh BUGS 458The 459.Ar argv 460argument is not really 461.Dv const 462as its elements may be permuted (unless 463.Ev POSIXLY_CORRECT 464is set). 465