1.\" Copyright (c) 1988, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" $OpenBSD: getopt.3,v 1.6 1998/05/05 19:36:03 deraadt Exp $ 33.\" 34.Dd April 19, 1994 35.Dt GETOPT 3 36.Os BSD 4.3 37.Sh NAME 38.Nm getopt 39.Nd get option character from command line argument list 40.Sh SYNOPSIS 41.Fd #include <unistd.h> 42.Vt extern char *optarg; 43.Vt extern int optind; 44.Vt extern int optopt; 45.Vt extern int opterr; 46.Vt extern int optreset; 47.Ft int 48.Fn getopt "int argc" "char * const *argv" "const char *optstring" 49.Sh DESCRIPTION 50The 51.Fn getopt 52function incrementally parses a command line argument list 53.Fa argv 54and returns the next 55.Em known 56option character. 57An option character is 58.Em known 59if it has been specified in the string of accepted option characters, 60.Fa optstring . 61.Pp 62The option string 63.Fa optstring 64may contain the following elements: individual characters, and 65characters followed by a colon to indicate an option argument 66is to follow. 67For example, an option string 68.Li "\&""x"" 69recognizes an option 70.Dq Fl x , 71and an option string 72.Li "\&""x:"" 73recognizes an option and argument 74.Dq Fl x Ar argument . 75It does not matter to 76.Fn getopt 77if a following argument has leading white space. 78.Pp 79On return from 80.Fn getopt , 81.Va optarg 82points to an option argument, if it is anticipated, 83and the variable 84.Va optind 85contains the index to the next 86.Fa argv 87argument for a subsequent call 88to 89.Fn getopt . 90The variable 91.Va optopt 92saves the last 93.Em known 94option character returned by 95.Fn getopt . 96.Pp 97The variable 98.Va opterr 99and 100.Va optind 101are both initialized to 1. 102The 103.Va optind 104variable may be set to another value before a set of calls to 105.Fn getopt 106in order to skip over more or less argv entries. 107.Pp 108In order to use 109.Fn getopt 110to evaluate multiple sets of arguments, or to evaluate a single set of 111arguments multiple times, 112the variable 113.Va optreset 114must be set to 1 before the second and each additional set of calls to 115.Fn getopt , 116and the variable 117.Va optind 118must be reinitialized. 119.Pp 120The 121.Fn getopt 122function 123returns \-1 124when the argument list is exhausted, or a non-recognized 125option is encountered. 126The interpretation of options in the argument list may be cancelled 127by the option 128.Ql -- 129(double dash) which causes 130.Fn getopt 131to signal the end of argument processing and returns \-1. 132When all options have been processed (i.e., up to the first non-option 133argument), 134.Fn getopt 135returns \-1. 136.Sh DIAGNOSTICS 137If the 138.Fn getopt 139function encounters a character not found in the string 140.Va optstring 141or detects 142a missing option argument it writes an error message to 143.Em stderr 144and returns 145.Ql ? . 146Setting 147.Va opterr 148to a zero will disable these error messages. 149If 150.Va optstring 151has a leading 152.Ql \&: 153then a missing option argument causes a 154.Ql \&: 155to be returned in addition to suppressing any error messages. 156.Pp 157Option arguments are allowed to begin with 158.Dq Li \- ; 159this is reasonable but 160reduces the amount of error checking possible. 161.Sh EXTENSIONS 162The 163.Va optreset 164variable was added to make it possible to call the 165.Fn getopt 166function multiple times. 167This is an extension to the 168.St -p1003.2 169specification. 170.Sh EXAMPLE 171.Bd -literal -compact 172extern char *optarg; 173extern int optind; 174int bflag, ch, fd; 175 176bflag = 0; 177while ((ch = getopt(argc, argv, "bf:")) != -1) { 178 switch (ch) { 179 case 'b': 180 bflag = 1; 181 break; 182 case 'f': 183 if ((fd = open(optarg, O_RDONLY, 0)) < 0) { 184 (void)fprintf(stderr, 185 "myname: %s: %s\en", optarg, strerror(errno)); 186 exit(1); 187 } 188 break; 189 case '?': 190 default: 191 usage(); 192 } 193} 194argc -= optind; 195argv += optind; 196.Ed 197.Sh HISTORY 198The 199.Fn getopt 200function appeared 201.Bx 4.3 . 202.Sh BUGS 203The 204.Fn getopt 205function was once specified to return 206.Dv EOF 207instead of \-1. 208This was changed by 209.St -p1003.2-92 210to decouple 211.Fn getopt 212from 213.Pa <stdio.h> . 214.Pp 215A single dash 216.Dq Li - 217may be specified as a character in 218.Fa optstring , 219however it should 220.Em never 221have an argument associated with it. 222This allows 223.Fn getopt 224to be used with programs that expect 225.Dq Li - 226as an option flag. 227This practice is wrong, and should not be used in any current development. 228It is provided for backward compatibility 229.Em only . 230By default, a single dash causes 231.Fn getopt 232to return \-1. 233This is, we believe, compatible with System V. 234.Pp 235It is also possible to handle digits as option letters. 236This allows 237.Fn getopt 238to be used with programs that expect a number 239.Pq Dq Li \&-\&3 240as an option. 241This practice is wrong, and should not be used in any current development. 242It is provided for backward compatibility 243.Em only . 244The following code fragment works in most cases. 245.Bd -literal -offset indent 246int length; 247char *p; 248 249while ((c = getopt(argc, argv, "0123456789")) != -1) 250 switch (c) { 251 case '0': case '1': case '2': case '3': case '4': 252 case '5': case '6': case '7': case '8': case '9': 253 p = argv[optind - 1]; 254 if (p[0] == '-' && p[1] == ch && !p[2]) 255 length = atoi(++p); 256 else 257 length = atoi(argv[optind] + 1); 258 break; 259 } 260} 261.Ed 262