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