1.\" Copyright (c) 1988, 1991 Regents of the University of California. 2.\" 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 6.16 (Berkeley) 4/19/91 33.\" 34.Dd April 19, 1991 35.Dt GETOPT 3 36.Os BSD 4.3 37.Sh NAME 38.Nm getopt 39.Nd get option letter from argv 40.Sh SYNOPSIS 41.Fd #include <stdlib.h> 42.Vt extern char *optarg 43.Vt extern int optind 44.Vt extern int opterr 45.Ft int 46.Fn getopt "int argc" "char * const *argv" "const char *optstring" 47.Sh DESCRIPTION 48The 49.Fn getopt 50function gets 51the next 52.Em known 53option character from 54.Fa argv . 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 characters; letters and 63letters followed by a colon to indicate an option argument 64is to follow. It does not matter to 65.Fn getopt 66if a following argument has leading white space. 67.Pp 68On return from 69.Fn getopt , 70.Va optarg 71points to an option argument, if it is anticipated, 72and the variable 73.Va optind 74contains the index to the next 75.Fa argv 76argument for a subsequent call 77to 78.Fn getopt . 79.Pp 80The variable 81.Va opterr 82and 83.Va optind 84are both initialized to 1. 85In order to use 86.Fn getopt 87to evaluate multiple sets of arguments, or to evaluate a single set of 88arguments multiple times, 89.Va optind 90must be initialized to the number of argv entries to be skipped in each 91evaluation. 92.Pp 93The 94.Fn getopt 95function 96returns an 97.Dv EOF 98when the argument list is exhausted, or a non-recognized 99option is encountered. 100The interpretation of options in the argument list may be cancelled 101by the option 102.Ql -- 103(double dash) which causes 104.Fn getopt 105to signal the end of argument processing and return an 106.Dv EOF . 107When all options have been processed (i.e., up to the first non-option 108argument), 109.Fn getopt 110returns 111.Dv EOF . 112.Sh DIAGNOSTICS 113If the 114.Fn getopt 115function encounters a character not found in the string 116.Va optarg 117or detects 118a missing option argument 119it writes error message 120.Ql ? 121to the 122.Em stderr . 123Setting 124.Va opterr 125to a zero will disable these error messages. 126.Sh EXAMPLE 127.Bd -literal -compact 128extern char *optarg; 129extern int optind; 130int bflag, ch, fd; 131 132bflag = 0; 133while ((ch = getopt(argc, argv, "bf:")) != EOF) 134 switch(ch) { 135 case 'b': 136 bflag = 1; 137 break; 138 case 'f': 139 if ((fd = open(optarg, O_RDONLY, 0)) < 0) { 140 (void)fprintf(stderr, 141 "myname: unable to read file %s.\en", optarg); 142 exit(1) ; 143 } 144 break; 145 case '?': 146 default: 147 usage(); 148} 149argc -= optind; 150argv += optind; 151.Ed 152.Sh HISTORY 153The 154.Fn getopt 155function appeared 156.Bx 4.3 . 157.Sh BUGS 158Option arguments are allowed to begin with 159.Dq Li \- ; 160this is reasonable but 161reduces the amount of error checking possible. 162.Pp 163A single dash 164.Dq Li - 165may be specified as an character in 166.Fa optstring , 167however it should 168.Em never 169have an argument associated with it. 170This allows 171.Fn getopt 172to be used with programs that expect 173.Dq Li - 174as an option flag. 175This practice is wrong, and should not be used in any current development. 176It is provided for backward compatibility 177.Em only . 178By default, a single dash causes 179.Fn getopt 180to return 181.Dv EOF . 182This is, we believe, compatible with System V. 183.Pp 184It is also possible to handle digits as option letters. 185This allows 186.Fn getopt 187to be used with programs that expect a number 188.Pq Dq Li \&-\&3 189as an option. 190This practice is wrong, and should not be used in any current development. 191It is provided for backward compatibility 192.Em only . 193The following code fragment works fairly well. 194.Bd -literal -offset indent 195int length; 196char *p; 197 198while ((c = getopt(argc, argv, "0123456789")) != EOF) 199 switch (c) { 200 case '0': case '1': case '2': case '3': case '4': 201 case '5': case '6': case '7': case '8': case '9': 202 p = argv[optind - 1]; 203 if (p[0] == '-' && p[1] == ch && !p[2]) 204 length = atoi(++p); 205 else 206 length = atoi(argv[optind] + 1); 207 break; 208 } 209} 210.Ed 211