Commit | Line | Data |
---|---|---|
2117e02e MW |
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. |