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$ 34.\" 35.Dd April 27, 1995 36.Dt GETOPT 3 37.Os BSD 4.3 38.Sh NAME 39.Nm getopt 40.Nd get option character from command line argument list 41.Sh LIBRARY 42.Lb libc 43.Sh SYNOPSIS 44.Fd #include <unistd.h> 45.Vt extern char *optarg; 46.Vt extern int optind; 47.Vt extern int optopt; 48.Vt extern int opterr; 49.Vt extern int optreset; 50.Ft int 51.Fn getopt "int argc" "char * const *argv" "const char *optstring" 52.Sh DESCRIPTION 53The 54.Fn getopt 55function incrementally parses a command line argument list 56.Fa argv 57and returns the next 58.Em known 59option character. 60An option character is 61.Em known 62if it has been specified in the string of accepted option characters, 63.Fa optstring . 64.Pp 65The option string 66.Fa optstring 67may contain the following elements: individual characters, and 68characters followed by a colon to indicate an option argument 69is to follow. 70For example, an option string 71.Li "\&""x"" 72recognizes an option 73.Dq Fl x , 74and an option string 75.Li "\&""x:"" 76recognizes an option and argument 77.Dq Fl x Ar argument . 78It does not matter to 79.Fn getopt 80if a following argument has leading white space. 81.Pp 82On return from 83.Fn getopt , 84.Va optarg 85points to an option argument, if it is anticipated, 86and the variable 87.Va optind 88contains the index to the next 89.Fa argv 90argument for a subsequent call 91to 92.Fn getopt . 93The variable 94.Va optopt 95saves the last 96.Em known 97option character returned by 98.Fn getopt . 99.Pp 100The variable 101.Va opterr 102and 103.Va optind 104are both initialized to 1. 105The 106.Va optind 107variable may be set to another value before a set of calls to 108.Fn getopt 109in order to skip over more or less argv entries. 110.Pp 111In order to use 112.Fn getopt 113to evaluate multiple sets of arguments, or to evaluate a single set of 114arguments multiple times, 115the variable 116.Va optreset 117must be set to 1 before the second and each additional set of calls to 118.Fn getopt , 119and the variable 120.Va optind 121must be reinitialized. 122.Pp 123The 124.Fn getopt 125function 126returns \-1 127when the argument list is exhausted, or 128.Ql ? 129if a non-recognized 130option is encountered. 131The interpretation of options in the argument list may be cancelled 132by the option 133.Ql -- 134(double dash) which causes 135.Fn getopt 136to signal the end of argument processing and return \-1. 137When all options have been processed (i.e., up to the first non-option 138argument), 139.Fn getopt 140returns \-1. 141.Sh DIAGNOSTICS 142If the 143.Fn getopt 144function encounters a character not found in the string 145.Va optarg 146or detects 147a missing option argument it writes an error message to the 148.Em stderr 149and returns 150.Ql ? . 151Setting 152.Va opterr 153to a zero will disable these error messages. 154If 155.Va optstring 156has a leading 157.Ql \&: 158then a missing option argument causes a 159.Ql \&: 160to be returned in addition to suppressing any error messages. 161.Pp 162Option arguments are allowed to begin with 163.Dq Li \- ; 164this is reasonable but 165reduces the amount of error checking possible. 166.Sh EXTENSIONS 167The 168.Va optreset 169variable was added to make it possible to call the 170.Fn getopt 171function multiple times. 172This is an extension to the 173.St -p1003.2 174specification. 175.Sh EXAMPLE 176.Bd -literal -compact 177int bflag, ch, fd; 178 179bflag = 0; 180while ((ch = getopt(argc, argv, "bf:")) != -1) 181 switch (ch) { 182 case 'b': 183 bflag = 1; 184 break; 185 case 'f': 186 if ((fd = open(optarg, O_RDONLY, 0)) < 0) 187 err(1, "%s", optarg); 188 break; 189 case '?': 190 default: 191 usage(); 192 } 193argc -= optind; 194argv += optind; 195.Ed 196.Sh HISTORY 197The 198.Fn getopt 199function appeared in 200.Bx 4.3 . 201.Sh BUGS 202The 203.Fn getopt 204function was once specified to return 205.Dv EOF 206instead of \-1. 207This was changed by 208.St -p1003.2-92 209to decouple 210.Fn getopt 211from 212.Pa <stdio.h> . 213.Pp 214A single dash 215.Dq Li - 216may be specified as a character in 217.Fa optstring , 218however it should 219.Em never 220have an argument associated with it. 221This allows 222.Fn getopt 223to be used with programs that expect 224.Dq Li - 225as an option flag. 226This practice is wrong, and should not be used in any current development. 227It is provided for backward compatibility 228.Em only . 229By default, a single dash causes 230.Fn getopt 231to return \-1. 232This is, we believe, compatible with System V. 233.Pp 234It is also possible to handle digits as option letters. 235This allows 236.Fn getopt 237to be used with programs that expect a number 238.Pq Dq Li \&-\&3 239as an option. 240This practice is wrong, and should not be used in any current development. 241It is provided for backward compatibility 242.Em only . 243The following code fragment works in most (but not all) cases. 244.Bd -literal -offset indent 245int length; 246char *p, *ep; 247 248while ((ch = getopt(argc, argv, "0123456789")) != -1) 249 switch (ch) { 250 case '0': case '1': case '2': case '3': case '4': 251 case '5': case '6': case '7': case '8': case '9': 252 p = argv[optind - 1]; 253 if (p[0] == '-' && p[1] == ch && !p[2]) 254 length = strtol(++p, &ep, 10); 255 else if (argv[optind] && argv[optind][1] == ch) { 256 length = strtol((p = argv[optind] + 1), 257 &ep, 10); 258 optind++; 259 optreset = 1; 260 } else 261 usage(); 262 if (*ep != '\0') 263 errx(EX_USAGE, "illegal number -- %s", p); 264 break; 265 } 266.Ed 267