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 . 62.Fn getopt_long 63can be used in two ways. 64In the first way, every long option understood 65by the program has a corresponding short option, and the option 66structure is only used to translate from long options to short 67options. 68When used in this fashion, 69.Fn getopt_long 70behaves identically to 71.Xr getopt 3 . 72This is a good way to add long option processing to an existing program 73with the minimum of rewriting. 74.Pp 75In the second mechanism, a long option sets a flag in the 76.Vt option 77structure passed, or will store a pointer to the command line argument 78in the 79.Vt option 80structure passed to it for options that take arguments. 81Additionally, 82the long option's argument may be specified as a single argument with 83an equal sign, e.g., 84.Pp 85.Dl "myprogram --myoption=somevalue" 86.Pp 87When a long option is processed, the call to 88.Fn getopt_long 89will return 0. 90For this reason, long option processing without 91shortcuts is not backwards compatible with 92.Xr getopt 3 . 93.Pp 94It is possible to combine these methods, providing for long options 95processing with short option equivalents for some options. 96Less 97frequently used options would be processed as long options only. 98.Pp 99The 100.Fn getopt_long 101call requires a structure to be initialized describing the long 102options. 103The structure is: 104.Bd -literal -offset indent 105struct option { 106 char *name; 107 int has_arg; 108 int *flag; 109 int val; 110}; 111.Ed 112.Pp 113The 114.Va name 115field should contain the option name without the leading double dash. 116.Pp 117The 118.Va has_arg 119field should be one of: 120.Pp 121.Bl -tag -width ".Dv optional_argument" -offset indent -compact 122.It Dv no_argument 123no argument to the option is expect 124.It Dv required_argument 125an argument to the option is required 126.It Li optional_argument 127an argument to the option may be presented. 128.El 129.Pp 130If 131.Va flag 132is not 133.Dv NULL , 134then the integer pointed to by it will be set to the 135value in the 136.Va val 137field. 138If the 139.Va flag 140field is 141.Dv NULL , 142then the 143.Va val 144field will be returned. 145Setting 146.Va flag 147to 148.Dv NULL 149and setting 150.Va val 151to the corresponding short option will make this function act just 152like 153.Xr getopt 3 . 154.Sh EXAMPLES 155.Bd -literal -compact 156extern char *optarg; 157extern int optind; 158int bflag, ch, fd; 159int daggerset; 160 161/* options descriptor */ 162static struct option longopts[] = { 163 { "buffy", no_argument, 0, 'b' }, 164 { "floride", required_argument, 0, 'f' }, 165 { "daggerset", no_argument, \*[Am]daggerset, 1 }, 166 { 0, 0, 0, 0 } 167}; 168 169bflag = 0; 170while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1) 171 switch(ch) { 172 case 'b': 173 bflag = 1; 174 break; 175 case 'f': 176 if ((fd = open(optarg, O_RDONLY, 0)) \*[Lt] 0) { 177 (void)fprintf(stderr, 178 "myname: %s: %s\en", optarg, strerror(errno)); 179 exit(1); 180 } 181 break; 182 case 0: 183 if(daggerset) { 184 fprintf(stderr,"Buffy will use her dagger to " 185 "apply floride to dracula's teeth\en"); 186 } 187 break; 188 case '?': 189 default: 190 usage(); 191} 192argc -= optind; 193argv += optind; 194.Ed 195.Sh IMPLEMENTATION DIFFERENCES 196This section describes differences to the 197.Tn GNU 198implementation 199found in glibc-2.1.3: 200.Bl -bullet 201.It 202Handling of 203.Ql - 204as first char of option string in presence of 205environment variable 206.Ev POSIXLY_CORRECT : 207.Bl -tag -width ".Nx" 208.It Tn GNU 209ignores 210.Ev POSIXLY_CORRECT 211and returns non-options as 212arguments to option '\e1'. 213.It Nx 214honors 215.Ev POSIXLY_CORRECT 216and stops at the first non-option. 217.El 218.It 219Handling of 220.Ql :: 221in options string in presence of 222.Ev POSIXLY_CORRECT : 223.Bl -tag -width ".Nx" 224.It Both 225.Tn GNU 226and 227.Nx 228ignore 229.Ev POSIXLY_CORRECT 230here and take 231.Ql :: 232to 233mean the preceding option takes an optional argument. 234.El 235.It 236Return value in case of missing argument if first character 237(after 238.Ql + 239or 240.Ql - ) 241in option string is not 242.Ql \&: : 243.Bl -tag -width ".Nx" 244.It Tn GNU 245returns 246.Ql \&? 247.It Nx 248returns 249.Ql \&: 250(since 251.Nx Ns 's 252.Fn getopt 253does). 254.El 255.It 256Handling of 257.Ql --a 258in getopt: 259.Bl -tag -width ".Nx" 260.It Tn GNU 261parses this as option 262.Ql - , 263option 264.Ql a . 265.It Nx 266parses this as 267.Ql -- , 268and returns \-1 (ignoring the 269.Ql a ) . 270(Because the original 271.Fn getopt 272does.) 273.El 274.It 275Setting of 276.Va optopt 277for long options with 278.Va flag 279!= 280.Dv NULL : 281.Bl -tag -width ".Nx" 282.It Tn GNU 283sets 284.Va optopt 285to 286.Va val . 287.It Nx 288sets 289.Va optopt 290to 0 (since 291.Va val 292would never be returned). 293.El 294.It 295Handling of 296.Ql -W 297with 298.Ql W ; 299in option string in 300.Fn getopt 301(not 302.Fn getopt_long ) : 303.Bl -tag -width ".Nx" 304.It Tn GNU 305causes a segfault. 306.It Nx 307returns \-1, with 308.Va optind 309pointing past the argument of 310.Ql -W 311(as if 312.Ql "-W arg" 313were 314.Ql --arg , 315and thus 316.Ql -- 317had been found). 318.\" How should we treat W; in the option string when called via 319.\" getopt? Ignore the ';' or treat it as a ':'? Issue a warning? 320.El 321.It 322Setting of 323.Va optarg 324for long options without an argument that are 325invoked via 326.Ql -W 327.Ql ( W ; 328in option string): 329.Bl -tag -width ".Nx" 330.It Tn GNU 331sets 332.Va optarg 333to the option name (the argument of 334.Ql -W ) . 335.It Nx 336sets 337.Va optarg 338to 339.Dv NULL 340(the argument of the long option). 341.El 342.It 343Handling of 344.Ql -W 345with an argument that is not (a prefix to) a known 346long option 347.Ql ( W ; 348in option string): 349.Bl -tag -width ".Nx" 350.It Tn GNU 351returns 352.Ql -W 353with 354.Va optarg 355set to the unknown option. 356.It Nx 357treats this as an error (unknown option) and returns 358.Ql \&? 359with 360.Va optopt 361set to 0 and 362.Va optarg 363set to 364.Dv NULL 365(as 366.Tn GNU Ns 's 367man page documents). 368.El 369.It 370The error messages are different. 371.It 372.Nx 373does not permute the argument vector at the same points in 374the calling sequence as 375.Tn GNU 376does. 377The aspects normally used by 378the caller (ordering after \-1 is returned, value of 379.Va optind 380relative 381to current positions) are the same, though. 382(We do fewer variable swaps.) 383.El 384.Sh SEE ALSO 385.Xr getopt 3 386.Sh HISTORY 387The 388.Fn getopt_long 389function first appeared in 390.Tn GNU 391libiberty. 392The first 393.Nx 394implementation appeared in 1.5. 395.Sh BUGS 396The implementation can completely replace 397.Xr getopt 3 , 398but right now we are using separate code. 399