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.25 2003/06/02 20:18:37 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 known option character. 51An option character is 52.Dq known 53if it has been specified in the string of accepted option characters, 54.Fa optstring . 55.Pp 56The option string 57.Fa optstring 58may contain the following elements: individual characters and 59characters followed by a colon to indicate an option argument 60is to follow. 61For example, an option string 62.Qq x 63recognizes an option 64.Fl x , 65and an option string 66.Qq Li x: 67recognizes an option and argument 68.Fl x Ar argument . 69It does not matter to 70.Fn getopt 71if a following argument has leading whitespace. 72.Pp 73On return from 74.Fn getopt , 75.Va optarg 76points to an option argument, if it is anticipated, 77and the variable 78.Va optind 79contains the index to the next 80.Fa argv 81argument for a subsequent call 82to 83.Fn getopt . 84.Pp 85The variables 86.Va opterr 87and 88.Va optind 89are both initialized to 1. 90The 91.Va optind 92variable may be set to another value before a set of calls to 93.Fn getopt 94in order to skip over more or less argv entries. 95.Pp 96In order to use 97.Fn getopt 98to evaluate multiple sets of arguments, or to evaluate a single set of 99arguments multiple times, 100the variable 101.Va optreset 102must be set to 1 before the second and each additional set of calls to 103.Fn getopt , 104and the variable 105.Va optind 106must be reinitialized. 107.Pp 108The 109.Fn getopt 110function returns \-1 when the argument list is exhausted. 111The interpretation of options in the argument list may be cancelled 112by the option 113.Ql -- 114(double dash) which causes 115.Fn getopt 116to signal the end of argument processing and returns \-1. 117When all options have been processed (i.e., up to the first non-option 118argument), 119.Fn getopt 120returns \-1. 121.Sh RETURN VALUES 122The 123.Fn getopt 124function returns the next known option character in 125.Fa optstring . 126If 127.Fn getopt 128encounters a character not found in 129.Fa optstring 130or if it detects a missing option argument, 131it returns 132.Sq ? 133(question mark). 134If 135.Fa optstring 136has a leading 137.Sq \: 138then a missing option argument causes 139.Sq \: 140to be returned instead of 141.Sq ? . 142In either case, the variable 143.Va optopt 144is set to the character that caused the error. 145The 146.Fn getopt 147function returns \-1 when the argument list is exhausted. 148.Sh EXAMPLES 149.Bd -literal -compact 150int bflag, ch, fd; 151 152bflag = 0; 153while ((ch = getopt(argc, argv, "bf:")) != -1) { 154 switch (ch) { 155 case 'b': 156 bflag = 1; 157 break; 158 case 'f': 159 if ((fd = open(optarg, O_RDONLY, 0)) < 0) { 160 (void)fprintf(stderr, 161 "myname: %s: %s\en", optarg, strerror(errno)); 162 exit(1); 163 } 164 break; 165 case '?': 166 default: 167 usage(); 168 } 169} 170argc -= optind; 171argv += optind; 172.Ed 173.Sh DIAGNOSTICS 174If the 175.Fn getopt 176function encounters a character not found in the string 177.Va optstring 178or detects 179a missing option argument it writes an error message to 180.Em stderr 181and returns 182.Ql ? . 183Setting 184.Va opterr 185to a zero will disable these error messages. 186If 187.Va optstring 188has a leading 189.Ql \&: 190then a missing option argument causes a 191.Ql \&: 192to be returned in addition to suppressing any error messages. 193.Pp 194Option arguments are allowed to begin with 195.Ql - ; 196this is reasonable but reduces the amount of error checking possible. 197.Sh SEE ALSO 198.Xr getopt 1 , 199.Xr getopt_long 3 , 200.Xr getsubopt 3 201.Sh EXTENSIONS 202The 203.Va optreset 204variable was added to make it possible to call the 205.Fn getopt 206function multiple times. 207This is an extension to the 208.St -p1003.2 209specification. 210.Sh HISTORY 211The 212.Fn getopt 213function appeared in 214.Bx 4.3 . 215.Sh BUGS 216The 217.Fn getopt 218function was once specified to return 219.Dv EOF 220instead of \-1. 221This was changed by 222.St -p1003.2-92 223to decouple 224.Fn getopt 225from 226.Pa <stdio.h> . 227.Pp 228A single dash 229.Pq Ql - 230may be specified as a character in 231.Fa optstring , 232however it should 233.Em never 234have an argument associated with it. 235This allows 236.Fn getopt 237to be used with programs that expect 238.Ql - 239as an option flag. 240This practice is wrong, and should not be used in any current development. 241It is provided for backward compatibility 242.Em only . 243Care should be taken not to use 244.Ql - 245as the first character in 246.Fa optstring 247to avoid a semantic conflict with 248.Tn GNU 249.Fn getopt , 250which assigns different meaning to an 251.Fa optstring 252that begins with a 253.Ql - . 254By default, a single dash causes 255.Fn getopt 256to return \-1. 257.Pp 258It is also possible to handle digits as option letters. 259This allows 260.Fn getopt 261to be used with programs that expect a number 262.Pq Dq Li \&-\&3 263as an option. 264This practice is wrong, and should not be used in any current development. 265It is provided for backward compatibility 266.Em only . 267The following code fragment works in most cases. 268.Bd -literal -offset indent 269int ch; 270long length; 271char *p; 272 273while ((ch = getopt(argc, argv, "0123456789")) != -1) { 274 switch (ch) { 275 case '0': case '1': case '2': case '3': case '4': 276 case '5': case '6': case '7': case '8': case '9': 277 p = argv[optind - 1]; 278 if (p[0] == '-' && p[1] == ch && !p[2]) 279 length = ch - '0'; 280 else 281 length = strtol(argv[optind] + 1, NULL, 10); 282 break; 283 } 284} 285.Ed 286