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.\" from: @(#)getopt.3 6.16 (Berkeley) 4/19/91 33.\" 386BSD: $Id: getopt.3,v 1.2 93/03/22 17:09:43 bill Exp $ 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 an appropriate error message 120on the 121.Em stderr 122stream, and returns 123.Ql ? 124as a option character for the errant option. 125Setting 126.Va opterr 127to a zero will disable these error messages. 128.Sh EXAMPLE 129.Bd -literal -compact 130extern char *optarg; 131extern int optind; 132int bflag, ch, fd; 133 134bflag = 0; 135while ((ch = getopt(argc, argv, "bf:")) != EOF) 136 switch(ch) { 137 case 'b': 138 bflag = 1; 139 break; 140 case 'f': 141 if ((fd = open(optarg, O_RDONLY, 0)) < 0) { 142 (void)fprintf(stderr, 143 "myname: unable to read file %s.\en", optarg); 144 exit(1) ; 145 } 146 break; 147 case '?': 148 default: 149 usage(); 150} 151argc -= optind; 152argv += optind; 153.Ed 154.Sh HISTORY 155The 156.Fn getopt 157function appeared 158.Bx 4.3 . 159.Sh BUGS 160Option arguments are allowed to begin with 161.Dq Li \- ; 162this is reasonable but 163reduces the amount of error checking possible. 164.Pp 165A single dash 166.Dq Li - 167may be specified as an character in 168.Fa optstring , 169however it should 170.Em never 171have an argument associated with it. 172This allows 173.Fn getopt 174to be used with programs that expect 175.Dq Li - 176as an option flag. 177This practice is wrong, and should not be used in any current development. 178It is provided for backward compatibility 179.Em only . 180By default, a single dash causes 181.Fn getopt 182to return 183.Dv EOF . 184This is, we believe, compatible with System V. 185.Pp 186It is also possible to handle digits as option letters. 187This allows 188.Fn getopt 189to be used with programs that expect a number 190.Pq Dq Li \&-\&3 191as an option. 192This practice is wrong, and should not be used in any current development. 193It is provided for backward compatibility 194.Em only . 195The following code fragment works fairly well. 196.Bd -literal -offset indent 197int length; 198char *p; 199 200while ((c = getopt(argc, argv, "0123456789")) != EOF) 201 switch (c) { 202 case '0': case '1': case '2': case '3': case '4': 203 case '5': case '6': case '7': case '8': case '9': 204 p = argv[optind - 1]; 205 if (p[0] == '-' && p[1] == ch && !p[2]) 206 length = atoi(++p); 207 else 208 length = atoi(argv[optind] + 1); 209 break; 210 } 211} 212.Ed 213