subgetopt.3 (5800B)
1 .TH subgetopt 3 2 .SH NAME 3 subgetopt \- get option character from command line 4 .SH SYNTAX 5 .B #include <subgetopt.h> 6 7 char *\fBsgoptarg\fP; 8 .br 9 int \fBsgoptind\fP; 10 .br 11 int \fBsgoptpos\fP; 12 .br 13 int \fBsgoptdone\fP; 14 .br 15 int \fBsgoptproblem\fP; 16 17 int \fBsgopt(\fP\fIargc,argv,opts\fR\fB)\fP; 18 19 int \fIargc\fR; 20 .br 21 char **\fIargv\fR; 22 .br 23 char *\fIopts\fR; 24 .SH DESCRIPTION 25 .B sgopt 26 returns the next valid command-line option character 27 from 28 .IR argv . 29 30 Valid option characters are listed in the 31 .I opts 32 string. 33 .I opts 34 may be empty. 35 A character in 36 .I opts 37 may be followed by a colon, 38 in which case it 39 takes an 40 .I option argument\fR. 41 Avoid using the characters ?, :, and \- as option characters. 42 43 Below 44 .I option argument 45 is abbreviated 46 as 47 .I optarg 48 and 49 .I command-line argument 50 is abbreviated as 51 .IR cmdarg . 52 53 Options are listed in cmdargs which begin with 54 a minus sign. 55 Several options which do not take optargs may be combined 56 into one cmdarg. 57 58 An option which takes an optarg may be handled in two ways. 59 If it appears at the very end of a cmdarg, 60 then the entire next cmdarg is the optarg. 61 But if there are any characters in the cmdarg 62 after the option character, 63 then those characters form the optarg. 64 The optarg is returned in 65 .BR sgoptarg . 66 Next time 67 .B sgopt 68 looks at the cmdarg which follows the optarg. 69 70 If a cmdarg does not begin with a hyphen, 71 or if it is a lone hyphen not followed by any characters, 72 or if it begins with two hyphens, 73 then it terminates option processing, 74 and 75 .B sgopt 76 returns an appropriate code. 77 If there are two hyphens, 78 .B sgopt 79 will advance attention to the next cmdarg, 80 so it can be called again to read further options. 81 .SH "PROPER USAGE" 82 .B sgoptproblem 83 should be used only when 84 .B sgopt 85 returns ?. 86 .B sgoptind 87 and 88 .B sgoptpos 89 are defined all the time. 90 .B sgoptarg 91 is defined all the time; 92 it is null unless 93 .B sgopt 94 has just returned an option with optarg. 95 96 .B sgopt 97 is typically used as follows. 98 99 .EX 100 #include <subgetopt.h> 101 102 main(argc,argv) int argc; char **argv; { int opt; 103 104 while ((opt = sgopt(argc,argv,"a:s")) != sgoptdone) 105 .br 106 switch(opt) { 107 .br 108 case 'a': 109 .br 110 printf("opt a with optarg %s\\n",sgoptarg); break; 111 .br 112 case 's': 113 .br 114 printf("opt s with no optarg\\n"); break; 115 .br 116 case '?': 117 .br 118 if (argv[sgoptind] && (sgoptind < argc)) 119 .br 120 printf("illegal opt %c\\n",sgoptproblem); 121 .br 122 else 123 .br 124 printf("missing arg, opt %c\\n",sgoptproblem); 125 .br 126 exit(1); 127 .br 128 } 129 130 argv += sgoptind; 131 .br 132 while (*argv) printf("argument %s\\n",*argv++); 133 .br 134 exit(0); 135 .br 136 } 137 .EE 138 139 The end of the command line is 140 marked by either 141 .IR argc , 142 or a null pointer in 143 .IR argv , 144 whichever comes first. 145 Normally 146 these two markers coincide, 147 so it is redundant 148 to test for 149 both 150 .I argv\fB[sgoptind] 151 and 152 .B sgoptind < \fIargc\fR. 153 The above code shows both tests as an illustration. 154 155 .B Multiple option sets: 156 One useful technique is to call 157 .B sgopt 158 with a primary 159 .I opts 160 until it returns EOF, 161 then call 162 .B sgopt 163 with a secondary 164 .I opts 165 until it returns EOF. 166 The user can provide primary options, then a double hyphen, 167 and then secondary options. 168 No special handling is needed if some or all of the options are 169 omitted. 170 The same technique can be used for any number of option sets 171 in series. 172 173 .B Multiple command lines: 174 Before parsing a new 175 .BR argv , 176 make sure to 177 set 178 .B sgoptind 179 and 180 .B sgoptpos 181 back to 182 1 and 0. 183 .SH "PARSING STAGES" 184 .B sgopt 185 keeps track of its position in 186 .I argv 187 with 188 .B sgoptind 189 and 190 .BR sgoptpos , 191 which are initialized to 1 and 0. 192 It looks at 193 .I argv\fB[sgoptind][sgoptpos] 194 and following characters. 195 196 .B sgopt 197 indicates 198 that no more options are available by 199 returning 200 .BR sgoptdone , 201 which is initialized to 202 .BR SUBGETOPTDONE , 203 which is defined as \-1. 204 205 .B sgopt 206 begins by setting 207 .B optarg 208 to null. 209 210 .B Ending conditions: 211 If 212 .I argv 213 is null, or 214 .B sgoptind 215 is larger than 216 .IR argc , 217 or the current cmdarg 218 .I argv\fB[sgoptind] 219 is null, 220 then 221 .B sgopt 222 returns 223 .BR optdone . 224 225 .B Stage one: 226 If the current character 227 is zero, 228 .B sgopt 229 moves to the beginning of the next cmdarg. 230 It then checks the ending conditions again. 231 232 .B Stage two: 233 If 234 the current position is the begining of the cmdarg, 235 .B sgopt 236 checks whether 237 the current character 238 is a minus sign. 239 If not it returns 240 .BR optdone . 241 It then 242 moves 243 to the next character. 244 If that character is zero, 245 .B sgopt 246 moves 247 back to the beginning of the cmdarg, 248 and returns 249 .BR sgoptdone . 250 If the character is a minus sign, 251 .B sgopt 252 moves to the beginning of the next cmdarg, 253 and returns 254 .BR sgoptdone . 255 256 .B Stage three: 257 .B sgopt 258 records the current character, 259 .IR c , 260 and moves to the next character. 261 There are three possibilities: 262 (1) 263 .I c 264 is an option character without optarg in 265 .IR opts , 266 or 267 (2) 268 .I c 269 is an option character with optarg in 270 .IR opts , 271 or 272 (3) 273 .I c 274 does not appear in 275 .IR opts . 276 277 (1) 278 If 279 .I c 280 appears as an option character without optarg in 281 .IR opts , 282 .B sgopt 283 returns 284 .IR c . 285 286 (2) 287 If 288 .I c 289 appears as an option character with optarg in 290 .IR opts , 291 .B sgopt 292 sets 293 .B sgoptarg 294 to the current position, 295 and moves to the next cmdarg. 296 If 297 .B sgoptarg 298 is nonempty, 299 .B sgopt 300 returns 301 .IR c . 302 303 Then 304 .B sgopt 305 sets 306 .B sgoptarg 307 to 308 the current cmdarg. 309 If 310 the current cmdarg is null, 311 or past 312 .IR argc , 313 .B sgopt 314 sets 315 .B sgoptproblem 316 to 317 .I c 318 and returns ?. 319 Otherwise 320 .B sgopt 321 moves to the next 322 argument 323 and returns 324 .IR c . 325 326 (2) 327 If 328 .I c 329 does not appear in 330 .IR opts , 331 .B sgopt 332 sets 333 .B sgoptproblem 334 to 335 .I c 336 and returns ?. 337 .SH "SYNTAX NOTE" 338 .B sgopt 339 is actually a macro abbreviation for 340 .BR subgetopt . 341 The external 342 .B sg 343 variables are also macros 344 for 345 .BR subget . 346 These macros are defined in 347 .BR <subgetopt.h> , 348 unless 349 .B SUBGETOPTNOSHORT 350 is defined 351 when 352 .B <subgetopt.h> 353 is included. 354 .SH VERSION 355 subgetopt version 0.9, 931129. 356 .SH AUTHOR 357 Placed into the public domain by Daniel J. Bernstein.