1.\" $NetBSD: getopt.3,v 1.31 2003/09/23 10:26:54 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.\" $FreeBSD$ 36.\" 37.Dd April 27, 1995 38.Dt GETOPT 3 39.Os 40.Sh NAME 41.Nm getopt 42.Nd get option character from command line argument list 43.Sh LIBRARY 44.Lb libc 45.Sh SYNOPSIS 46.In unistd.h 47.Vt extern char *optarg ; 48.Vt extern int optind ; 49.Vt extern int optopt ; 50.Vt extern int opterr ; 51.Vt extern int optreset ; 52.Ft int 53.Fn getopt "int argc" "char * const argv[]" "const char *optstring" 54.Sh DESCRIPTION 55The 56.Fn getopt 57function incrementally parses a command line argument list 58.Fa argv 59and returns the next 60.Em known 61option character. 62An option character is 63.Em known 64if it has been specified in the string of accepted option characters, 65.Fa optstring . 66.Pp 67The option string 68.Fa optstring 69may contain the following elements: individual characters, and 70characters followed by a colon to indicate an option argument 71is to follow. 72For example, an option string 73.Li "\&""x"" 74recognizes an option 75.Dq Fl x , 76and an option string 77.Li "\&""x:"" 78recognizes an option and argument 79.Dq Fl x Ar argument . 80It does not matter to 81.Fn getopt 82if a following argument has leading white space. 83.Pp 84On return from 85.Fn getopt , 86.Va optarg 87points to an option argument, if it is anticipated, 88and the variable 89.Va optind 90contains the index to the next 91.Fa argv 92argument for a subsequent call 93to 94.Fn getopt . 95The variable 96.Va optopt 97saves the last 98.Em known 99option character returned by 100.Fn getopt . 101.Pp 102The variables 103.Va opterr 104and 105.Va optind 106are both initialized to 1. 107The 108.Va optind 109variable may be set to another value before a set of calls to 110.Fn getopt 111in order to skip over more or less argv entries. 112.Pp 113In order to use 114.Fn getopt 115to evaluate multiple sets of arguments, or to evaluate a single set of 116arguments multiple times, 117the variable 118.Va optreset 119must be set to 1 before the second and each additional set of calls to 120.Fn getopt , 121and the variable 122.Va optind 123must be reinitialized. 124.Pp 125The 126.Fn getopt 127function returns \-1 when the argument list is exhausted. 128The interpretation of options in the argument list may be cancelled 129by the option 130.Ql -- 131(double dash) which causes 132.Fn getopt 133to signal the end of argument processing and return \-1. 134When all options have been processed (i.e., up to the first non-option 135argument), 136.Fn getopt 137returns \-1. 138.Sh RETURN VALUES 139The 140.Fn getopt 141function returns the next known option character in 142.Fa optstring . 143If 144.Fn getopt 145encounters a character not found in 146.Fa optstring 147or if it detects a missing option argument, 148it returns 149.Ql \&? 150(question mark). 151If 152.Fa optstring 153has a leading 154.Ql \&: 155then a missing option argument causes 156.Ql \&: 157to be returned instead of 158.Ql \&? . 159In either case, the variable 160.Va optopt 161is set to the character that caused the error. 162The 163.Fn getopt 164function returns \-1 when the argument list is exhausted. 165.Sh EXAMPLES 166.Bd -literal -compact 167extern char *optarg; 168extern int optind; 169int bflag, ch, fd; 170 171bflag = 0; 172while ((ch = getopt(argc, argv, "bf:")) != -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 '?': 185 default: 186 usage(); 187 } 188} 189argc -= optind; 190argv += optind; 191.Ed 192.Sh DIAGNOSTICS 193If the 194.Fn getopt 195function encounters a character not found in the string 196.Fa optstring 197or detects 198a missing option argument it writes an error message to the 199.Dv stderr 200and returns 201.Ql \&? . 202Setting 203.Va opterr 204to a zero will disable these error messages. 205If 206.Fa optstring 207has a leading 208.Ql \&: 209then a missing option argument causes a 210.Ql \&: 211to be returned in addition to suppressing any error messages. 212.Pp 213Option arguments are allowed to begin with 214.Dq Li \- ; 215this is reasonable but reduces the amount of error checking possible. 216.Sh SEE ALSO 217.Xr getopt 1 , 218.Xr getopt_long 3 , 219.Xr getsubopt 3 220.Sh STANDARDS 221The 222.Va optreset 223variable was added to make it possible to call the 224.Fn getopt 225function multiple times. 226This is an extension to the 227.St -p1003.2 228specification. 229.Sh HISTORY 230The 231.Fn getopt 232function appeared in 233.Bx 4.3 . 234.Sh BUGS 235The 236.Fn getopt 237function was once specified to return 238.Dv EOF 239instead of \-1. 240This was changed by 241.St -p1003.2-92 242to decouple 243.Fn getopt 244from 245.In stdio.h . 246.Pp 247A single dash 248.Dq Li - 249may be specified as a character in 250.Fa optstring , 251however it should 252.Em never 253have an argument associated with it. 254This allows 255.Fn getopt 256to be used with programs that expect 257.Dq Li - 258as an option flag. 259This practice is wrong, and should not be used in any current development. 260It is provided for backward compatibility 261.Em only . 262Care should be taken not to use 263.Ql \&- 264as the first character in 265.Fa optstring 266to avoid a semantic conflict with 267.Tn GNU 268.Fn getopt , 269which assigns different meaning to an 270.Fa optstring 271that begins with a 272.Ql \&- . 273By default, a single dash causes 274.Fn getopt 275to return \-1. 276.Pp 277It is also possible to handle digits as option letters. 278This allows 279.Fn getopt 280to be used with programs that expect a number 281.Pq Dq Li \&-\&3 282as an option. 283This practice is wrong, and should not be used in any current development. 284It is provided for backward compatibility 285.Em only . 286The following code fragment works in most cases. 287.Bd -literal -offset indent 288int ch; 289long length; 290char *p, *ep; 291 292while ((ch = getopt(argc, argv, "0123456789")) != -1) 293 switch (ch) { 294 case '0': case '1': case '2': case '3': case '4': 295 case '5': case '6': case '7': case '8': case '9': 296 p = argv[optind - 1]; 297 if (p[0] == '-' \*[Am]\*[Am] p[1] == ch \*[Am]\*[Am] !p[2]) { 298 length = ch - '0'; 299 ep = ""; 300 } else if (argv[optind] \*[Am]\*[Am] argv[optind][1] == ch) { 301 length = strtol((p = argv[optind] + 1), 302 \*[Am]ep, 10); 303 optind++; 304 optreset = 1; 305 } else 306 usage(); 307 if (*ep != '\e0') 308 errx(EX_USAGE, "illegal number -- %s", p); 309 break; 310 } 311.Ed 312