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.28 2003/09/22 23:47:26 millert 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 optind; 40.Vt extern int optopt; 41.Vt extern int opterr; 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 66.Px . 67For example, an option string 68.Qq x 69recognizes an option 70.Fl x , 71and an option string 72.Qq Li x: 73recognizes an option and argument 74.Fl x Ar argument . 75It does not matter to 76.Fn getopt 77if a following argument has leading whitespace. 78.Pp 79On return from 80.Fn getopt , 81.Va optarg 82points to an option argument, if it is anticipated, 83and the variable 84.Va optind 85contains the index to the next 86.Fa argv 87argument for a subsequent call 88to 89.Fn getopt . 90.Pp 91The variables 92.Va opterr 93and 94.Va optind 95are both initialized to 1. 96The 97.Va optind 98variable may be set to another value before a set of calls to 99.Fn getopt 100in order to skip over more or less argv entries. 101.Pp 102In order to use 103.Fn getopt 104to evaluate multiple sets of arguments, or to evaluate a single set of 105arguments multiple times, 106the variable 107.Va optreset 108must be set to 1 before the second and each additional set of calls to 109.Fn getopt , 110and the variable 111.Va optind 112must be reinitialized. 113.Pp 114The 115.Fn getopt 116function returns \-1 when the argument list is exhausted. 117The interpretation of options in the argument list may be cancelled 118by the option 119.Ql -- 120(double dash) which causes 121.Fn getopt 122to signal the end of argument processing and return \-1. 123When all options have been processed (i.e., up to the first non-option 124argument), 125.Fn getopt 126returns \-1. 127.Sh RETURN VALUES 128The 129.Fn getopt 130function returns the next known option character in 131.Fa optstring . 132If 133.Fn getopt 134encounters a character not found in 135.Fa optstring 136or if it detects a missing option argument, 137it returns 138.Sq \&? 139(question mark). 140If 141.Fa optstring 142has a leading 143.Sq \&: 144then a missing option argument causes 145.Sq \&: 146to be returned instead of 147.Sq \&? . 148In either case, the variable 149.Va optopt 150is set to the character that caused the error. 151The 152.Fn getopt 153function returns \-1 when the argument list is exhausted. 154.Sh ENVIRONMENT 155.Bl -tag -width POSIXLY_CORRECTXX 156.It Ev POSIXLY_CORRECT 157If set, a leading 158.Sq - 159in 160.Ar optstring 161is ignored. 162.El 163.Sh EXAMPLES 164.Bd -literal -compact 165extern char *optarg; 166extern int optind; 167int bflag, ch, fd; 168 169bflag = 0; 170while ((ch = getopt(argc, argv, "bf:")) != -1) { 171 switch (ch) { 172 case 'b': 173 bflag = 1; 174 break; 175 case 'f': 176 if ((fd = open(optarg, O_RDONLY, 0)) < 0) { 177 (void)fprintf(stderr, 178 "myname: %s: %s\en", optarg, strerror(errno)); 179 exit(1); 180 } 181 break; 182 case '?': 183 default: 184 usage(); 185 } 186} 187argc -= optind; 188argv += optind; 189.Ed 190.Sh DIAGNOSTICS 191If the 192.Fn getopt 193function encounters a character not found in the string 194.Fa optstring 195or detects 196a missing option argument it writes an error message to 197.Em stderr 198and returns 199.Ql \&? . 200Setting 201.Va opterr 202to a zero will disable these error messages. 203If 204.Fa optstring 205has a leading 206.Ql \&: 207then a missing option argument causes a 208.Ql \&: 209to be returned in addition to suppressing any error messages. 210.Pp 211Option arguments are allowed to begin with 212.Ql - ; 213this is reasonable but reduces the amount of error checking possible. 214.Sh SEE ALSO 215.Xr getopt 1 , 216.Xr getopt_long 3 , 217.Xr getsubopt 3 218.Sh STANDARDS 219The 220.Fn getopt 221function implements a superset of the functionality specified by 222.St -p1003.1 . 223.Pp 224The following extensions are supported: 225.Bl -tag -width "xxx" 226.It Li o 227The 228.Va optreset 229variable was added to make it possible to call the 230.Fn getopt 231function multiple times. 232.It Li o 233If the first character of 234.Fa optstring 235is a plus sign 236.Pq Ql + , 237it will be ignored. 238This is for compatibility with 239.Tn GNU 240.Fn getopt . 241.It Li o 242If the first character of 243.Fa optstring 244is a dash 245.Pq Ql - , 246non-options will be returned as arguments to the option character 247.Ql \e1 . 248This is for compatibility with 249.Tn GNU 250.Fn getopt . 251.It Li o 252A single dash 253.Pq Ql - 254may be specified as a character in 255.Fa optstring , 256however it should 257.Em never 258have an argument associated with it. 259This allows 260.Fn getopt 261to be used with programs that expect 262.Ql - 263as an option flag. 264This practice is wrong, and should not be used in any current development. 265It is provided for backward compatibility 266.Em only . 267Care should be taken not to use 268.Ql - 269as the first character in 270.Fa optstring 271to avoid a semantic conflict with 272.Tn GNU 273.Fn getopt 274semantics (see above). 275By default, a single dash causes 276.Fn getopt 277to return \-1. 278.El 279.Pp 280Unlike 281.Tn GNU 282.Fn getopt , 283.Ox 284does not permute the argument vector to allow non-options to be 285interspersed with options on the command line. 286Programs requiring this behavior should use 287.Xr getopt_long 3 288instead. 289Because of this (and unlike 290.Tn GNU ) , 291the 292.Ox 293.Fn getopt 294supports optional arguments separated by whitespace. 295.Sh HISTORY 296The 297.Fn getopt 298function appeared in 299.Bx 4.3 . 300.Sh BUGS 301The 302.Fn getopt 303function was once specified to return 304.Dv EOF 305instead of \-1. 306This was changed by 307.St -p1003.2-92 308to decouple 309.Fn getopt 310from 311.Aq Pa stdio.h . 312.Pp 313It is possible to handle digits as option letters. 314This allows 315.Fn getopt 316to be used with programs that expect a number 317.Pq Dq Li \-3 318as an option. 319This practice is wrong, and should not be used in any current development. 320It is provided for backward compatibility 321.Em only . 322The following code fragment works in most cases. 323.Bd -literal -offset indent 324int ch; 325long length; 326char *p; 327 328while ((ch = getopt(argc, argv, "0123456789")) != -1) { 329 switch (ch) { 330 case '0': case '1': case '2': case '3': case '4': 331 case '5': case '6': case '7': case '8': case '9': 332 p = argv[optind - 1]; 333 if (p[0] == '-' && p[1] == ch && !p[2]) 334 length = ch - '0'; 335 else 336 length = strtol(argv[optind] + 1, NULL, 10); 337 break; 338 } 339} 340.Ed 341