1.\" $NetBSD: getopt.3,v 1.26 2003/08/07 16:43:39 agc 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 August 11, 2002 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.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. 125The interpretation of options in the argument list may be cancelled 126by the option 127.Ql -- 128(double dash) which causes 129.Fn getopt 130to signal the end of argument processing and returns \-1. 131When all options have been processed (i.e., up to the first non-option 132argument), 133.Fn getopt 134returns \-1. 135.Sh DIAGNOSTICS 136If the 137.Fn getopt 138function encounters a character not found in the string 139.Fa optstring 140or detects 141a missing option argument it writes an error message to 142.Va stderr 143and returns 144.Ql \&? . 145Setting 146.Va opterr 147to a zero will disable these error messages. 148If 149.Va optstring 150has a leading 151.Ql \&: 152then a missing option argument causes a 153.Ql \&: 154to be returned in addition to suppressing any error messages. 155.Pp 156Option arguments are allowed to begin with 157.Dq Li \- ; 158this is reasonable but 159reduces the amount of error checking possible. 160.Sh EXTENSIONS 161The 162.Va optreset 163variable was added to make it possible to call the 164.Fn getopt 165function multiple times. 166This is an extension to the 167.St -p1003.2 168specification. 169.Sh EXAMPLES 170.Bd -literal -compact 171extern char *optarg; 172extern int optind; 173int bflag, ch, fd; 174 175bflag = 0; 176while ((ch = getopt(argc, argv, "bf:")) != -1) 177 switch (ch) { 178 case 'b': 179 bflag = 1; 180 break; 181 case 'f': 182 if ((fd = open(optarg, O_RDONLY, 0)) \*[Lt] 0) { 183 (void)fprintf(stderr, 184 "myname: %s: %s\en", optarg, strerror(errno)); 185 exit(1); 186 } 187 break; 188 case '?': 189 default: 190 usage(); 191 } 192argc -= optind; 193argv += optind; 194.Ed 195.Sh HISTORY 196The 197.Fn getopt 198function appeared in 199.Bx 4.3 . 200.Sh BUGS 201The 202.Fn getopt 203function was once specified to return 204.Dv EOF 205instead of \-1. 206This was changed by 207.St -p1003.2-92 208to decouple 209.Fn getopt 210from 211.Pa \*[Lt]stdio.h\*[Gt] . 212.Pp 213A single dash 214.Dq Li - 215may be specified as a character in 216.Fa optstring , 217however it should 218.Em never 219have an argument associated with it. 220This allows 221.Fn getopt 222to be used with programs that expect 223.Dq Li - 224as an option flag. 225This practice is wrong, and should not be used in any current development. 226It is provided for backward compatibility 227.Em only . 228By default, a single dash causes 229.Fn getopt 230to return \-1. 231This is, we believe, compatible with System V. 232.Pp 233It is also possible to handle digits as option letters. 234This allows 235.Fn getopt 236to be used with programs that expect a number 237.Pq Dq Li \&-\&3 238as an option. 239This practice is wrong, and should not be used in any current development. 240It is provided for backward compatibility 241.Em only . 242The following code fragment works in most cases. 243.Bd -literal -offset indent 244int length; 245char *p; 246 247while ((c = getopt(argc, argv, "0123456789")) != -1) { 248 switch (c) { 249 case '0': case '1': case '2': case '3': case '4': 250 case '5': case '6': case '7': case '8': case '9': 251 p = argv[optind - 1]; 252 if (p[0] == '-' \*[Am]\*[Am] p[1] == ch \*[Am]\*[Am] !p[2]) 253 length = atoi(++p); 254 else 255 length = atoi(argv[optind] + 1); 256 break; 257 } 258} 259.Ed 260