1.\" $NetBSD: getopt_long.3,v 1.14 2003/08/07 16:43:40 agc 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 April 1, 2000 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.Sh EXAMPLES 142.Bd -literal -compact 143extern char *optarg; 144extern int optind; 145int bflag, ch, fd; 146int daggerset; 147 148/* options descriptor */ 149static struct option longopts[] = { 150 { "buffy", no_argument, 0, 'b' }, 151 { "floride", required_argument, 0, 'f' }, 152 { "daggerset", no_argument, \*[Am]daggerset, 1 }, 153 { NULL, 0, NULL, 0 } 154}; 155 156bflag = 0; 157while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1) 158 switch (ch) { 159 case 'b': 160 bflag = 1; 161 break; 162 case 'f': 163 if ((fd = open(optarg, O_RDONLY, 0)) \*[Lt] 0) { 164 (void)fprintf(stderr, 165 "myname: %s: %s\en", optarg, strerror(errno)); 166 exit(1); 167 } 168 break; 169 case 0: 170 if(daggerset) { 171 fprintf(stderr,"Buffy will use her dagger to " 172 "apply floride to dracula's teeth\en"); 173 } 174 break; 175 case '?': 176 default: 177 usage(); 178} 179argc -= optind; 180argv += optind; 181.Ed 182.Sh IMPLEMENTATION DIFFERENCES 183This section describes differences to the GNU implementation 184found in glibc-2.1.3: 185.Bl -tag -width "xxx" 186.It Li o 187handling of - as first char of option string in presence of 188environment variable POSIXLY_CORRECT: 189.Bl -tag -width "NetBSD" 190.It Li GNU 191ignores POSIXLY_CORRECT and returns non-options as 192arguments to option '\e1'. 193.It Li NetBSD 194honors POSIXLY_CORRECT and stops at the first non-option. 195.El 196.It Li o 197handling of :: in options string in presence of POSIXLY_CORRECT: 198.Bl -tag -width "NetBSD" 199.It Li Both 200GNU and NetBSD ignore POSIXLY_CORRECT here and take :: to 201mean the preceding option takes an optional argument. 202.El 203.It Li o 204return value in case of missing argument if first character 205(after + or -) in option string is not ':': 206.Bl -tag -width "NetBSD" 207.It Li GNU 208returns '?' 209.It NetBSD 210returns ':' (since NetBSD's getopt does). 211.El 212.It Li o 213handling of --a in getopt: 214.Bl -tag -width "NetBSD" 215.It Li GNU 216parses this as option '-', option 'a'. 217.It Li NetBSD 218parses this as '--', and returns \-1 (ignoring the a). 219(Because the original getopt does.) 220.El 221.It Li o 222setting of optopt for long options with flag != 223.Dv NULL : 224.Bl -tag -width "NetBSD" 225.It Li GNU 226sets optopt to val. 227.It Li NetBSD 228sets optopt to 0 (since val would never be returned). 229.El 230.It Li o 231handling of -W with W; in option string in getopt (not getopt_long): 232.Bl -tag -width "NetBSD" 233.It Li GNU 234causes a segfault. 235.It Li NetBSD 236returns \-1, with optind pointing past the argument of -W 237(as if `-W arg' were `--arg', and thus '--' had been found). 238.\" How should we treat W; in the option string when called via 239.\" getopt? Ignore the ';' or treat it as a ':'? Issue a warning? 240.El 241.It Li o 242setting of optarg for long options without an argument that are 243invoked via -W (W; in option string): 244.Bl -tag -width "NetBSD" 245.It Li GNU 246sets optarg to the option name (the argument of -W). 247.It Li NetBSD 248sets optarg to 249.Dv NULL 250(the argument of the long option). 251.El 252.It Li o 253handling of -W with an argument that is not (a prefix to) a known 254long option (W; in option string): 255.Bl -tag -width "NetBSD" 256.It Li GNU 257returns -W with optarg set to the unknown option. 258.It Li NetBSD 259treats this as an error (unknown option) and returns '?' with 260optopt set to 0 and optarg set to 261.Dv NULL 262(as GNU's man page documents). 263.El 264.It Li o 265The error messages are different. 266.It Li o 267NetBSD does not permute the argument vector at the same points in 268the calling sequence as GNU does. 269The aspects normally used by the caller 270(ordering after \-1 is returned, value of optind relative 271to current positions) are the same, though. 272(We do fewer variable swaps.) 273.El 274.Sh SEE ALSO 275.Xr getopt 3 276.Sh HISTORY 277The 278.Fn getopt_long 279function first appeared in GNU libiberty. 280The first 281.Nx 282implementation appeared in 1.5. 283.Sh BUGS 284The implementation can completely replace 285.Xr getopt 3 , 286but right now we are using separate code. 287