1.\" Copyright (c) 1988, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)getopt.3 8.5 (Berkeley) 4/27/95 33.\" $FreeBSD: src/lib/libc/stdlib/getopt.3,v 1.11.2.8 2001/12/14 18:33:58 ru Exp $ 34.\" $DragonFly: src/lib/libc/stdlib/getopt.3,v 1.5 2006/05/26 19:39:37 swildner Exp $ 35.\" 36.Dd April 27, 1995 37.Dt GETOPT 3 38.Os 39.Sh NAME 40.Nm getopt 41.Nd get option character from command line argument list 42.Sh LIBRARY 43.Lb libc 44.Sh SYNOPSIS 45.In unistd.h 46.Vt extern char *optarg ; 47.Vt extern int optind ; 48.Vt extern int optopt ; 49.Vt extern int opterr ; 50.Vt extern int optreset ; 51.Ft int 52.Fn getopt "int argc" "char * const *argv" "const char *optstring" 53.Sh DESCRIPTION 54The 55.Fn getopt 56function incrementally parses a command line argument list 57.Fa argv 58and returns the next 59.Em known 60option character. 61An option character is 62.Em known 63if it has been specified in the string of accepted option characters, 64.Fa optstring . 65.Pp 66The option string 67.Fa optstring 68may contain the following elements: individual characters, and 69characters followed by a colon to indicate an option argument 70is to follow. 71For example, an option string 72.Li "\&""x"" 73recognizes an option 74.Dq Fl x , 75and an option string 76.Li "\&""x:"" 77recognizes an option and argument 78.Dq Fl x Ar argument . 79It does not matter to 80.Fn getopt 81if a following argument has leading white space. 82.Pp 83On return from 84.Fn getopt , 85.Va optarg 86points to an option argument, if it is anticipated, 87and the variable 88.Va optind 89contains the index to the next 90.Fa argv 91argument for a subsequent call 92to 93.Fn getopt . 94The variable 95.Va optopt 96saves the last 97.Em known 98option character returned by 99.Fn getopt . 100.Pp 101The variable 102.Va opterr 103and 104.Va optind 105are both initialized to 1. 106The 107.Va optind 108variable may be set to another value before a set of calls to 109.Fn getopt 110in order to skip over more or less argv entries. 111.Pp 112In order to use 113.Fn getopt 114to evaluate multiple sets of arguments, or to evaluate a single set of 115arguments multiple times, 116the variable 117.Va optreset 118must be set to 1 before the second and each additional set of calls to 119.Fn getopt , 120and the variable 121.Va optind 122must be reinitialized. 123.Pp 124The 125.Fn getopt 126function 127returns \-1 128when the argument list is exhausted, or 129.Ql ?\& 130if a non-recognized 131option is encountered. 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 EXAMPLES 143.Bd -literal -compact 144int bflag, ch, fd; 145 146bflag = 0; 147while ((ch = getopt(argc, argv, "bf:")) != -1) { 148 switch (ch) { 149 case 'b': 150 bflag = 1; 151 break; 152 case 'f': 153 if ((fd = open(optarg, O_RDONLY, 0)) < 0) 154 err(1, "%s", optarg); 155 break; 156 default: 157 usage(); 158 } 159} 160argc -= optind; 161argv += optind; 162.Ed 163.Sh DIAGNOSTICS 164If the 165.Fn getopt 166function encounters a character not found in the string 167.Va optstring 168or detects 169a missing option argument it writes an error message to the 170.Em stderr 171and returns 172.Ql ?\& . 173Setting 174.Va opterr 175to a zero will disable these error messages. 176If 177.Va optstring 178has a leading 179.Ql \&: 180then a missing option argument causes a 181.Ql \&: 182to be returned in addition to suppressing any error messages. 183.Pp 184Option arguments are allowed to begin with 185.Dq Li \- ; 186this is reasonable but 187reduces the amount of error checking possible. 188.Sh EXTENSIONS 189The 190.Va optreset 191variable was added to make it possible to call the 192.Fn getopt 193function multiple times. 194This is an extension to the 195.St -p1003.2 196specification. 197.Sh HISTORY 198The 199.Fn getopt 200function appeared in 201.Bx 4.3 . 202.Sh BUGS 203The 204.Fn getopt 205function was once specified to return 206.Dv EOF 207instead of \-1. 208This was changed by 209.St -p1003.2-92 210to decouple 211.Fn getopt 212from 213.In stdio.h . 214.Pp 215A single dash 216.Dq Li - 217may be specified as a character in 218.Fa optstring , 219however it should 220.Em never 221have an argument associated with it. 222This allows 223.Fn getopt 224to be used with programs that expect 225.Dq Li - 226as an option flag. 227This practice is wrong, and should not be used in any current development. 228It is provided for backward compatibility 229.Em only . 230By default, a single dash causes 231.Fn getopt 232to return \-1. 233This is, we believe, compatible with System V. 234.Pp 235It is also possible to handle digits as option letters. 236This allows 237.Fn getopt 238to be used with programs that expect a number 239.Pq Dq Li \&-\&3 240as an option. 241This practice is wrong, and should not be used in any current development. 242It is provided for backward compatibility 243.Em only . 244The following code fragment works in most (but not all) cases. 245.Bd -literal -offset indent 246int length; 247char *p, *ep; 248 249while ((ch = getopt(argc, argv, "0123456789")) != -1) { 250 switch (ch) { 251 case '0': case '1': case '2': case '3': case '4': 252 case '5': case '6': case '7': case '8': case '9': 253 p = argv[optind - 1]; 254 if (p[0] == '-' && p[1] == ch && !p[2]) 255 length = strtol(++p, &ep, 10); 256 else if (argv[optind] && argv[optind][1] == ch) { 257 length = strtol((p = argv[optind] + 1), 258 &ep, 10); 259 optind++; 260 optreset = 1; 261 } else 262 usage(); 263 if (*ep != '\0') 264 errx(EX_USAGE, "illegal number -- %s", p); 265 break; 266 } 267} 268.Ed 269