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