1.\" $NetBSD: getopt_long.3,v 1.8 2002/06/03 12:01:43 wiz Exp $ 2.\" 3.\" Copyright (c) 1988, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)getopt.3 8.5 (Berkeley) 4/27/95 35.\" $FreeBSD$ 36.\" 37.Dd April 1, 2000 38.Dt GETOPT_LONG 3 39.Os 40.Sh NAME 41.Nm getopt_long 42.Nd get long options from command line argument list 43.Sh LIBRARY 44.Lb libc 45.Sh SYNOPSIS 46.In getopt.h 47.Ft int 48.Fo getopt_long 49.Fa "int argc" "char * const *argv" "const char *optstring" 50.Fa "struct option *long options" "int *index" 51.Fc 52.Sh DESCRIPTION 53The 54.Fn getopt_long 55function is similar to 56.Xr getopt 3 57but it accepts options in two forms: words and characters. 58The 59.Fn getopt_long 60function provides a superset of the functionality of 61.Xr getopt 3 . 62The 63.Fn getopt_long 64function 65can be used in two ways. 66In the first way, every long option understood 67by the program has a corresponding short option, and the option 68structure is only used to translate from long options to short 69options. 70When used in this fashion, 71.Fn getopt_long 72behaves identically to 73.Xr getopt 3 . 74This is a good way to add long option processing to an existing program 75with the minimum of rewriting. 76.Pp 77In the second mechanism, a long option sets a flag in the 78.Vt option 79structure passed, or will store a pointer to the command line argument 80in the 81.Vt option 82structure passed to it for options that take arguments. 83Additionally, 84the long option's argument may be specified as a single argument with 85an equal sign, e.g., 86.Pp 87.Dl "myprogram --myoption=somevalue" 88.Pp 89When a long option is processed, the call to 90.Fn getopt_long 91will return 0. 92For this reason, long option processing without 93shortcuts is not backwards compatible with 94.Xr getopt 3 . 95.Pp 96It is possible to combine these methods, providing for long options 97processing with short option equivalents for some options. 98Less 99frequently used options would be processed as long options only. 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.Va name 117field should contain the option name without the leading double dash. 118.Pp 119The 120.Va has_arg 121field should be one of: 122.Pp 123.Bl -tag -width ".Dv optional_argument" -offset indent -compact 124.It Dv no_argument 125no argument to the option is expect 126.It Dv required_argument 127an argument to the option is required 128.It Li optional_argument 129an argument to the option may be presented. 130.El 131.Pp 132If 133.Va flag 134is not 135.Dv NULL , 136then the integer pointed to by it will be set to the 137value in the 138.Va val 139field. 140If the 141.Va flag 142field is 143.Dv NULL , 144then the 145.Va val 146field will be returned. 147Setting 148.Va flag 149to 150.Dv NULL 151and setting 152.Va val 153to the corresponding short option will make this function act just 154like 155.Xr getopt 3 . 156.Sh EXAMPLES 157.Bd -literal -compact 158extern char *optarg; 159extern int optind; 160int bflag, ch, fd; 161int daggerset; 162 163/* options descriptor */ 164static struct option longopts[] = { 165 { "buffy", no_argument, 0, 'b' }, 166 { "floride", required_argument, 0, 'f' }, 167 { "daggerset", no_argument, \*[Am]daggerset, 1 }, 168 { 0, 0, 0, 0 } 169}; 170 171bflag = 0; 172while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1) 173 switch(ch) { 174 case 'b': 175 bflag = 1; 176 break; 177 case 'f': 178 if ((fd = open(optarg, O_RDONLY, 0)) \*[Lt] 0) { 179 (void)fprintf(stderr, 180 "myname: %s: %s\en", optarg, strerror(errno)); 181 exit(1); 182 } 183 break; 184 case 0: 185 if(daggerset) { 186 fprintf(stderr,"Buffy will use her dagger to " 187 "apply floride to dracula's teeth\en"); 188 } 189 break; 190 case '?': 191 default: 192 usage(); 193} 194argc -= optind; 195argv += optind; 196.Ed 197.Sh IMPLEMENTATION DIFFERENCES 198This section describes differences to the 199.Tn GNU 200implementation 201found in glibc-2.1.3: 202.Bl -bullet 203.It 204Handling of 205.Ql - 206as first char of option string in presence of 207environment variable 208.Ev POSIXLY_CORRECT : 209.Bl -tag -width ".Nx" 210.It Tn GNU 211ignores 212.Ev POSIXLY_CORRECT 213and returns non-options as 214arguments to option '\e1'. 215.It Nx 216honors 217.Ev POSIXLY_CORRECT 218and stops at the first non-option. 219.El 220.It 221Handling of 222.Ql :: 223in options string in presence of 224.Ev POSIXLY_CORRECT : 225.Bl -tag -width ".Nx" 226.It Both 227.Tn GNU 228and 229.Nx 230ignore 231.Ev POSIXLY_CORRECT 232here and take 233.Ql :: 234to 235mean the preceding option takes an optional argument. 236.El 237.It 238Return value in case of missing argument if first character 239(after 240.Ql + 241or 242.Ql - ) 243in option string is not 244.Ql \&: : 245.Bl -tag -width ".Nx" 246.It Tn GNU 247returns 248.Ql \&? 249.It Nx 250returns 251.Ql \&: 252(since 253.Nx Ns 's 254.Fn getopt 255does). 256.El 257.It 258Handling of 259.Ql --a 260in getopt: 261.Bl -tag -width ".Nx" 262.It Tn GNU 263parses this as option 264.Ql - , 265option 266.Ql a . 267.It Nx 268parses this as 269.Ql -- , 270and returns \-1 (ignoring the 271.Ql a ) . 272(Because the original 273.Fn getopt 274does.) 275.El 276.It 277Setting of 278.Va optopt 279for long options with 280.Va flag 281!= 282.Dv NULL : 283.Bl -tag -width ".Nx" 284.It Tn GNU 285sets 286.Va optopt 287to 288.Va val . 289.It Nx 290sets 291.Va optopt 292to 0 (since 293.Va val 294would never be returned). 295.El 296.It 297Handling of 298.Ql -W 299with 300.Ql W ; 301in option string in 302.Fn getopt 303(not 304.Fn getopt_long ) : 305.Bl -tag -width ".Nx" 306.It Tn GNU 307causes a segfault. 308.It Nx 309returns \-1, with 310.Va optind 311pointing past the argument of 312.Ql -W 313(as if 314.Ql "-W arg" 315were 316.Ql --arg , 317and thus 318.Ql -- 319had been found). 320.\" How should we treat W; in the option string when called via 321.\" getopt? Ignore the ';' or treat it as a ':'? Issue a warning? 322.El 323.It 324Setting of 325.Va optarg 326for long options without an argument that are 327invoked via 328.Ql -W 329.Ql ( W ; 330in option string): 331.Bl -tag -width ".Nx" 332.It Tn GNU 333sets 334.Va optarg 335to the option name (the argument of 336.Ql -W ) . 337.It Nx 338sets 339.Va optarg 340to 341.Dv NULL 342(the argument of the long option). 343.El 344.It 345Handling of 346.Ql -W 347with an argument that is not (a prefix to) a known 348long option 349.Ql ( W ; 350in option string): 351.Bl -tag -width ".Nx" 352.It Tn GNU 353returns 354.Ql -W 355with 356.Va optarg 357set to the unknown option. 358.It Nx 359treats this as an error (unknown option) and returns 360.Ql \&? 361with 362.Va optopt 363set to 0 and 364.Va optarg 365set to 366.Dv NULL 367(as 368.Tn GNU Ns 's 369man page documents). 370.El 371.It 372The error messages are different. 373.It 374.Nx 375does not permute the argument vector at the same points in 376the calling sequence as 377.Tn GNU 378does. 379The aspects normally used by 380the caller (ordering after \-1 is returned, value of 381.Va optind 382relative 383to current positions) are the same, though. 384(We do fewer variable swaps.) 385.El 386.Sh SEE ALSO 387.Xr getopt 3 388.Sh HISTORY 389The 390.Fn getopt_long 391function first appeared in 392.Tn GNU 393libiberty. 394The first 395.Nx 396implementation appeared in 1.5. 397.Sh BUGS 398The implementation can completely replace 399.Xr getopt 3 , 400but right now we are using separate code. 401