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