1.\" Copyright (c) 1988, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)getopt.3 8.5 (Berkeley) 04/27/95 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 <unistd.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 \-1 98when the argument list is exhausted, or a non-recognized 99option is encountered. 100The interpretation of options in the argument list may be cancelled 101by the option 102.Ql -- 103(double dash) which causes 104.Fn getopt 105to signal the end of argument processing and returns \-1. 106When all options have been processed (i.e., up to the first non-option 107argument), 108.Fn getopt 109returns \-1. 110.Sh DIAGNOSTICS 111If the 112.Fn getopt 113function encounters a character not found in the string 114.Va optarg 115or detects 116a missing option argument it writes an error message and returns 117.Ql ? 118to the 119.Em stderr . 120Setting 121.Va opterr 122to a zero will disable these error messages. 123If 124.Va optstring 125has a leading 126.Ql \&: 127then a missing option argument causes a 128.Ql \&: 129to be returned in addition to suppressing any error messages. 130.Pp 131Option arguments are allowed to begin with 132.Dq Li \- ; 133this is reasonable but 134reduces the amount of error checking possible. 135.Sh EXTENSIONS 136The 137.Va optreset 138variable was added to make it possible to call the 139.Fn getopt 140function multiple times. 141This is an extension to the 142.St -p1003.2 143specification. 144.Sh EXAMPLE 145.Bd -literal -compact 146extern char *optarg; 147extern int optind; 148int bflag, ch, fd; 149 150bflag = 0; 151while ((ch = getopt(argc, argv, "bf:")) != -1) 152 switch(ch) { 153 case 'b': 154 bflag = 1; 155 break; 156 case 'f': 157 if ((fd = open(optarg, O_RDONLY, 0)) < 0) { 158 (void)fprintf(stderr, 159 "myname: %s: %s\en", optarg, strerror(errno)); 160 exit(1); 161 } 162 break; 163 case '?': 164 default: 165 usage(); 166} 167argc -= optind; 168argv += optind; 169.Ed 170.Sh HISTORY 171The 172.Fn getopt 173function appeared 174.Bx 4.3 . 175.Sh BUGS 176The 177.Fn getopt 178function was once specified to return 179.Dv EOF 180instead of \-1. 181This was changed by 182.St -p1003.2-92 183to decouple 184.Fn getopt 185from 186.Pa <stdio.h> . 187.Pp 188A single dash 189.Dq Li - 190may be specified as an character in 191.Fa optstring , 192however it should 193.Em never 194have an argument associated with it. 195This allows 196.Fn getopt 197to be used with programs that expect 198.Dq Li - 199as an option flag. 200This practice is wrong, and should not be used in any current development. 201It is provided for backward compatibility 202.Em only . 203By default, a single dash causes 204.Fn getopt 205to return \-1. 206This is, we believe, compatible with System V. 207.Pp 208It is also possible to handle digits as option letters. 209This allows 210.Fn getopt 211to be used with programs that expect a number 212.Pq Dq Li \&-\&3 213as an option. 214This practice is wrong, and should not be used in any current development. 215It is provided for backward compatibility 216.Em only . 217The following code fragment works in most cases. 218.Bd -literal -offset indent 219int length; 220char *p; 221 222while ((c = getopt(argc, argv, "0123456789")) != -1) 223 switch (c) { 224 case '0': case '1': case '2': case '3': case '4': 225 case '5': case '6': case '7': case '8': case '9': 226 p = argv[optind - 1]; 227 if (p[0] == '-' && p[1] == ch && !p[2]) 228 length = atoi(++p); 229 else 230 length = atoi(argv[optind] + 1); 231 break; 232 } 233} 234.Ed 235