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.5 1993/10/13 17:23:39 jtc 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 <unistd.h> 43.Ft int 44.Fn getopt "int argc" "char * const *argv" "const char *optstring" 45.Vt extern char *optarg; 46.Vt extern int optind; 47.Vt extern int opterr; 48.Vt extern int optopt; 49.Sh DESCRIPTION 50The 51.Fn getopt 52function gets 53the next 54.Em known 55option character from 56.Fa argv . 57An option character is 58.Em known 59if it has been specified in the string of accepted option characters, 60.Fa optstring . 61.Pp 62The option string 63.Fa optstring 64may contain the following characters; letters and 65letters followed by a colon to indicate an option argument 66is to follow. It does not matter to 67.Fn getopt 68if a following argument has leading white space. 69.Pp 70On return from 71.Fn getopt , 72.Va optarg 73points to an option argument, if it is anticipated, 74and the variable 75.Va optind 76contains the index to the next 77.Fa argv 78argument for a subsequent call 79to 80.Fn getopt . 81.Pp 82The variable 83.Va opterr 84and 85.Va optind 86are both initialized to 1. 87In order to use 88.Fn getopt 89to evaluate multiple sets of arguments, or to evaluate a single set of 90arguments multiple times, 91.Va optind 92must be initialized to the number of argv entries to be skipped in each 93evaluation. 94.Pp 95The 96.Fn getopt 97function 98returns \-1 99when the argument list is exhausted. 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 \-1. 106When all options have been processed (i.e., up to the first non-option 107argument), 108.Fn getopt 109returns \-1. 110.Sh DIAGNOSTICS 111If the 112.Fn getopt 113function encounters an option character that is not contained in 114.Fa optstring , 115it returns a question mark 116.Pq ? 117character. 118If it detects a missing option argument, it returns a colon 119.Pq \: 120character if the first character of 121.Fa optstring 122is a colon, otherwise it returns a question mark. 123In either case, a diagnostic message is written to 124.Em stderr 125unless the application has set 126.Va opterr 127to zero or the first character of 128.Fa optstring 129is a colon. 130.Sh EXAMPLE 131.\" The following example comes from section E.9.7 of the IEEE 1003.2-90 132.\" standard (POSIX.2). 133The following code fragment shows how one might process the arguments for 134a utility that can take the mutually exclusive options 135.Em a 136and 137.Em b 138and the options 139.Em f 140and 141.Em o , 142both of which require arguments: 143.Pp 144.Bd -literal -compact 145#include <unistd.h> 146 147int 148main (argc, argv) 149 int argc; 150 char *argv[]; 151{ 152 int c, bflg, aflg, errflg = 0; 153 char *ifile, *ofile; 154 extern char *optarg; 155 extern int optind, optopt; 156 157 . . . 158 159 while ((c = getopt(argc, argv, ":abf:o:")) != -1) { 160 switch(ch) { 161 case 'a': 162 if (bflg) 163 errflg = 1; 164 else 165 aflg = 1; 166 break; 167 case 'b': 168 if (aflg) 169 errflg = 1; 170 else 171 bflg = 1; 172 break; 173 case 'f': 174 ifile = optarg; 175 break; 176 case 'o': 177 ofile = optarg; 178 break; 179 case ':': /* -f or -o without option-arg */ 180 fprintf (stderr, 181 "Option -%c requires an option-argument\\n", 182 optopt); 183 errflg = 1; 184 break; 185 case '?': 186 fprintf (stderr, 187 "Unrecognized option: -%c\\n", 188 optopt); 189 errflg = 1; 190 break; 191 } 192 } 193 194 if (errflg) { 195 fprintf (stderr, "usage: . . .\\n"); 196 exit (2); 197 } 198 199 argc -= optind; 200 argv += optind; 201 202 . . . 203 204} 205.Ed 206.Sh STANDARDS 207The 208.Fn getopt 209function conforms to 210.St -p1003.2-92 . 211.Sh HISTORY 212The 213.Fn getopt 214function appeared 215.Bx 4.3 . 216.Sh BUGS 217The 218.Fn getopt 219function was once specified to return 220.Dv EOF 221instead of \-1. 222This was changed by 223.St -p1003.2-92 224to decouple 225.Fn getopt 226from 227.Pa <stdio.h> . 228.Pp 229Option arguments are allowed to begin with 230.Dq Li \- ; 231this is reasonable but 232reduces the amount of error checking possible. 233.Pp 234A single dash 235.Dq Li - 236may be specified as an character in 237.Fa optstring , 238however it should 239.Em never 240have an argument associated with it. 241This allows 242.Fn getopt 243to be used with programs that expect 244.Dq Li - 245as an option flag. 246This practice is wrong, and should not be used in any current development. 247It is provided for backward compatibility 248.Em only . 249By default, a single dash causes 250.Fn getopt 251to returns \-1. 252This is, we believe, compatible with System V. 253.Pp 254It is also possible to handle digits as option letters. 255This allows 256.Fn getopt 257to be used with programs that expect a number 258.Pq Dq Li \&-\&3 259as an option. 260This practice is wrong, and should not be used in any current development. 261It is provided for backward compatibility 262.Em only . 263The following code fragment works fairly well. 264.Bd -literal -offset indent 265int length; 266char *p; 267 268while ((c = getopt(argc, argv, "0123456789")) != -1) 269 switch (c) { 270 case '0': case '1': case '2': case '3': case '4': 271 case '5': case '6': case '7': case '8': case '9': 272 p = argv[optind - 1]; 273 if (p[0] == '-' && p[1] == ch && !p[2]) 274 length = atoi(++p); 275 else 276 length = atoi(argv[optind] + 1); 277 break; 278 } 279} 280.Ed 281