| 1 | .TH getopt 3 |
| 2 | .SH NAME |
| 3 | getopt \- get option character from command line |
| 4 | .SH SYNTAX |
| 5 | .B #include <getopt.h> |
| 6 | |
| 7 | char *\fBoptarg\fP; |
| 8 | .br |
| 9 | int \fBoptind\fP; |
| 10 | .br |
| 11 | int \fBoptpos\fP; |
| 12 | .br |
| 13 | int \fBopteof\fP; |
| 14 | .br |
| 15 | int \fBoptproblem\fP; |
| 16 | .br |
| 17 | char *\fBoptprogname\fP; |
| 18 | .br |
| 19 | int \fBopterr\fP; |
| 20 | |
| 21 | int \fBgetopt(\fP\fIargc,argv,opts\fR\fB)\fP; |
| 22 | |
| 23 | int \fIargc\fR; |
| 24 | .br |
| 25 | char **\fIargv\fR; |
| 26 | .br |
| 27 | char *\fIopts\fR; |
| 28 | .SH DESCRIPTION |
| 29 | This is a clone version of |
| 30 | the standard |
| 31 | .B getopt |
| 32 | library, |
| 33 | built on top of |
| 34 | .BR subgetopt(3) . |
| 35 | |
| 36 | See |
| 37 | .B subgetopt(3) |
| 38 | for a detailed description of |
| 39 | .B getopt |
| 40 | processing. |
| 41 | The main difference between |
| 42 | .B getopt |
| 43 | and |
| 44 | .B subgetopt |
| 45 | is that |
| 46 | .B getopt |
| 47 | prints error messages |
| 48 | in case of problems. |
| 49 | To turn off these error messages, set |
| 50 | .B opterr |
| 51 | (default nonzero) |
| 52 | to zero. |
| 53 | |
| 54 | This clone version of |
| 55 | .B getopt |
| 56 | also provides an |
| 57 | .B optprogname |
| 58 | variable. |
| 59 | There are two uses for this variable: |
| 60 | |
| 61 | (1) |
| 62 | By default |
| 63 | .B optprogname |
| 64 | is null. |
| 65 | When |
| 66 | .B getopt |
| 67 | sees this, |
| 68 | it |
| 69 | attempts to initialize |
| 70 | .B optprogname |
| 71 | from |
| 72 | .IR argv\fB[0] , |
| 73 | stripping the directory name. |
| 74 | The calling program can use |
| 75 | .B optprogname |
| 76 | after calling |
| 77 | .B getopt |
| 78 | at least once. |
| 79 | This is appropriate if the name of the program should be |
| 80 | determined from its command line. |
| 81 | |
| 82 | (2) |
| 83 | .B getopt |
| 84 | prints |
| 85 | .B optprogname |
| 86 | at the beginning |
| 87 | of any error messages. |
| 88 | So the calling program can, |
| 89 | before calling |
| 90 | .BR getopt , |
| 91 | initialize |
| 92 | .B optprogname |
| 93 | as desired. |
| 94 | This is appropriate if the name of the program should not be |
| 95 | determined from its command line. |
| 96 | .SH "COMPATIBILITY" |
| 97 | Old versions of |
| 98 | .B getopt |
| 99 | do not include |
| 100 | .BR opterr . |
| 101 | .BR optpos , |
| 102 | .BR opteof , |
| 103 | .BR optproblem , |
| 104 | and |
| 105 | .B optprogname |
| 106 | are specific to this clone version of |
| 107 | .BR getopt . |
| 108 | |
| 109 | Many features of this clone version of |
| 110 | .B getopt |
| 111 | are poorly defined, if available at all, |
| 112 | in most versions of |
| 113 | .BR getopt . |
| 114 | For example, the standard |
| 115 | .B getopt |
| 116 | interface does not define |
| 117 | .B optind |
| 118 | until the end of the option list. |
| 119 | And |
| 120 | .B optarg |
| 121 | is not defined |
| 122 | unless |
| 123 | .B getopt |
| 124 | has just returned |
| 125 | an option which takes an argument. |
| 126 | In this clone version, |
| 127 | .B optind |
| 128 | and |
| 129 | .B optpos |
| 130 | always indicate the next character to be read, |
| 131 | and |
| 132 | .B optarg |
| 133 | is null whenever |
| 134 | the current option does not take an argument. |
| 135 | See |
| 136 | .B subgetopt(3) |
| 137 | for precise definitions of the parsing procedure. |
| 138 | |
| 139 | When it reaches the end of the option list, |
| 140 | this version of |
| 141 | .B getopt |
| 142 | always returns |
| 143 | .BR opteof , |
| 144 | which is the same as |
| 145 | .BR subgetoptdone , |
| 146 | which is initialized to |
| 147 | .BR SUBGETOPTDONE , |
| 148 | which is defined as \-1. |
| 149 | The standard behavior is to return |
| 150 | EOF |
| 151 | from |
| 152 | .B stdio(3). |
| 153 | This is incompatible |
| 154 | on any weird machine where |
| 155 | EOF is different from \-1. |
| 156 | The calling program could set |
| 157 | .B opteof |
| 158 | to EOF to imitate the standard behavior. |
| 159 | |
| 160 | Like most versions of |
| 161 | .BR getopt , |
| 162 | this clone version allows, but does not demand, that |
| 163 | option arguments be |
| 164 | separated from the option by whitespace, i.e., be |
| 165 | in the next command-line argument. |
| 166 | |
| 167 | Some versions of |
| 168 | .B getopt |
| 169 | provide an |
| 170 | .B optopt |
| 171 | variable. |
| 172 | .B optopt |
| 173 | is incompatible across systems: |
| 174 | for example, |
| 175 | GNU |
| 176 | .B getopt |
| 177 | uses it the same way that this clone version uses |
| 178 | .BR optproblem , |
| 179 | while |
| 180 | BSD |
| 181 | .B getopt |
| 182 | uses it to |
| 183 | indicate the last option character returned by |
| 184 | .BR getopt . |
| 185 | This clone version does not provide |
| 186 | .BR optopt . |
| 187 | The use of |
| 188 | .B optopt |
| 189 | is strongly discouraged. |
| 190 | |
| 191 | Some versions of |
| 192 | .B getopt |
| 193 | do not recognize a double hyphen as the end of arguments. |
| 194 | This version allows a double hyphen, or in fact any argument beginning |
| 195 | with two hyphens. |
| 196 | |
| 197 | A lone hyphen is always recognized as the end of arguments. |
| 198 | Some versions of |
| 199 | .B getopt |
| 200 | allow lone hyphens as options. |
| 201 | This practice is wrong and is strongly discouraged. |
| 202 | .SH "SYNTAX NOTE" |
| 203 | .B getopt |
| 204 | is actually a macro abbreviation for |
| 205 | .BR getoptmine . |
| 206 | The external |
| 207 | .B opterr |
| 208 | and |
| 209 | .B optprogname |
| 210 | variables |
| 211 | are macros for |
| 212 | .B getopterr |
| 213 | and |
| 214 | .BR getoptprogname . |
| 215 | All the other |
| 216 | .B opt |
| 217 | variables are macros |
| 218 | for |
| 219 | .BR subgetopt . |
| 220 | These macros are defined in |
| 221 | .BR <getopt.h> , |
| 222 | unless |
| 223 | .B GETOPTNOSHORT |
| 224 | is defined. |
| 225 | Further macros are defined in |
| 226 | .BR <subgetopt.h> , |
| 227 | which is included by |
| 228 | .BR <getopt.h> , |
| 229 | unless |
| 230 | .B SUBGETOPTNOSHORT |
| 231 | is defined. |
| 232 | .SH VERSION |
| 233 | getopt version 1.9, 931129. |
| 234 | .SH AUTHOR |
| 235 | Placed into the public domain by Daniel J. Bernstein. |