1.\" Copyright (c) 1988, 1991 Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)getopt.3 6.18 (Berkeley) 03/02/93 7.\" 8.Dd 9.Dt GETOPT 3 10.Os BSD 4.3 11.Sh NAME 12.Nm getopt 13.Nd get option character from command line argument list 14.Sh SYNOPSIS 15.Fd #include <stdlib.h> 16.Vt extern char *optarg 17.Vt extern int optind 18.Vt extern int optopt 19.Vt extern int opterr 20.Vt extern int optreset 21.Ft int 22.Fn getopt "int argc" "char * const *argv" "const char *optstring" 23.Sh DESCRIPTION 24The 25.Fn getopt 26function incrementally parses a command line argument list 27.Fa argv 28and returns the next 29.Em known 30option character. 31An option character is 32.Em known 33if it has been specified in the string of accepted option characters, 34.Fa optstring . 35.Pp 36The option string 37.Fa optstring 38may contain the following elements: individual characters, and 39characters followed by a colon to indicate an option argument 40is to follow. 41For example, an option string 42.Li "\&""x"" 43recognizes an option 44.Dq Fl x , 45and an option string 46.Li "\&""x:"" 47recognizes an option and argument 48.Dq Fl x Ar argument . 49It does not matter to 50.Fn getopt 51if a following argument has leading white space. 52.Pp 53On return from 54.Fn getopt , 55.Va optarg 56points to an option argument, if it is anticipated, 57and the variable 58.Va optind 59contains the index to the next 60.Fa argv 61argument for a subsequent call 62to 63.Fn getopt . 64The variable 65.Va optopt 66saves the last 67.Em known 68option character returned by 69.Fn getopt . 70.Pp 71The variable 72.Va opterr 73and 74.Va optind 75are both initialized to 1. 76The 77.Va optind 78variable may be set to another value before a set of calls to 79.Fn getopt 80in order to skip over more or less argv entries. 81.Pp 82In order to use 83.Fn getopt 84to evaluate multiple sets of arguments, or to evaluate a single set of 85arguments multiple times, 86the variable 87.Va optreset 88must be set to 1 before the second and each additional set of calls to 89.Fn getopt , 90and the variable 91.Va optind 92must be reinitialized. 93.Pp 94The 95.Fn getopt 96function 97returns an 98.Dv EOF 99when the argument list is exhausted, or a non-recognized 100option is encountered. 101The interpretation of options in the argument list may be cancelled 102by the option 103.Ql -- 104(double dash) which causes 105.Fn getopt 106to signal the end of argument processing and return an 107.Dv EOF . 108When all options have been processed (i.e., up to the first non-option 109argument), 110.Fn getopt 111returns 112.Dv EOF . 113.Sh DIAGNOSTICS 114If the 115.Fn getopt 116function encounters a character not found in the string 117.Va optarg 118or detects 119a missing option argument it writes an error message and returns 120.Ql ? 121to the 122.Em stderr . 123Setting 124.Va opterr 125to a zero will disable these error messages. 126If 127.Va optstring 128has a leading 129.Ql \&: 130then then a missing option argumet causes a 131.Ql \&: 132to be returned in addition to supressing any error messages. 133option argument 134.Pp 135Option arguments are allowed to begin with 136.Dq Li \- ; 137this is reasonable but 138reduces the amount of error checking possible. 139.Sh EXTENSIONS 140The 141.Va optreset 142variable was added to make it possible to call the 143.Fn getopt 144function multiple times. 145This is an extension to the 146.St -p1003.2 147specification. 148.Sh EXAMPLE 149.Bd -literal -compact 150extern char *optarg; 151extern int optind; 152int bflag, ch, fd; 153 154bflag = 0; 155while ((ch = getopt(argc, argv, "bf:")) != EOF) 156 switch(ch) { 157 case 'b': 158 bflag = 1; 159 break; 160 case 'f': 161 if ((fd = open(optarg, O_RDONLY, 0)) < 0) { 162 (void)fprintf(stderr, 163 "myname: %s: %s\en", optarg, strerror(errno)); 164 exit(1); 165 } 166 break; 167 case '?': 168 default: 169 usage(); 170} 171argc -= optind; 172argv += optind; 173.Ed 174.Sh HISTORY 175The 176.Fn getopt 177function appeared 178.Bx 4.3 . 179.Sh BUGS 180A single dash 181.Dq Li - 182may be specified as an character in 183.Fa optstring , 184however it should 185.Em never 186have an argument associated with it. 187This allows 188.Fn getopt 189to be used with programs that expect 190.Dq Li - 191as an option flag. 192This practice is wrong, and should not be used in any current development. 193It is provided for backward compatibility 194.Em only . 195By default, a single dash causes 196.Fn getopt 197to return 198.Dv EOF . 199This is, we believe, compatible with System V. 200.Pp 201It is also possible to handle digits as option letters. 202This allows 203.Fn getopt 204to be used with programs that expect a number 205.Pq Dq Li \&-\&3 206as an option. 207This practice is wrong, and should not be used in any current development. 208It is provided for backward compatibility 209.Em only . 210The following code fragment works in most cases. 211.Bd -literal -offset indent 212int length; 213char *p; 214 215while ((c = getopt(argc, argv, "0123456789")) != EOF) 216 switch (c) { 217 case '0': case '1': case '2': case '3': case '4': 218 case '5': case '6': case '7': case '8': case '9': 219 p = argv[optind - 1]; 220 if (p[0] == '-' && p[1] == ch && !p[2]) 221 length = atoi(++p); 222 else 223 length = atoi(argv[optind] + 1); 224 break; 225 } 226} 227.Ed 228