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