1.\" $NetBSD: getopt_long.3,v 1.18 2007/07/02 17:56:17 ginsbach 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 July 2, 2007 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 89Abbreviated long option names are accepted when 90.Fn getopt_long 91processes long options if the abbreviation is unique. 92An exact match is always preferred for a defined long option. 93.Pp 94The 95.Fn getopt_long 96call requires a structure to be initialized describing the long options. 97The structure is: 98.Bd -literal 99struct option { 100 char *name; 101 int has_arg; 102 int *flag; 103 int val; 104}; 105.Ed 106.Pp 107The 108.Fa name 109field should contain the option name without the leading double dash. 110.Pp 111The 112.Fa has_arg 113field should be one of: 114.Bl -tag -width "optional_argument" 115.It Li no_argument 116no argument to the option is expect. 117.It Li required_argument 118an argument to the option is required. 119.It Li optional_argument 120an argument to the option may be presented. 121.El 122.Pp 123If 124.Fa flag 125is not 126.Dv NULL , 127then the integer pointed to by it will be set to the value in the 128.Fa val 129field. 130If the 131.Fa flag 132field is 133.Dv NULL , 134then the 135.Fa val 136field will be returned. 137Setting 138.Fa flag 139to 140.Dv NULL 141and setting 142.Fa val 143to the corresponding short option will make this function act just 144like 145.Xr getopt 3 . 146.Pp 147If the 148.Fa index 149field is not 150.Dv NULL , 151the integer it points to will be set to the index of the long option 152in the 153.Fa long_options 154array. 155.Pp 156The last element of the 157.Fa long_options 158array has to be filled with zeroes (see 159.Sx EXAMPLES 160section). 161.Sh EXAMPLES 162.Bd -literal -compact 163extern char *optarg; 164extern int optind; 165int bflag, ch, fd; 166int daggerset; 167 168/* options descriptor */ 169static struct option longopts[] = { 170 { "buffy", no_argument, 0, 'b' }, 171 { "fluoride", required_argument, 0, 'f' }, 172 { "daggerset", no_argument, \*[Am]daggerset, 1 }, 173 { NULL, 0, NULL, 0 } 174}; 175 176bflag = 0; 177while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1) 178 switch (ch) { 179 case 'b': 180 bflag = 1; 181 break; 182 case 'f': 183 if ((fd = open(optarg, O_RDONLY, 0)) \*[Lt] 0) { 184 (void)fprintf(stderr, 185 "myname: %s: %s\en", optarg, strerror(errno)); 186 exit(1); 187 } 188 break; 189 case 0: 190 if(daggerset) { 191 fprintf(stderr,"Buffy will use her dagger to " 192 "apply fluoride to dracula's teeth\en"); 193 } 194 break; 195 case '?': 196 default: 197 usage(); 198} 199argc -= optind; 200argv += optind; 201.Ed 202.Sh IMPLEMENTATION DIFFERENCES 203This section describes differences to the GNU implementation 204found in glibc-2.1.3: 205.Bl -tag -width "xxx" 206.It Li o 207handling of - as first char of option string in presence of 208environment variable POSIXLY_CORRECT: 209.Bl -tag -width "NetBSD" 210.It Li GNU 211ignores POSIXLY_CORRECT and returns non-options as 212arguments to option '\e1'. 213.It Li NetBSD 214honors POSIXLY_CORRECT and stops at the first non-option. 215.El 216.It Li o 217handling of :: in options string in presence of POSIXLY_CORRECT: 218.Bl -tag -width "NetBSD" 219.It Li Both 220GNU and NetBSD ignore POSIXLY_CORRECT here and take :: to 221mean the preceding option takes an optional argument. 222.El 223.It Li o 224return value in case of missing argument if first character 225(after + or -) in option string is not ':': 226.Bl -tag -width "NetBSD" 227.It Li GNU 228returns '?' 229.It NetBSD 230returns ':' (since NetBSD's getopt does). 231.El 232.It Li o 233handling of --a in getopt: 234.Bl -tag -width "NetBSD" 235.It Li GNU 236parses this as option '-', option 'a'. 237.It Li NetBSD 238parses this as '--', and returns \-1 (ignoring the a). 239(Because the original getopt does.) 240.El 241.It Li o 242setting of optopt for long options with flag != 243.Dv NULL : 244.Bl -tag -width "NetBSD" 245.It Li GNU 246sets optopt to val. 247.It Li NetBSD 248sets optopt to 0 (since val would never be returned). 249.El 250.It Li o 251handling of -W with W; in option string in getopt (not getopt_long): 252.Bl -tag -width "NetBSD" 253.It Li GNU 254causes a segfault. 255.It Li NetBSD 256returns \-1, with optind pointing past the argument of -W 257(as if `-W arg' were `--arg', and thus '--' had been found). 258.\" How should we treat W; in the option string when called via 259.\" getopt? Ignore the ';' or treat it as a ':'? Issue a warning? 260.El 261.It Li o 262setting of optarg for long options without an argument that are 263invoked via -W (W; in option string): 264.Bl -tag -width "NetBSD" 265.It Li GNU 266sets optarg to the option name (the argument of -W). 267.It Li NetBSD 268sets optarg to 269.Dv NULL 270(the argument of the long option). 271.El 272.It Li o 273handling of -W with an argument that is not (a prefix to) a known 274long option (W; in option string): 275.Bl -tag -width "NetBSD" 276.It Li GNU 277returns -W with optarg set to the unknown option. 278.It Li NetBSD 279treats this as an error (unknown option) and returns '?' with 280optopt set to 0 and optarg set to 281.Dv NULL 282(as GNU's man page documents). 283.El 284.It Li o 285The error messages are different. 286.It Li o 287NetBSD does not permute the argument vector at the same points in 288the calling sequence as GNU does. 289The aspects normally used by the caller 290(ordering after \-1 is returned, value of optind relative 291to current positions) are the same, though. 292(We do fewer variable swaps.) 293.El 294.Sh SEE ALSO 295.Xr getopt 3 296.Sh HISTORY 297The 298.Fn getopt_long 299function first appeared in GNU libiberty. 300The first 301.Nx 302implementation appeared in 1.5. 303.Sh BUGS 304The implementation can completely replace 305.Xr getopt 3 , 306but right now we are using separate code. 307.Pp 308The 309.Fa argv 310argument is not really const. 311