1.\" $NetBSD: getopt_long.3,v 1.11 2002/10/02 10:54:19 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.\" 36.Dd April 1, 2000 37.Dt GETOPT_LONG 3 38.Os 39.Sh NAME 40.Nm getopt_long 41.Nd get long options from command line argument list 42.Sh LIBRARY 43.Lb libc 44.Sh SYNOPSIS 45.Fd #include \*[Lt]getopt.h\*[Gt] 46.Ft int 47.Fn getopt_long "int argc" "char * const *argv" "const char *optstring" "struct option *long options" "int *index" 48.Sh DESCRIPTION 49The 50.Fn getopt_long 51function is similar to 52.Xr getopt 3 53but it accepts options in two forms: words and characters. 54The 55.Fn getopt_long 56function provides a superset of the functionality of 57.Xr getopt 3 . 58.Fn getopt_long 59can be used in two ways. 60In the first way, every long option understood by the program has a 61corresponding short option, and the option structure is only used to 62translate from long options to short options. 63When used in this fashion, 64.Fn getopt_long 65behaves identically to 66.Xr getopt 3 . 67This is a good way to add long option processing to an existing program 68with the minimum of rewriting. 69.Pp 70In the second mechanism, a long option sets a flag in the 71.Fa option 72structure passed, or will store a pointer to the command line argument 73in the 74.Fa option 75structure passed to it for options that take arguments. 76Additionally, the long option's argument may be specified as a single 77argument with an equal sign, e.g. 78.Bd -literal 79myprogram --myoption=somevalue 80.Ed 81.Pp 82When a long option is processed the call to 83.Fn getopt_long 84will return 0. 85For this reason, long option processing without 86shortcuts is not backwards compatible with 87.Xr getopt 3 . 88.Pp 89It is possible to combine these methods, providing for long options 90processing with short option equivalents for some options. 91Less frequently used options would be processed as long options only. 92.Pp 93The 94.Fn getopt_long 95call requires a structure to be initialized describing the long options. 96The structure is: 97.Bd -literal 98struct option { 99 char *name; 100 int has_arg; 101 int *flag; 102 int val; 103}; 104.Ed 105.Pp 106The 107.Fa name 108field should contain the option name without the leading double dash. 109.Pp 110The 111.Fa has_arg 112field should be one of: 113.Bl -tag -width "optional_argument" 114.It Li no_argument 115no argument to the option is expect. 116.It Li required_argument 117an argument to the option is required. 118.It Li optional_argument 119an argument to the option may be presented. 120.El 121.Pp 122If 123.Fa flag 124is not 125.Dv NULL , 126then the integer pointed to by it will be set to the value in the 127.Fa val 128field. 129If the 130.Fa flag 131field is 132.Dv NULL , 133then the 134.Fa val 135field will be returned. 136Setting 137.Fa flag 138to 139.Dv NULL 140and setting 141.Fa val 142to the corresponding short option will make this function act just 143like 144.Xr getopt 3 . 145.Sh EXAMPLES 146.Bd -literal -compact 147extern char *optarg; 148extern int optind; 149int bflag, ch, fd; 150int daggerset; 151 152/* options descriptor */ 153static struct option longopts[] = { 154 { "buffy", no_argument, 0, 'b' }, 155 { "floride", required_argument, 0, 'f' }, 156 { "daggerset", no_argument, \*[Am]daggerset, 1 }, 157 { 0, 0, 0, 0 } 158}; 159 160bflag = 0; 161while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1) 162 switch(ch) { 163 case 'b': 164 bflag = 1; 165 break; 166 case 'f': 167 if ((fd = open(optarg, O_RDONLY, 0)) \*[Lt] 0) { 168 (void)fprintf(stderr, 169 "myname: %s: %s\en", optarg, strerror(errno)); 170 exit(1); 171 } 172 break; 173 case 0: 174 if(daggerset) { 175 fprintf(stderr,"Buffy will use her dagger to " 176 "apply floride to dracula's teeth\en"); 177 } 178 break; 179 case '?': 180 default: 181 usage(); 182} 183argc -= optind; 184argv += optind; 185.Ed 186.Sh IMPLEMENTATION DIFFERENCES 187This section describes differences to the GNU implementation 188found in glibc-2.1.3: 189.Bl -tag -width "xxx" 190.It Li o 191handling of - as first char of option string in presence of 192environment variable POSIXLY_CORRECT: 193.Bl -tag -width "NetBSD" 194.It Li GNU 195ignores POSIXLY_CORRECT and returns non-options as 196arguments to option '\e1'. 197.It Li NetBSD 198honors POSIXLY_CORRECT and stops at the first non-option. 199.El 200.It Li o 201handling of :: in options string in presence of POSIXLY_CORRECT: 202.Bl -tag -width "NetBSD" 203.It Li Both 204GNU and NetBSD ignore POSIXLY_CORRECT here and take :: to 205mean the preceding option takes an optional argument. 206.El 207.It Li o 208return value in case of missing argument if first character 209(after + or -) in option string is not ':': 210.Bl -tag -width "NetBSD" 211.It Li GNU 212returns '?' 213.It NetBSD 214returns ':' (since NetBSD's getopt does). 215.El 216.It Li o 217handling of --a in getopt: 218.Bl -tag -width "NetBSD" 219.It Li GNU 220parses this as option '-', option 'a'. 221.It Li NetBSD 222parses this as '--', and returns \-1 (ignoring the a). 223(Because the original getopt does.) 224.El 225.It Li o 226setting of optopt for long options with flag != 227.Dv NULL : 228.Bl -tag -width "NetBSD" 229.It Li GNU 230sets optopt to val. 231.It Li NetBSD 232sets optopt to 0 (since val would never be returned). 233.El 234.It Li o 235handling of -W with W; in option string in getopt (not getopt_long): 236.Bl -tag -width "NetBSD" 237.It Li GNU 238causes a segfault. 239.It Li NetBSD 240returns \-1, with optind pointing past the argument of -W 241(as if `-W arg' were `--arg', and thus '--' had been found). 242.\" How should we treat W; in the option string when called via 243.\" getopt? Ignore the ';' or treat it as a ':'? Issue a warning? 244.El 245.It Li o 246setting of optarg for long options without an argument that are 247invoked via -W (W; in option string): 248.Bl -tag -width "NetBSD" 249.It Li GNU 250sets optarg to the option name (the argument of -W). 251.It Li NetBSD 252sets optarg to 253.Dv NULL 254(the argument of the long option). 255.El 256.It Li o 257handling of -W with an argument that is not (a prefix to) a known 258long option (W; in option string): 259.Bl -tag -width "NetBSD" 260.It Li GNU 261returns -W with optarg set to the unknown option. 262.It Li NetBSD 263treats this as an error (unknown option) and returns '?' with 264optopt set to 0 and optarg set to 265.Dv NULL 266(as GNU's man page documents). 267.El 268.It Li o 269The error messages are different. 270.It Li o 271NetBSD does not permute the argument vector at the same points in 272the calling sequence as GNU does. 273The aspects normally used by the caller 274(ordering after \-1 is returned, value of optind relative 275to current positions) are the same, though. 276(We do fewer variable swaps.) 277.El 278.Sh SEE ALSO 279.Xr getopt 3 280.Sh HISTORY 281The 282.Fn getopt_long 283function first appeared in GNU libiberty. 284The first 285.Nx 286implementation appeared in 1.5. 287.Sh BUGS 288The implementation can completely replace 289.Xr getopt 3 , 290but right now we are using separate code. 291