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