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 167#include <unistd.h> 168int bflag, ch, fd; 169 170bflag = 0; 171while ((ch = getopt(argc, argv, "bf:")) != -1) { 172 switch (ch) { 173 case 'b': 174 bflag = 1; 175 break; 176 case 'f': 177 if ((fd = open(optarg, O_RDONLY, 0)) \*[Lt] 0) { 178 (void)fprintf(stderr, 179 "myname: %s: %s\en", optarg, strerror(errno)); 180 exit(1); 181 } 182 break; 183 case '?': 184 default: 185 usage(); 186 } 187} 188argc -= optind; 189argv += optind; 190.Ed 191.Sh DIAGNOSTICS 192If the 193.Fn getopt 194function encounters a character not found in the string 195.Fa optstring 196or detects 197a missing option argument it writes an error message to the 198.Dv stderr 199and returns 200.Ql \&? . 201Setting 202.Va opterr 203to a zero will disable these error messages. 204If 205.Fa optstring 206has a leading 207.Ql \&: 208then a missing option argument causes a 209.Ql \&: 210to be returned in addition to suppressing any error messages. 211.Pp 212Option arguments are allowed to begin with 213.Dq Li \- ; 214this is reasonable but reduces the amount of error checking possible. 215.Sh SEE ALSO 216.Xr getopt 1 , 217.Xr getopt_long 3 , 218.Xr getsubopt 3 219.Sh STANDARDS 220The 221.Va optreset 222variable was added to make it possible to call the 223.Fn getopt 224function multiple times. 225This is an extension to the 226.St -p1003.2 227specification. 228.Sh HISTORY 229The 230.Fn getopt 231function appeared in 232.Bx 4.3 . 233.Sh BUGS 234The 235.Fn getopt 236function was once specified to return 237.Dv EOF 238instead of \-1. 239This was changed by 240.St -p1003.2-92 241to decouple 242.Fn getopt 243from 244.In stdio.h . 245.Pp 246A single dash 247.Dq Li - 248may be specified as a character in 249.Fa optstring , 250however it should 251.Em never 252have an argument associated with it. 253This allows 254.Fn getopt 255to be used with programs that expect 256.Dq Li - 257as an option flag. 258This practice is wrong, and should not be used in any current development. 259It is provided for backward compatibility 260.Em only . 261Care should be taken not to use 262.Ql \&- 263as the first character in 264.Fa optstring 265to avoid a semantic conflict with 266.Tn GNU 267.Fn getopt , 268which assigns different meaning to an 269.Fa optstring 270that begins with a 271.Ql \&- . 272By default, a single dash causes 273.Fn getopt 274to return \-1. 275.Pp 276It is also possible to handle digits as option letters. 277This allows 278.Fn getopt 279to be used with programs that expect a number 280.Pq Dq Li \&-\&3 281as an option. 282This practice is wrong, and should not be used in any current development. 283It is provided for backward compatibility 284.Em only . 285The following code fragment works in most cases. 286.Bd -literal -offset indent 287int ch; 288long length; 289char *p, *ep; 290 291while ((ch = getopt(argc, argv, "0123456789")) != -1) 292 switch (ch) { 293 case '0': case '1': case '2': case '3': case '4': 294 case '5': case '6': case '7': case '8': case '9': 295 p = argv[optind - 1]; 296 if (p[0] == '-' \*[Am]\*[Am] p[1] == ch \*[Am]\*[Am] !p[2]) { 297 length = ch - '0'; 298 ep = ""; 299 } else if (argv[optind] \*[Am]\*[Am] argv[optind][1] == ch) { 300 length = strtol((p = argv[optind] + 1), 301 \*[Am]ep, 10); 302 optind++; 303 optreset = 1; 304 } else 305 usage(); 306 if (*ep != '\e0') 307 errx(EX_USAGE, "illegal number -- %s", p); 308 break; 309 } 310.Ed 311