1.\" $NetBSD: getopt.3,v 1.14 1998/07/29 03:38:30 ross 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. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)getopt.3 8.5 (Berkeley) 4/27/95 35.\" 36.Dd April 27, 1995 37.Dt GETOPT 3 38.Os BSD 4.3 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.Fd #include <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 a non-recognized 129option is encountered. 130The interpretation of options in the argument list may be cancelled 131by the option 132.Ql -- 133(double dash) which causes 134.Fn getopt 135to signal the end of argument processing and returns \-1. 136When all options have been processed (i.e., up to the first non-option 137argument), 138.Fn getopt 139returns \-1. 140.Sh DIAGNOSTICS 141If the 142.Fn getopt 143function encounters a character not found in the string 144.Fa optstring 145or detects 146a missing option argument it writes an error message to 147.Va stderr 148and returns 149.Ql ? . 150Setting 151.Va opterr 152to a zero will disable these error messages. 153If 154.Va optstring 155has a leading 156.Ql \&: 157then a missing option argument causes a 158.Ql \&: 159to be returned in addition to suppressing any error messages. 160.Pp 161Option arguments are allowed to begin with 162.Dq Li \- ; 163this is reasonable but 164reduces the amount of error checking possible. 165.Sh EXTENSIONS 166The 167.Va optreset 168variable was added to make it possible to call the 169.Fn getopt 170function multiple times. 171This is an extension to the 172.St -p1003.2 173specification. 174.Sh EXAMPLE 175.Bd -literal -compact 176extern char *optarg; 177extern int optind; 178int bflag, ch, fd; 179 180bflag = 0; 181while ((ch = getopt(argc, argv, "bf:")) != -1) 182 switch(ch) { 183 case 'b': 184 bflag = 1; 185 break; 186 case 'f': 187 if ((fd = open(optarg, O_RDONLY, 0)) < 0) { 188 (void)fprintf(stderr, 189 "myname: %s: %s\en", optarg, strerror(errno)); 190 exit(1); 191 } 192 break; 193 case '?': 194 default: 195 usage(); 196} 197argc -= optind; 198argv += optind; 199.Ed 200.Sh HISTORY 201The 202.Fn getopt 203function appeared 204.Bx 4.3 . 205.Sh BUGS 206The 207.Fn getopt 208function was once specified to return 209.Dv EOF 210instead of \-1. 211This was changed by 212.St -p1003.2-92 213to decouple 214.Fn getopt 215from 216.Pa <stdio.h> . 217.Pp 218A single dash 219.Dq Li - 220may be specified as a character in 221.Fa optstring , 222however it should 223.Em never 224have an argument associated with it. 225This allows 226.Fn getopt 227to be used with programs that expect 228.Dq Li - 229as an option flag. 230This practice is wrong, and should not be used in any current development. 231It is provided for backward compatibility 232.Em only . 233By default, a single dash causes 234.Fn getopt 235to return \-1. 236This is, we believe, compatible with System V. 237.Pp 238It is also possible to handle digits as option letters. 239This allows 240.Fn getopt 241to be used with programs that expect a number 242.Pq Dq Li \&-\&3 243as an option. 244This practice is wrong, and should not be used in any current development. 245It is provided for backward compatibility 246.Em only . 247The following code fragment works in most cases. 248.Bd -literal -offset indent 249int length; 250char *p; 251 252while ((c = getopt(argc, argv, "0123456789")) != -1) 253 switch (c) { 254 case '0': case '1': case '2': case '3': case '4': 255 case '5': case '6': case '7': case '8': case '9': 256 p = argv[optind - 1]; 257 if (p[0] == '-' && p[1] == ch && !p[2]) 258 length = atoi(++p); 259 else 260 length = atoi(argv[optind] + 1); 261 break; 262 } 263} 264.Ed 265