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.38 2006/03/15 02:50:25 ray Exp $ 29.\" 30.Dd December 17, 2002 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 303Unlike 304.Tn GNU 305.Fn getopt , 306.Ox 307does not permute the argument vector to allow non-options to be 308interspersed with options on the command line. 309Programs requiring this behavior should use 310.Xr getopt_long 3 311instead. 312Because of this (and unlike 313.Tn GNU ) , 314the 315.Ox 316.Fn getopt 317supports optional arguments separated by whitespace. 318.Pp 319Historic 320.Bx 321versions of 322.Fn getopt 323set 324.Fa optopt 325to the last option character processed. 326However, this conflicts with 327.St -p1003.1 328which stipulates that 329.Fa optopt 330be set to the last character that caused an error. 331.Sh HISTORY 332The 333.Fn getopt 334function appeared in 335.Bx 4.3 . 336.Sh BUGS 337The 338.Fn getopt 339function was once specified to return 340.Dv EOF 341instead of \-1. 342This was changed by 343.St -p1003.2-92 344to decouple 345.Fn getopt 346from 347.Aq Pa stdio.h . 348.Pp 349It is possible to handle digits as option letters. 350This allows 351.Fn getopt 352to be used with programs that expect a number 353.Pq Dq Li \-3 354as an option. 355This practice is wrong, and should not be used in any current development. 356It is provided for backward compatibility 357.Em only . 358The following code fragment works in most cases and can handle mixed 359number and letter arguments. 360.Bd -literal -offset indent 361int aflag = 0, bflag = 0, ch, lastch = '\e0'; 362int length = -1, newarg = 1, prevoptind = 1; 363 364while ((ch = getopt(argc, argv, "0123456789ab")) != -1) { 365 switch (ch) { 366 case '0': case '1': case '2': case '3': case '4': 367 case '5': case '6': case '7': case '8': case '9': 368 if (newarg || !isdigit(lastch)) 369 length = 0; 370 else if (length > INT_MAX / 10) 371 usage(); 372 length = (length * 10) + (ch - '0'); 373 break; 374 case 'a': 375 aflag = 1; 376 break; 377 case 'b': 378 bflag = 1; 379 break; 380 default: 381 usage(); 382 } 383 lastch = ch; 384 newarg = optind != prevoptind; 385 prevoptind = optind; 386} 387.Ed 388