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 cancelled 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 175int bflag, ch, fd; 176 177bflag = 0; 178while ((ch = getopt(argc, argv, "bf:")) != -1) 179 switch (ch) { 180 case 'b': 181 bflag = 1; 182 break; 183 case 'f': 184 if ((fd = open(optarg, O_RDONLY, 0)) < 0) 185 err(1, "%s", optarg); 186 break; 187 case '?': 188 default: 189 usage(); 190 } 191argc -= optind; 192argv += optind; 193.Ed 194.Sh HISTORY 195The 196.Fn getopt 197function appeared in 198.Bx 4.3 . 199.Sh BUGS 200The 201.Fn getopt 202function was once specified to return 203.Dv EOF 204instead of \-1. 205This was changed by 206.St -p1003.2-92 207to decouple 208.Fn getopt 209from 210.Pa <stdio.h> . 211.Pp 212A single dash 213.Dq Li - 214may be specified as a character in 215.Fa optstring , 216however it should 217.Em never 218have an argument associated with it. 219This allows 220.Fn getopt 221to be used with programs that expect 222.Dq Li - 223as an option flag. 224This practice is wrong, and should not be used in any current development. 225It is provided for backward compatibility 226.Em only . 227By default, a single dash causes 228.Fn getopt 229to return \-1. 230This is, we believe, compatible with System V. 231.Pp 232It is also possible to handle digits as option letters. 233This allows 234.Fn getopt 235to be used with programs that expect a number 236.Pq Dq Li \&-\&3 237as an option. 238This practice is wrong, and should not be used in any current development. 239It is provided for backward compatibility 240.Em only . 241The following code fragment works in most (but not all) cases. 242.Bd -literal -offset indent 243int length; 244char *p, *ep; 245 246while ((ch = getopt(argc, argv, "0123456789")) != -1) 247 switch (ch) { 248 case '0': case '1': case '2': case '3': case '4': 249 case '5': case '6': case '7': case '8': case '9': 250 p = argv[optind - 1]; 251 if (p[0] == '-' && p[1] == ch && !p[2]) 252 length = strtol(++p, &ep, 10); 253 else if (argv[optind] && argv[optind][1] == ch) { 254 length = strtol((p = argv[optind] + 1), 255 &ep, 10); 256 optind++; 257 optreset = 1; 258 } else 259 usage(); 260 if (*ep != '\0') 261 errx(EX_USAGE, "illegal number -- %s", p); 262 break; 263 } 264.Ed 265