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