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