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.48 2022/07/25 02:25:55 jsg Exp $ 29.\" 30.Dd $Mdocdate: July 25 2022 $ 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.In 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; except in the case where 77the argument is optional, denoted with two colons, no leading whitespace 78is permitted. 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 . 91.Pp 92The variables 93.Va opterr 94and 95.Va optind 96are both initialized to 1. 97The 98.Va optind 99variable may be set to another value larger than 0 before a set of calls to 100.Fn getopt 101in order to skip over more or less 102.Fa argv 103entries. 104An 105.Va optind 106value of 0 is reserved for compatibility with GNU 107.Fn getopt . 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 returns \-1 when the argument list is exhausted. 124The interpretation of options in the argument list may be cancelled 125by the option 126.Ql -- 127(double dash) which causes 128.Fn getopt 129to signal the end of argument processing and return \-1. 130When all options have been processed (i.e., up to the first non-option 131argument), 132.Fn getopt 133returns \-1. 134.Sh RETURN VALUES 135The 136.Fn getopt 137function returns the next known option character in 138.Fa optstring . 139If 140.Fn getopt 141encounters a character not found in 142.Fa optstring 143or if it detects a missing option argument, 144it returns 145.Sq \&? 146(question mark). 147If 148.Fa optstring 149has a leading 150.Sq \&: 151then a missing option argument causes 152.Sq \&: 153to be returned instead of 154.Sq \&? . 155In either case, the variable 156.Va optopt 157is set to the character that caused the error. 158The 159.Fn getopt 160function returns \-1 when the argument list is exhausted. 161.Sh EXAMPLES 162The following code accepts the options 163.Fl b 164and 165.Fl f Ar argument 166and adjusts 167.Va argc 168and 169.Va argv 170after option argument processing has completed. 171.Bd -literal -offset indent 172int bflag, ch, fd; 173 174bflag = 0; 175while ((ch = getopt(argc, argv, "bf:")) != -1) { 176 switch (ch) { 177 case 'b': 178 bflag = 1; 179 break; 180 case 'f': 181 if ((fd = open(optarg, O_RDONLY)) == -1) 182 err(1, "%s", optarg); 183 break; 184 default: 185 usage(); 186 } 187} 188argc -= optind; 189argv += optind; 190.Ed 191.Sh DIAGNOSTICS 192If the 193.Fn getopt 194function encounters a character not found in the string 195.Fa optstring 196or detects 197a missing option argument, it writes an error message to 198.Em stderr 199and returns 200.Ql \&? . 201Setting 202.Va opterr 203to a zero will disable these error messages. 204If 205.Fa optstring 206has a leading 207.Ql \&: 208then a missing option argument causes a 209.Ql \&: 210to be returned in addition to suppressing any error messages. 211.Pp 212Option arguments are allowed to begin with 213.Ql - ; 214this is reasonable but reduces the amount of error checking possible. 215.Sh SEE ALSO 216.Xr getopt 1 , 217.Xr getopt_long 3 , 218.Xr getsubopt 3 219.Sh STANDARDS 220The 221.Fn getopt 222function implements a superset of the functionality specified by 223.St -p1003.1 . 224.Pp 225The following extensions are supported: 226.Bl -bullet 227.It 228The 229.Va optreset 230variable was added to make it possible to call the 231.Fn getopt 232function multiple times. 233.It 234If the 235.Va optind 236variable is set to 0, 237.Fn getopt 238will behave as if the 239.Va optreset 240variable has been set. 241This is for compatibility with 242.Tn GNU 243.Fn getopt . 244New code should use 245.Va optreset 246instead. 247.It 248If the first character of 249.Fa optstring 250is a plus sign 251.Pq Ql + , 252it will be ignored. 253This is for compatibility with 254.Tn GNU 255.Fn getopt . 256.It 257If the first character of 258.Fa optstring 259is a dash 260.Pq Ql - , 261non-options will be returned as arguments to the option character 262.Ql \e1 . 263This is for compatibility with 264.Tn GNU 265.Fn getopt . 266.It 267A single dash 268.Pq Ql - 269may be specified as a character in 270.Fa optstring , 271however it should 272.Em never 273have an argument associated with it. 274This allows 275.Fn getopt 276to be used with programs that expect 277.Ql - 278as an option flag. 279This practice is wrong, and should not be used in any current development. 280It is provided for backward compatibility 281.Em only . 282Care should be taken not to use 283.Ql - 284as the first character in 285.Fa optstring 286to avoid a semantic conflict with 287.Tn GNU 288.Fn getopt 289semantics (see above). 290By default, a single dash causes 291.Fn getopt 292to return \-1. 293.El 294.Pp 295Historic 296.Bx 297versions of 298.Fn getopt 299set 300.Fa optopt 301to the last option character processed. 302However, this conflicts with 303.St -p1003.1 304which stipulates that 305.Fa optopt 306be set to the last character that caused an error. 307.Sh HISTORY 308The 309.Fn getopt 310function first appeared in 311.At III 312and was reimplemented for 313.Bx 4.3 . 314.Sh BUGS 315The 316.Fn getopt 317function was once specified to return 318.Dv EOF 319instead of \-1. 320This was changed by 321.St -p1003.2-92 322to decouple 323.Fn getopt 324from 325.In stdio.h . 326.Pp 327It is possible to handle digits as option letters. 328This allows 329.Fn getopt 330to be used with programs that expect a number 331.Pq Dq Li \-3 332as an option. 333This practice is wrong, and should not be used in any current development. 334It is provided for backward compatibility 335.Em only . 336The following code fragment works in most cases and can handle mixed 337number and letter arguments. 338.Bd -literal -offset indent 339int aflag = 0, bflag = 0, ch, lastch = '\e0'; 340int length = -1, newarg = 1, prevoptind = 1; 341 342while ((ch = getopt(argc, argv, "0123456789ab")) != -1) { 343 switch (ch) { 344 case '0': case '1': case '2': case '3': case '4': 345 case '5': case '6': case '7': case '8': case '9': 346 if (newarg || !isdigit(lastch)) 347 length = 0; 348 else if (length > INT_MAX / 10) 349 usage(); 350 length = (length * 10) + (ch - '0'); 351 break; 352 case 'a': 353 aflag = 1; 354 break; 355 case 'b': 356 bflag = 1; 357 break; 358 default: 359 usage(); 360 } 361 lastch = ch; 362 newarg = optind != prevoptind; 363 prevoptind = optind; 364} 365.Ed 366