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