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