1.\" $NetBSD: getopt.3,v 1.32 2010/03/22 19:30:54 joerg 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. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)getopt.3 8.5 (Berkeley) 4/27/95 31.\" 32.Dd September 10, 2003 33.Dt GETOPT 3 34.Os 35.Sh NAME 36.Nm getopt 37.Nd get option character from command line argument list 38.Sh LIBRARY 39.Lb libc 40.Sh SYNOPSIS 41.In 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.Qq x 69recognizes an option 70.Dq Fl x , 71and an option string 72.Qq 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 whitespace. 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 variables 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 returns \-1 when the argument list is exhausted. 123The interpretation of options in the argument list may be cancelled 124by the option 125.Dq -- 126(double dash) which causes 127.Fn getopt 128to signal the end of argument processing and return \-1. 129When all options have been processed (i.e., up to the first non-option 130argument), 131.Fn getopt 132returns \-1. 133.Sh RETURN VALUES 134The 135.Fn getopt 136function returns the next known option character in 137.Fa optstring . 138If 139.Fn getopt 140encounters a character not found in 141.Fa optstring 142or if it detects a missing option argument, 143it returns 144.Sq \&? 145(question mark). 146If 147.Fa optstring 148has a leading 149.Sq \&: 150then a missing option argument causes 151.Sq \&: 152to be returned instead of 153.Sq \&? . 154In either case, the variable 155.Va optopt 156is set to the character that caused the error. 157The 158.Fn getopt 159function returns \-1 when the argument list is exhausted. 160.Sh EXAMPLES 161.Bd -literal -compact 162extern char *optarg; 163extern int optind; 164int bflag, ch, fd; 165 166bflag = 0; 167while ((ch = getopt(argc, argv, "bf:")) != -1) { 168 switch (ch) { 169 case 'b': 170 bflag = 1; 171 break; 172 case 'f': 173 if ((fd = open(optarg, O_RDONLY, 0)) \*[Lt] 0) { 174 (void)fprintf(stderr, 175 "myname: %s: %s\en", optarg, strerror(errno)); 176 exit(1); 177 } 178 break; 179 case '?': 180 default: 181 usage(); 182 } 183} 184argc -= optind; 185argv += optind; 186.Ed 187.Sh DIAGNOSTICS 188If the 189.Fn getopt 190function encounters a character not found in the string 191.Fa optstring 192or detects 193a missing option argument it writes an error message to 194.Em stderr 195and returns 196.Sq \&? . 197Setting 198.Va opterr 199to a zero will disable these error messages. 200If 201.Fa optstring 202has a leading 203.Sq \&: 204then a missing option argument causes a 205.Sq \&: 206to be returned in addition to suppressing any error messages. 207.Pp 208Option arguments are allowed to begin with 209.Sq - ; 210this is reasonable but reduces the amount of error checking possible. 211.Sh SEE ALSO 212.Xr getopt 1 , 213.Xr getopt_long 3 , 214.Xr getsubopt 3 215.Sh STANDARDS 216The 217.Va optreset 218variable was added to make it possible to call the 219.Fn getopt 220function multiple times. 221This is an extension to the 222.St -p1003.2 223specification. 224.Sh HISTORY 225The 226.Fn getopt 227function appeared in 228.Bx 4.3 . 229.Sh BUGS 230The 231.Fn getopt 232function was once specified to return 233.Dv EOF 234instead of \-1. 235This was changed by 236.St -p1003.2-92 237to decouple 238.Fn getopt 239from 240.In stdio.h . 241.Pp 242A single dash 243.Pq Sq - 244may be specified as a character in 245.Fa optstring , 246however it should 247.Em never 248have an argument associated with it. 249This allows 250.Fn getopt 251to be used with programs that expect 252.Sq - 253as an option flag. 254This practice is wrong, and should not be used in any current development. 255It is provided for backward compatibility 256.Em only . 257Care should be taken not to use 258.Sq - 259as the first character in 260.Fa optstring 261to avoid a semantic conflict with 262.Tn GNU 263.Fn getopt , 264which assigns different meaning to an 265.Fa optstring 266that begins with a 267.Sq - . 268By default, a single dash causes 269.Fn getopt 270to return \-1. 271.Pp 272It is also possible to handle digits as option letters. 273This allows 274.Fn getopt 275to be used with programs that expect a number 276.Pq Dq Li \-3 277as an option. 278This practice is wrong, and should not be used in any current development. 279It is provided for backward compatibility 280.Em only . 281The following code fragment works in most cases. 282.Bd -literal -offset indent 283int ch; 284long length; 285char *p; 286 287while ((ch = getopt(argc, argv, "0123456789")) != -1) { 288 switch (ch) { 289 case '0': case '1': case '2': case '3': case '4': 290 case '5': case '6': case '7': case '8': case '9': 291 p = argv[optind - 1]; 292 if (p[0] == '-' \*[Am]\*[Am] p[1] == ch \*[Am]\*[Am] !p[2]) 293 length = ch - '0'; 294 else 295 length = strtol(argv[optind] + 1, NULL, 10); 296 break; 297 } 298} 299.Ed 300