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.\" @(#)getopt.3 8.5 (Berkeley) 4/27/95 33.\" $FreeBSD$ 34.\" 35.Dd April 27, 1995 36.Dt GETOPT 3 37.Os BSD 4.3 38.Sh NAME 39.Nm getopt 40.Nd get option character from command line argument list 41.Sh SYNOPSIS 42.Fd #include <unistd.h> 43.Vt extern char *optarg; 44.Vt extern int optind; 45.Vt extern int optopt; 46.Vt extern int opterr; 47.Vt extern int optreset; 48.Ft int 49.Fn getopt "int argc" "char * const *argv" "const char *optstring" 50.Sh DESCRIPTION 51The 52.Fn getopt 53function incrementally parses a command line argument list 54.Fa argv 55and returns the next 56.Em known 57option character. 58An option character is 59.Em known 60if it has been specified in the string of accepted option characters, 61.Fa optstring . 62.Pp 63The option string 64.Fa optstring 65may contain the following elements: individual characters, and 66characters followed by a colon to indicate an option argument 67is to follow. 68For example, an option string 69.Li "\&""x"" 70recognizes an option 71.Dq Fl x , 72and an option string 73.Li "\&""x:"" 74recognizes an option and argument 75.Dq Fl x Ar argument . 76It does not matter to 77.Fn getopt 78if a following argument has leading white space. 79.Pp 80On return from 81.Fn getopt , 82.Va optarg 83points to an option argument, if it is anticipated, 84and the variable 85.Va optind 86contains the index to the next 87.Fa argv 88argument for a subsequent call 89to 90.Fn getopt . 91The variable 92.Va optopt 93saves the last 94.Em known 95option character returned by 96.Fn getopt . 97.Pp 98The variable 99.Va opterr 100and 101.Va optind 102are both initialized to 1. 103The 104.Va optind 105variable may be set to another value before a set of calls to 106.Fn getopt 107in order to skip over more or less argv entries. 108.Pp 109In order to use 110.Fn getopt 111to evaluate multiple sets of arguments, or to evaluate a single set of 112arguments multiple times, 113the variable 114.Va optreset 115must be set to 1 before the second and each additional set of calls to 116.Fn getopt , 117and the variable 118.Va optind 119must be reinitialized. 120.Pp 121The 122.Fn getopt 123function 124returns \-1 125when the argument list is exhausted, or 126.Ql ? 127if a non-recognized 128option is encountered. 129The interpretation of options in the argument list may be canceled 130by the option 131.Ql -- 132(double dash) which causes 133.Fn getopt 134to signal the end of argument processing and return \-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.Va optarg 144or detects 145a missing option argument it writes an error message to the 146.Em 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 EXAMPLE 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)) < 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 <stdio.h> . 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 ((ch = getopt(argc, argv, "0123456789")) != -1) 252 switch (ch) { 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] == '-' && p[1] == ch && !p[2]) 257 length = atoi(++p); 258 else 259 length = atoi(argv[optind] + 1); 260 break; 261 } 262.Ed 263