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 April 27, 1995 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. 69For example, an option string 70.Li \&"x" 71recognizes an option 72.Dq Fl x , 73and an option string 74.Li \&"x:" 75recognizes an option and argument 76.Dq Fl x Ar argument . 77It does not matter to 78.Fn getopt 79if a following argument has leading white space. 80.Pp 81On return from 82.Fn getopt , 83.Va optarg 84points to an option argument, if it is anticipated, 85and the variable 86.Va optind 87contains the index to the next 88.Fa argv 89argument for a subsequent call 90to 91.Fn getopt . 92The variable 93.Va optopt 94saves the last 95.Em known 96option character returned by 97.Fn getopt . 98.Pp 99The variables 100.Va opterr 101and 102.Va optind 103are both initialized to 1. 104The 105.Va optind 106variable may be set to another value before a set of calls to 107.Fn getopt 108in order to skip over more or less argv entries. 109.Pp 110In order to use 111.Fn getopt 112to evaluate multiple sets of arguments, or to evaluate a single set of 113arguments multiple times, 114the variable 115.Va optreset 116must be set to 1 before the second and each additional set of calls to 117.Fn getopt , 118and the variable 119.Va optind 120must be reinitialized. 121.Pp 122The 123.Fn getopt 124function returns \-1 when the argument list is exhausted. 125The interpretation of options in the argument list may be cancelled 126by the option 127.Ql -- 128(double dash) which causes 129.Fn getopt 130to signal the end of argument processing and return \-1. 131When all options have been processed (i.e., up to the first non-option 132argument), 133.Fn getopt 134returns \-1. 135.Sh RETURN VALUES 136The 137.Fn getopt 138function returns the next known option character in 139.Fa optstring . 140If 141.Fn getopt 142encounters a character not found in 143.Fa optstring 144or if it detects a missing option argument, 145it returns 146.Ql \&? 147(question mark). 148If 149.Fa optstring 150has a leading 151.Ql \&: 152then a missing option argument causes 153.Ql \&: 154to be returned instead of 155.Ql \&? . 156In either case, the variable 157.Va optopt 158is set to the character that caused the error. 159The 160.Fn getopt 161function returns \-1 when the argument list is exhausted. 162.Sh EXAMPLES 163.Bd -literal -compact 164#include <unistd.h> 165int bflag, ch, fd; 166 167bflag = 0; 168while ((ch = getopt(argc, argv, "bf:")) != -1) { 169 switch (ch) { 170 case 'b': 171 bflag = 1; 172 break; 173 case 'f': 174 if ((fd = open(optarg, O_RDONLY, 0)) \*[Lt] 0) { 175 fprintf(stderr, 176 "myname: %s: %s\en", optarg, strerror(errno)); 177 exit(1); 178 } 179 break; 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} 307.Ed 308