1.\" $OpenBSD: getopt_long.3,v 1.10 2004/01/06 23:44:28 fgsch Exp $ 2.\" $NetBSD: getopt_long.3,v 1.11 2002/10/02 10:54:19 wiz Exp $ 3.\" 4.\" Copyright (c) 1988, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)getopt.3 8.5 (Berkeley) 4/27/95 32.\" 33.Dd April 1, 2000 34.Dt GETOPT_LONG 3 35.Os 36.Sh NAME 37.Nm getopt_long , 38.Nm getopt_long_only 39.Nd get long options from command line argument list 40.Sh SYNOPSIS 41.Fd #include <getopt.h> 42.Vt extern char *optarg; 43.Vt extern int optind; 44.Vt extern int optopt; 45.Vt extern int opterr; 46.Vt extern int optreset; 47.Ft int 48.Fn getopt_long "int argc" "char * const *argv" "const char *optstring" "const struct option *longopts" "int *longindex" 49.Ft int 50.Fn getopt_long_only "int argc" "char * const *argv" "const char *optstring" "const struct option *longopts" "int *longindex" 51.Sh DESCRIPTION 52The 53.Fn getopt_long 54function is similar to 55.Xr getopt 3 56but it accepts options in two forms: words and characters. 57The 58.Fn getopt_long 59function provides a superset of the functionality of 60.Xr getopt 3 . 61.Fn getopt_long 62can be used in two ways. 63In the first way, every long option understood by the program has a 64corresponding short option, and the option structure is only used to 65translate from long options to short options. 66When used in this fashion, 67.Fn getopt_long 68behaves identically to 69.Xr getopt 3 . 70This is a good way to add long option processing to an existing program 71with the minimum of rewriting. 72.Pp 73In the second mechanism, a long option sets a flag in the 74.Fa option 75structure passed, or will store a pointer to the command line argument 76in the 77.Fa option 78structure passed to it for options that take arguments. 79Additionally, the long option's argument may be specified as a single 80argument with an equal sign, e.g. 81.Bd -literal 82myprogram --myoption=somevalue 83.Ed 84.Pp 85When a long option is processed the call to 86.Fn getopt_long 87will return 0. 88For this reason, long option processing without 89shortcuts is not backwards compatible with 90.Xr getopt 3 . 91.Pp 92It is possible to combine these methods, providing for long options 93processing with short option equivalents for some options. 94Less frequently used options would be processed as long options only. 95.Pp 96The 97.Fn getopt_long 98call requires a structure to be initialized describing the long 99options. 100The structure is: 101.Bd -literal 102struct option { 103 char *name; 104 int has_arg; 105 int *flag; 106 int val; 107}; 108.Ed 109.Pp 110The 111.Fa name 112field should contain the option name without the leading double dash. 113.Pp 114The 115.Fa has_arg 116field should be one of: 117.Bl -tag -width "optional_argument" 118.It Li no_argument 119no argument to the option is expect. 120.It Li required_argument 121an argument to the option is required. 122.It Li optional_argument 123an argument to the option may be presented. 124.El 125.Pp 126If 127.Fa flag 128is not 129.Dv NULL , 130then the integer pointed to by it will be set to the value in the 131.Fa val 132field. 133If the 134.Fa flag 135field is 136.Dv NULL , 137then the 138.Fa val 139field will be returned. 140Setting 141.Fa flag 142to 143.Dv NULL 144and setting 145.Fa val 146to the corresponding short option will make this function act just 147like 148.Xr getopt 3 . 149.Pp 150If the 151.Fa longindex 152field is not 153.Dv NULL , 154then the integer pointed to by it will be set to the index of the long 155option relative to 156.Fa longopts . 157.Pp 158The last element of the 159.Fa longopts 160array has to be filled with zeroes. 161.Pp 162The 163.Fn getopt_long_only 164function behaves identically to 165.Fn getopt_long 166with the exception that long options may start with 167.Sq - 168in addition to 169.Sq -- . 170If an option starting with 171.Sq - 172does not match a long option but does match a single-character option, 173the single-character option is returned. 174.Sh RETURN VALUES 175If the 176.Fa flag 177field in 178.Li struct option 179is 180.Dv NULL , 181.Fn getopt_long 182and 183.Fn getopt_long_only 184return the value specified in the 185.Fa val 186field, which is usually just the corresponding short option. 187If 188.Fa flag 189is not 190.Dv NULL , 191these functions return 0 and store 192.Fa val 193in the location pointed to by 194.Fa flag . 195These functions return 196.Sq \: 197if there was a missing option argument, 198.Sq \&? 199if the user specified an unknown or ambiguous option, and 200\-1 when the argument list has been exhausted. 201.Sh EXAMPLES 202.Bd -literal -compact 203int bflag, ch, fd; 204int daggerset; 205 206/* options descriptor */ 207static struct option longopts[] = { 208 { "buffy", no_argument, NULL, 'b' }, 209 { "fluoride", required_argument, NULL, 'f' }, 210 { "daggerset", no_argument, &daggerset, 1 }, 211 { NULL, 0, NULL, 0 } 212}; 213 214bflag = 0; 215while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1) 216 switch (ch) { 217 case 'b': 218 bflag = 1; 219 break; 220 case 'f': 221 if ((fd = open(optarg, O_RDONLY, 0)) == -1) 222 err(1, "unable to open %s", optarg); 223 break; 224 case 0: 225 if (daggerset) { 226 fprintf(stderr,"Buffy will use her dagger to " 227 "apply fluoride to dracula's teeth\en"); 228 } 229 break; 230 default: 231 usage(); 232} 233argc -= optind; 234argv += optind; 235.Ed 236.Sh IMPLEMENTATION DIFFERENCES 237This section describes differences to the GNU implementation 238found in glibc-2.1.3: 239.Bl -tag -width "xxx" 240.It Li o 241handling of - as first char of option string in presence of 242environment variable POSIXLY_CORRECT: 243.Bl -tag -width "OpenBSD" 244.It Li GNU 245ignores POSIXLY_CORRECT and returns non-options as 246arguments to option '\e1'. 247.It Li OpenBSD 248honors POSIXLY_CORRECT and stops at the first non-option. 249.El 250.It Li o 251handling of - within the option string (not the first character): 252.Bl -tag -width "OpenBSD" 253.It Li GNU 254treats a 255.Ql - 256on the command line as a non-argument. 257.It Li OpenBSD 258a 259.Ql - 260within the option string matches a 261.Ql - 262(single dash) on the command line. 263This functionality is provided for backward compatibility with 264programs, such as 265.Xr su 1 , 266that use 267.Ql - 268as an option flag. 269This practice is wrong, and should not be used in any current development. 270.El 271.It Li o 272handling of :: in options string in presence of POSIXLY_CORRECT: 273.Bl -tag -width "OpenBSD" 274.It Li Both 275GNU and OpenBSD ignore POSIXLY_CORRECT here and take :: to 276mean the preceding option takes an optional argument. 277.El 278.It Li o 279return value in case of missing argument if first character 280(after + or -) in option string is not ':': 281.Bl -tag -width "OpenBSD" 282.It Li GNU 283returns '?' 284.It OpenBSD 285returns ':' (since OpenBSD's getopt does). 286.El 287.It Li o 288handling of --a in getopt: 289.Bl -tag -width "OpenBSD" 290.It Li GNU 291parses this as option '-', option 'a'. 292.It Li OpenBSD 293parses this as '--', and returns \-1 (ignoring the a). 294(Because the original getopt does.) 295.El 296.It Li o 297setting of optopt for long options with flag != 298.Dv NULL : 299.Bl -tag -width "OpenBSD" 300.It Li GNU 301sets optopt to val. 302.It Li OpenBSD 303sets optopt to 0 (since val would never be returned). 304.El 305.It Li o 306handling of -W with W; in option string in getopt (not getopt_long): 307.Bl -tag -width "OpenBSD" 308.It Li GNU 309causes a segfault. 310.It Li OpenBSD 311no special handling is done; 312.Dq W; 313is interpreted as two separate options, neither of which take an argument. 314.El 315.It Li o 316setting of optarg for long options without an argument that are 317invoked via -W (W; in option string): 318.Bl -tag -width "OpenBSD" 319.It Li GNU 320sets optarg to the option name (the argument of -W). 321.It Li OpenBSD 322sets optarg to 323.Dv NULL 324(the argument of the long option). 325.El 326.It Li o 327handling of -W with an argument that is not (a prefix to) a known 328long option (W; in option string): 329.Bl -tag -width "OpenBSD" 330.It Li GNU 331returns -W with optarg set to the unknown option. 332.It Li OpenBSD 333treats this as an error (unknown option) and returns '?' with 334optopt set to 0 and optarg set to 335.Dv NULL 336(as GNU's man page documents). 337.El 338.It Li o 339The error messages are different. 340.It Li o 341OpenBSD does not permute the argument vector at the same points in 342the calling sequence as GNU does. 343The aspects normally used by the caller 344(ordering after \-1 is returned, value of optind relative 345to current positions) are the same, though. 346(We do fewer variable swaps.) 347.El 348.Sh ENVIRONMENT 349.Bl -tag -width POSIXLY_CORRECT 350.It Ev POSIXLY_CORRECT 351If set, option processing stops when the first non-option is found and 352a leading 353.Sq - 354or 355.Sq + 356in the 357.Ar optstring 358is ignored. 359.El 360.Sh SEE ALSO 361.Xr getopt 3 362.Sh HISTORY 363The 364.Fn getopt_long 365and 366.Fn getopt_long_only 367functions first appeared in GNU libiberty. 368This implementation first appeared in 369.Ox 3.3 . 370.Sh BUGS 371The 372.Ar argv 373argument is not really 374.Dv const 375as its elements may be permuted (unless 376.Ev POSIXLY_CORRECT 377is set). 378