1.\" $NetBSD: getopt.3,v 1.31 2003/09/23 10:26:54 wiz Exp $ 2.\" 3.\" Copyright (c) 1988, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)getopt.3 8.5 (Berkeley) 4/27/95 31.\" $FreeBSD: src/lib/libc/stdlib/getopt.3,v 1.26 2007/01/09 00:28:10 imp Exp $ 32.\" 33.Dd February 19, 2022 34.Dt GETOPT 3 35.Os 36.Sh NAME 37.Nm getopt 38.Nd get option character from command line argument list 39.Sh LIBRARY 40.Lb libc 41.Sh SYNOPSIS 42.In unistd.h 43.Vt extern char *optarg ; 44.Vt extern int optind ; 45.Vt extern int optopt ; 46.Vt extern int opterr ; 47.Vt extern int optreset ; 48.Ft int 49.Fn getopt "int argc" "char * const argv[]" "const char *optstring" 50.Sh DESCRIPTION 51The 52.Fn getopt 53function incrementally parses a command line argument list 54.Fa argv 55and returns the next 56.Em known 57option character. 58An option character is 59.Em known 60if it has been specified in the string of accepted option characters, 61.Fa optstring . 62.Pp 63The option string 64.Fa optstring 65may contain the following elements: 66.Bl -bullet -offset indent 67.It 68An individual character. 69For example, an option string 70.Li \&"x" 71recognizes an option 72.Dq Fl x . 73.It 74A character followed by a colon, which indicates the option requires 75an argument. 76It does not matter if a following argument has leading white space. 77For example, an option string 78.Li \&"x:" 79recognizes an option and argument 80.Dq Fl x Ar argument 81or 82.Dq Fl x Ns Ar argument . 83.It 84A character followed by two colons, which indicates the option argument 85is optional. 86The following argument must be in the 87.Em same 88word as the option name itself. 89The 90.Va optarg 91is set to the rest of the 92.Em current 93.Fa argv 94word, or 95.Dv NULL 96if there were no more characters in the current word. 97This is a 98.Tn GNU 99extension. 100For example, an option string 101.Li \&"x::" 102recognizes an option 103.Dq Fl x 104or an option and argument 105.Dq Fl x Ns Ar argument . 106.El 107.Pp 108On return from 109.Fn getopt , 110.Va optarg 111points to an option argument, if it is anticipated, 112and the variable 113.Va optind 114contains the index to the next 115.Fa argv 116argument for a subsequent call 117to 118.Fn getopt . 119The variable 120.Va optopt 121saves the last 122.Em known 123option character returned by 124.Fn getopt . 125.Pp 126The variables 127.Va opterr 128and 129.Va optind 130are both initialized to 1. 131The 132.Va optind 133variable may be set to another value before a set of calls to 134.Fn getopt 135in order to skip over more or less 136.Fa argv 137entries. 138.Pp 139In order to use 140.Fn getopt 141to evaluate multiple sets of arguments, or to evaluate a single set of 142arguments multiple times, 143the variable 144.Va optreset 145must be set to 1 before the second and each additional set of calls to 146.Fn getopt , 147and the variable 148.Va optind 149must be reinitialized. 150.Pp 151The 152.Fn getopt 153function returns \-1 when the argument list is exhausted. 154The interpretation of options in the argument list may be cancelled 155by the option 156.Ql -- 157(double dash) which causes 158.Fn getopt 159to signal the end of argument processing and return \-1. 160When all options have been processed (i.e., up to the first non-option 161argument), 162.Fn getopt 163returns \-1. 164.Sh RETURN VALUES 165The 166.Fn getopt 167function returns the next known option character in 168.Fa optstring . 169If 170.Fn getopt 171encounters a character not found in 172.Fa optstring 173or if it detects a missing option argument, 174it returns 175.Ql \&? 176(question mark). 177If 178.Fa optstring 179has a leading 180.Ql \&: 181then a missing option argument causes 182.Ql \&: 183to be returned instead of 184.Ql \&? . 185In either case, the variable 186.Va optopt 187is set to the character that caused the error. 188The 189.Fn getopt 190function returns \-1 when the argument list is exhausted. 191.Sh EXAMPLES 192.Bd -literal -compact 193#include <unistd.h> 194int bflag, ch, fd; 195 196bflag = 0; 197while ((ch = getopt(argc, argv, "bf:")) != -1) { 198 switch (ch) { 199 case 'b': 200 bflag = 1; 201 break; 202 case 'f': 203 if ((fd = open(optarg, O_RDONLY, 0)) \*[Lt] 0) { 204 fprintf(stderr, 205 "myname: %s: %s\en", optarg, strerror(errno)); 206 exit(1); 207 } 208 break; 209 default: 210 usage(); 211 } 212} 213argc -= optind; 214argv += optind; 215.Ed 216.Sh DIAGNOSTICS 217If the 218.Fn getopt 219function encounters a character not found in the string 220.Fa optstring 221or detects 222a missing option argument it writes an error message to the 223.Dv stderr 224and returns 225.Ql \&? . 226Setting 227.Va opterr 228to a zero will disable these error messages. 229If 230.Fa optstring 231has a leading 232.Ql \&: 233then a missing option argument causes a 234.Ql \&: 235to be returned in addition to suppressing any error messages. 236.Pp 237Option arguments are allowed to begin with 238.Dq Li \- ; 239this is reasonable but reduces the amount of error checking possible. 240.Sh SEE ALSO 241.Xr getopt 1 , 242.Xr getopt_long 3 , 243.Xr getsubopt 3 244.Sh STANDARDS 245The 246.Va optreset 247variable was added to make it possible to call the 248.Fn getopt 249function multiple times. 250This is an extension to the 251.St -p1003.2 252specification. 253.Sh HISTORY 254The 255.Fn getopt 256function appeared in 257.Bx 4.3 . 258.Sh BUGS 259The 260.Fn getopt 261function was once specified to return 262.Dv EOF 263instead of \-1. 264This was changed by 265.St -p1003.2-92 266to decouple 267.Fn getopt 268from 269.In stdio.h . 270.Pp 271A single dash 272.Dq Li - 273may be specified as a character in 274.Fa optstring , 275however it should 276.Em never 277have an argument associated with it. 278This allows 279.Fn getopt 280to be used with programs that expect 281.Dq Li - 282as an option flag. 283This practice is wrong, and should not be used in any current development. 284It is provided for backward compatibility 285.Em only . 286Care should be taken not to use 287.Ql \&- 288as the first character in 289.Fa optstring 290to avoid a semantic conflict with 291.Tn GNU 292.Fn getopt , 293which assigns different meaning to an 294.Fa optstring 295that begins with a 296.Ql \&- . 297By default, a single dash causes 298.Fn getopt 299to return \-1. 300.Pp 301It is also possible to handle digits as option letters. 302This allows 303.Fn getopt 304to be used with programs that expect a number 305.Pq Dq Li \&-\&3 306as an option. 307This practice is wrong, and should not be used in any current development. 308It is provided for backward compatibility 309.Em only . 310The following code fragment works in most cases. 311.Bd -literal -offset indent 312int ch; 313long length; 314char *p, *ep; 315 316while ((ch = getopt(argc, argv, "0123456789")) != -1) { 317 switch (ch) { 318 case '0': case '1': case '2': case '3': case '4': 319 case '5': case '6': case '7': case '8': case '9': 320 p = argv[optind - 1]; 321 if (p[0] == '-' \*[Am]\*[Am] p[1] == ch \*[Am]\*[Am] !p[2]) { 322 length = ch - '0'; 323 ep = ""; 324 } else if (argv[optind] \*[Am]\*[Am] argv[optind][1] == ch) { 325 length = strtol((p = argv[optind] + 1), 326 \*[Am]ep, 10); 327 optind++; 328 optreset = 1; 329 } else 330 usage(); 331 if (*ep != '\e0') 332 errx(EX_USAGE, "illegal number -- %s", p); 333 break; 334 } 335} 336.Ed 337