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