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