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. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" $OpenBSD: getopt.3,v 1.40 2007/05/31 19:19:31 jmc Exp $ 29.\" 30.Dd $Mdocdate: May 31 2007 $ 31.Dt GETOPT 3 32.Os 33.Sh NAME 34.Nm getopt 35.Nd get option character from command line argument list 36.Sh SYNOPSIS 37.Fd #include <unistd.h> 38.Vt extern char *optarg; 39.Vt extern int opterr; 40.Vt extern int optind; 41.Vt extern int optopt; 42.Vt extern int optreset; 43.Ft int 44.Fn getopt "int argc" "char * const *argv" "const char *optstring" 45.Sh DESCRIPTION 46The 47.Fn getopt 48function incrementally parses a command line argument list 49.Fa argv 50and returns the next 51.Em known 52option character. 53An option character is 54.Em known 55if it has been specified in the string of accepted option characters, 56.Fa optstring . 57.Pp 58The option string 59.Fa optstring 60may contain the following elements: individual characters, 61characters followed by a colon, and characters followed by two colons. 62A character followed by a single colon indicates that an argument 63is to follow the option on the command line. 64Two colons indicates that the argument is optional \- this is an 65extension not covered by POSIX. 66For example, an option string 67.Qq x 68recognizes an option 69.Fl x , 70and an option string 71.Qq Li x: 72recognizes an option and argument 73.Fl x Ar argument . 74It does not matter to 75.Fn getopt 76if a following argument has leading whitespace. 77.Pp 78On return from 79.Fn getopt , 80.Va optarg 81points to an option argument, if it is anticipated, 82and the variable 83.Va optind 84contains the index to the next 85.Fa argv 86argument for a subsequent call 87to 88.Fn getopt . 89.Pp 90The variables 91.Va opterr 92and 93.Va optind 94are both initialized to 1. 95The 96.Va optind 97variable may be set to another value larger than 0 before a set of calls to 98.Fn getopt 99in order to skip over more or less 100.Fa argv 101entries. 102An 103.Va optind 104value of 0 is reserved for compatibility with GNU 105.Fn getopt . 106.Pp 107In order to use 108.Fn getopt 109to evaluate multiple sets of arguments, or to evaluate a single set of 110arguments multiple times, 111the variable 112.Va optreset 113must be set to 1 before the second and each additional set of calls to 114.Fn getopt , 115and the variable 116.Va optind 117must be reinitialized. 118.Pp 119The 120.Fn getopt 121function returns \-1 when the argument list is exhausted. 122The interpretation of options in the argument list may be cancelled 123by the option 124.Ql -- 125(double dash) which causes 126.Fn getopt 127to signal the end of argument processing and return \-1. 128When all options have been processed (i.e., up to the first non-option 129argument), 130.Fn getopt 131returns \-1. 132.Sh RETURN VALUES 133The 134.Fn getopt 135function returns the next known option character in 136.Fa optstring . 137If 138.Fn getopt 139encounters a character not found in 140.Fa optstring 141or if it detects a missing option argument, 142it returns 143.Sq \&? 144(question mark). 145If 146.Fa optstring 147has a leading 148.Sq \&: 149then a missing option argument causes 150.Sq \&: 151to be returned instead of 152.Sq \&? . 153In either case, the variable 154.Va optopt 155is set to the character that caused the error. 156The 157.Fn getopt 158function returns \-1 when the argument list is exhausted. 159.Sh ENVIRONMENT 160.Bl -tag -width POSIXLY_CORRECTXX 161.It Ev POSIXLY_CORRECT 162If set, a leading 163.Sq - 164in 165.Ar optstring 166is ignored. 167.El 168.Sh EXAMPLES 169The following code accepts the options 170.Fl b 171and 172.Fl f Ar argument 173and adjusts 174.Va argc 175and 176.Va argv 177after option argument processing has completed. 178.Bd -literal -offset indent 179int bflag, ch, fd; 180 181bflag = 0; 182while ((ch = getopt(argc, argv, "bf:")) != -1) { 183 switch (ch) { 184 case 'b': 185 bflag = 1; 186 break; 187 case 'f': 188 if ((fd = open(optarg, O_RDONLY, 0)) == -1) 189 err(1, "%s", optarg); 190 break; 191 default: 192 usage(); 193 /* NOTREACHED */ 194 } 195} 196argc -= optind; 197argv += optind; 198.Ed 199.Sh DIAGNOSTICS 200If the 201.Fn getopt 202function encounters a character not found in the string 203.Fa optstring 204or detects 205a missing option argument, it writes an error message to 206.Em stderr 207and returns 208.Ql \&? . 209Setting 210.Va opterr 211to a zero will disable these error messages. 212If 213.Fa optstring 214has a leading 215.Ql \&: 216then a missing option argument causes a 217.Ql \&: 218to be returned in addition to suppressing any error messages. 219.Pp 220Option arguments are allowed to begin with 221.Ql - ; 222this is reasonable but reduces the amount of error checking possible. 223.Sh SEE ALSO 224.Xr getopt 1 , 225.Xr getopt_long 3 , 226.Xr getsubopt 3 227.Sh STANDARDS 228The 229.Fn getopt 230function implements a superset of the functionality specified by 231.St -p1003.1 . 232.Pp 233The following extensions are supported: 234.Bl -tag -width "xxx" 235.It Li o 236The 237.Va optreset 238variable was added to make it possible to call the 239.Fn getopt 240function multiple times. 241.It Li o 242If the 243.Va optind 244variable is set to 0, 245.Fn getopt 246will behave as if the 247.Va optreset 248variable has been set. 249This is for compatibility with 250.Tn GNU 251.Fn getopt . 252New code should use 253.Va optreset 254instead. 255.It Li o 256If the first character of 257.Fa optstring 258is a plus sign 259.Pq Ql + , 260it will be ignored. 261This is for compatibility with 262.Tn GNU 263.Fn getopt . 264.It Li o 265If the first character of 266.Fa optstring 267is a dash 268.Pq Ql - , 269non-options will be returned as arguments to the option character 270.Ql \e1 . 271This is for compatibility with 272.Tn GNU 273.Fn getopt . 274.It Li o 275A single dash 276.Pq Ql - 277may be specified as a character in 278.Fa optstring , 279however it should 280.Em never 281have an argument associated with it. 282This allows 283.Fn getopt 284to be used with programs that expect 285.Ql - 286as an option flag. 287This practice is wrong, and should not be used in any current development. 288It is provided for backward compatibility 289.Em only . 290Care should be taken not to use 291.Ql - 292as the first character in 293.Fa optstring 294to avoid a semantic conflict with 295.Tn GNU 296.Fn getopt 297semantics (see above). 298By default, a single dash causes 299.Fn getopt 300to return \-1. 301.El 302.Pp 303Historic 304.Bx 305versions of 306.Fn getopt 307set 308.Fa optopt 309to the last option character processed. 310However, this conflicts with 311.St -p1003.1 312which stipulates that 313.Fa optopt 314be set to the last character that caused an error. 315.Sh HISTORY 316The 317.Fn getopt 318function appeared in 319.Bx 4.3 . 320.Sh BUGS 321The 322.Fn getopt 323function was once specified to return 324.Dv EOF 325instead of \-1. 326This was changed by 327.St -p1003.2-92 328to decouple 329.Fn getopt 330from 331.Aq Pa stdio.h . 332.Pp 333It is possible to handle digits as option letters. 334This allows 335.Fn getopt 336to be used with programs that expect a number 337.Pq Dq Li \-3 338as an option. 339This practice is wrong, and should not be used in any current development. 340It is provided for backward compatibility 341.Em only . 342The following code fragment works in most cases and can handle mixed 343number and letter arguments. 344.Bd -literal -offset indent 345int aflag = 0, bflag = 0, ch, lastch = '\e0'; 346int length = -1, newarg = 1, prevoptind = 1; 347 348while ((ch = getopt(argc, argv, "0123456789ab")) != -1) { 349 switch (ch) { 350 case '0': case '1': case '2': case '3': case '4': 351 case '5': case '6': case '7': case '8': case '9': 352 if (newarg || !isdigit(lastch)) 353 length = 0; 354 else if (length > INT_MAX / 10) 355 usage(); 356 length = (length * 10) + (ch - '0'); 357 break; 358 case 'a': 359 aflag = 1; 360 break; 361 case 'b': 362 bflag = 1; 363 break; 364 default: 365 usage(); 366 } 367 lastch = ch; 368 newarg = optind != prevoptind; 369 prevoptind = optind; 370} 371.Ed 372