1.\" $NetBSD: getopt_long.3,v 1.17 2006/06/28 06:25:15 mjl 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. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)getopt.3 8.5 (Berkeley) 4/27/95 31.\" 32.Dd December 2, 2005 33.Dt GETOPT_LONG 3 34.Os 35.Sh NAME 36.Nm getopt_long 37.Nd get long options from command line argument list 38.Sh LIBRARY 39.Lb libc 40.Sh SYNOPSIS 41.In getopt.h 42.Ft int 43.Fn getopt_long "int argc" "char * const *argv" "const char *optstring" "struct option *long_options" "int *index" 44.Sh DESCRIPTION 45The 46.Fn getopt_long 47function is similar to 48.Xr getopt 3 49but it accepts options in two forms: words and characters. 50The 51.Fn getopt_long 52function provides a superset of the functionality of 53.Xr getopt 3 . 54.Fn getopt_long 55can be used in two ways. 56In the first way, every long option understood by the program has a 57corresponding short option, and the option structure is only used to 58translate from long options to short options. 59When used in this fashion, 60.Fn getopt_long 61behaves identically to 62.Xr getopt 3 . 63This is a good way to add long option processing to an existing program 64with the minimum of rewriting. 65.Pp 66In the second mechanism, a long option sets a flag in the 67.Fa option 68structure passed, or will store a pointer to the command line argument 69in the 70.Fa option 71structure passed to it for options that take arguments. 72Additionally, the long option's argument may be specified as a single 73argument with an equal sign, e.g. 74.Bd -literal 75myprogram --myoption=somevalue 76.Ed 77.Pp 78When a long option is processed the call to 79.Fn getopt_long 80will return 0. 81For this reason, long option processing without 82shortcuts is not backwards compatible with 83.Xr getopt 3 . 84.Pp 85It is possible to combine these methods, providing for long options 86processing with short option equivalents for some options. 87Less frequently used options would be processed as long options only. 88.Pp 89The 90.Fn getopt_long 91call requires a structure to be initialized describing the long options. 92The structure is: 93.Bd -literal 94struct option { 95 char *name; 96 int has_arg; 97 int *flag; 98 int val; 99}; 100.Ed 101.Pp 102The 103.Fa name 104field should contain the option name without the leading double dash. 105.Pp 106The 107.Fa has_arg 108field should be one of: 109.Bl -tag -width "optional_argument" 110.It Li no_argument 111no argument to the option is expect. 112.It Li required_argument 113an argument to the option is required. 114.It Li optional_argument 115an argument to the option may be presented. 116.El 117.Pp 118If 119.Fa flag 120is not 121.Dv NULL , 122then the integer pointed to by it will be set to the value in the 123.Fa val 124field. 125If the 126.Fa flag 127field is 128.Dv NULL , 129then the 130.Fa val 131field will be returned. 132Setting 133.Fa flag 134to 135.Dv NULL 136and setting 137.Fa val 138to the corresponding short option will make this function act just 139like 140.Xr getopt 3 . 141.Pp 142If the 143.Fa index 144field is not 145.Dv NULL , 146the integer it points to will be set to the index of the long option 147in the 148.Fa long_options 149array. 150.Pp 151The last element of the 152.Fa long_options 153array has to be filled with zeroes (see 154.Sx EXAMPLES 155section). 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 { "fluoride", required_argument, 0, 'f' }, 167 { "daggerset", no_argument, \*[Am]daggerset, 1 }, 168 { NULL, 0, NULL, 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 fluoride 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 GNU implementation 199found in glibc-2.1.3: 200.Bl -tag -width "xxx" 201.It Li o 202handling of - as first char of option string in presence of 203environment variable POSIXLY_CORRECT: 204.Bl -tag -width "NetBSD" 205.It Li GNU 206ignores POSIXLY_CORRECT and returns non-options as 207arguments to option '\e1'. 208.It Li NetBSD 209honors POSIXLY_CORRECT and stops at the first non-option. 210.El 211.It Li o 212handling of :: in options string in presence of POSIXLY_CORRECT: 213.Bl -tag -width "NetBSD" 214.It Li Both 215GNU and NetBSD ignore POSIXLY_CORRECT here and take :: to 216mean the preceding option takes an optional argument. 217.El 218.It Li o 219return value in case of missing argument if first character 220(after + or -) in option string is not ':': 221.Bl -tag -width "NetBSD" 222.It Li GNU 223returns '?' 224.It NetBSD 225returns ':' (since NetBSD's getopt does). 226.El 227.It Li o 228handling of --a in getopt: 229.Bl -tag -width "NetBSD" 230.It Li GNU 231parses this as option '-', option 'a'. 232.It Li NetBSD 233parses this as '--', and returns \-1 (ignoring the a). 234(Because the original getopt does.) 235.El 236.It Li o 237setting of optopt for long options with flag != 238.Dv NULL : 239.Bl -tag -width "NetBSD" 240.It Li GNU 241sets optopt to val. 242.It Li NetBSD 243sets optopt to 0 (since val would never be returned). 244.El 245.It Li o 246handling of -W with W; in option string in getopt (not getopt_long): 247.Bl -tag -width "NetBSD" 248.It Li GNU 249causes a segfault. 250.It Li NetBSD 251returns \-1, with optind pointing past the argument of -W 252(as if `-W arg' were `--arg', and thus '--' had been found). 253.\" How should we treat W; in the option string when called via 254.\" getopt? Ignore the ';' or treat it as a ':'? Issue a warning? 255.El 256.It Li o 257setting of optarg for long options without an argument that are 258invoked via -W (W; in option string): 259.Bl -tag -width "NetBSD" 260.It Li GNU 261sets optarg to the option name (the argument of -W). 262.It Li NetBSD 263sets optarg to 264.Dv NULL 265(the argument of the long option). 266.El 267.It Li o 268handling of -W with an argument that is not (a prefix to) a known 269long option (W; in option string): 270.Bl -tag -width "NetBSD" 271.It Li GNU 272returns -W with optarg set to the unknown option. 273.It Li NetBSD 274treats this as an error (unknown option) and returns '?' with 275optopt set to 0 and optarg set to 276.Dv NULL 277(as GNU's man page documents). 278.El 279.It Li o 280The error messages are different. 281.It Li o 282NetBSD does not permute the argument vector at the same points in 283the calling sequence as GNU does. 284The aspects normally used by the caller 285(ordering after \-1 is returned, value of optind relative 286to current positions) are the same, though. 287(We do fewer variable swaps.) 288.El 289.Sh SEE ALSO 290.Xr getopt 3 291.Sh HISTORY 292The 293.Fn getopt_long 294function first appeared in GNU libiberty. 295The first 296.Nx 297implementation appeared in 1.5. 298.Sh BUGS 299The implementation can completely replace 300.Xr getopt 3 , 301but right now we are using separate code. 302.Pp 303The 304.Fa argv 305argument is not really const. 306