Commit | Line | Data |
---|---|---|
05fbeb03 | 1 | .\" -*-nroff-*- |
fbf20b5b | 2 | .TH mdwopt 3 "6 July 1999" "Straylight/Edgeware" "mLib utilities library" |
05fbeb03 | 3 | .SH "NAME" |
4 | mdwopt \- command-line option parser | |
5 | .\" @mdwopt | |
6 | .SH "SYNOPSIS" | |
7 | .nf | |
8 | .B "#include <mLib/mdwopt.h>" | |
d056fbdf | 9 | .PP |
adec5584 | 10 | .ta 2n |
4729aa69 | 11 | .B "typedef struct {" |
adec5584 MW |
12 | .B " char *arg, *prog;" |
13 | .B " int opt, ind, err;" | |
14 | .B " ..." | |
4729aa69 | 15 | .B "} mdwopt_data;" |
d056fbdf | 16 | .PP |
4729aa69 MW |
17 | .B "char *optarg, optprog;" |
18 | .B "int optopt, opterr, optind;" | |
d056fbdf | 19 | .PP |
4729aa69 | 20 | .B "struct option {" |
adec5584 MW |
21 | .B " const char *name;" |
22 | .B " int has_arg;" | |
23 | .B " int *flag;" | |
24 | .B " int val;" | |
4729aa69 | 25 | .B "};" |
d056fbdf | 26 | .PP |
4729aa69 MW |
27 | .B "#define OPTF_NOARG = ..." |
28 | .B "#define OPTF_ARGREQ = ..." | |
29 | .B "#define OPTF_ARGOPT = ..." | |
30 | .B "#define OPTF_ARG = ..." | |
31 | .B "#define OPTF_SWITCH = ..." | |
32 | .B "#define OPTF_NEGATE = ..." | |
d056fbdf | 33 | .PP |
4729aa69 MW |
34 | .B "#define OPTF_NOLONGS = ..." |
35 | .B "#define OPTF_NOSHORTS = ..." | |
36 | .B "#define OPTF_NUMBERS = ..." | |
37 | .B "#define OPTF_NEGATION = ..." | |
38 | .B "#define OPTF_ENVVAR = ..." | |
39 | .B "#define OPTF_NOPROGNAME = ..." | |
40 | .B "#define OPTF_NEGNUMBER = ..." | |
d056fbdf | 41 | .PP |
4729aa69 | 42 | .B "#define OPTF_NEGATED = ..." |
d056fbdf | 43 | .PP |
adec5584 MW |
44 | .ta \w'\fBint mdwopt('u |
45 | .BI "int mdwopt(int " argc ", char *const *" argv , | |
46 | .BI " const char *" shortopt , | |
47 | .BI " const struct option *" longopt ", int *" longind , | |
48 | .BI " mdwopt_data *" data ", int " flags ); | |
d056fbdf | 49 | .PP |
05fbeb03 | 50 | .BI "int getopt(int " argc ", char *const *" argv ", const char *" o ); |
d056fbdf | 51 | .PP |
adec5584 MW |
52 | .ta \w'\fBint getopt_long('u |
53 | .BI "int getopt_long(int " argc ", char *const *" argv , | |
54 | .BI " const char * "shortopt , | |
55 | .BI " const struct option *" longopt ", int *" longind ); | |
d056fbdf | 56 | .PP |
adec5584 MW |
57 | .ta \w'\fBint getopt_long_only('u |
58 | .BI "int getopt_long_only(int " argc ", char *const *" argv , | |
59 | .BI " const char * "shortopt , | |
60 | .BI " const struct option *" longopt ", int *" longind ); | |
05fbeb03 | 61 | .fi |
62 | .SH "OVERVIEW" | |
63 | The | |
64 | .B mdwopt | |
65 | function is a command line options parser which is (mostly) compatible | |
66 | with the standard POSIX and GNU | |
67 | .B getopt | |
68 | functions, although provides more features than either. It's not the | |
69 | most featureful options parser around, but it's good enough for my | |
70 | purposes at the moment. | |
71 | .SH "OPTION SYNTAX" | |
72 | A command line consists of a number of | |
73 | .I words | |
74 | (which may contain spaces, according to various shell quoting | |
75 | conventions). A word may be an option, an argument to an option, or a | |
76 | non-option. An option begins with a special character, usually | |
77 | .RB ` \- ', | |
78 | although | |
79 | .RB ` + ' | |
80 | is also used sometimes. As special exceptions, the word containing only | |
81 | a | |
82 | .RB ` \- ' | |
83 | is considered to be a non-option, since it usually represents standard | |
84 | input or output as a filename, and the word containing only a | |
85 | double-dash | |
3751b763 | 86 | .RB ` \-\- ' |
05fbeb03 | 87 | is used to mark all following words as being non-options regardless of |
88 | their initial character. | |
89 | .PP | |
90 | Traditionally, all words after the first non-option have been considered | |
91 | to be non-options automatically, so that options must be specified | |
92 | before filenames. However, this implementation can extract all the | |
93 | options from the command line regardless of their position. This can | |
94 | usually be disabled by setting one of the environment variables | |
95 | .B POSIXLY_CORRECT | |
96 | or | |
97 | .BR _POSIX_OPTION_ORDER . | |
98 | .PP | |
99 | There are two different styles of options: | |
100 | .I short | |
101 | and | |
102 | .IR long . | |
103 | Traditional Unix (and POSIX) only uses short options. The long options | |
104 | are a GNU convention. | |
105 | .SS "Short option syntax" | |
106 | Short options are the sort which Unix has known for ages: an option is a | |
107 | single letter, preceded by a | |
3751b763 | 108 | .RB ` \- '. |
05fbeb03 | 109 | Short options can be joined together to save space (and possibly to make |
110 | silly words): e.g., instead of giving options | |
111 | .RB ` "\-x \-y" ', | |
112 | a user could write | |
113 | .RB ` \-xy '. | |
114 | Some short options can have arguments which appear after the option | |
115 | letter, either immediately following, or in the next word; so an option | |
116 | with an argument could be written as | |
117 | .RB ` "\-o foo" ' | |
118 | or as | |
119 | .RB ` \-ofoo '). | |
120 | Note that options with optional arguments must be written in the second | |
121 | style. | |
122 | .PP | |
123 | When a short option controls a flag setting, it is sometimes possible to | |
124 | explicitly turn the flag off, as well as turning it on, (usually to | |
125 | override default options). This is usually done by using a | |
126 | .RB ` + ' | |
d4efbcd9 | 127 | instead of a |
05fbeb03 | 128 | .RB ` \- ' |
129 | to introduce the option. (Some programs use upper-case option letters | |
130 | to indicate this instead.) | |
131 | .SS "Long option syntax" | |
132 | Long options, as popularized by the GNU utilities, are given long-ish | |
133 | memorable names, preceded by a double-dash | |
134 | .RB ` \-\- '. | |
135 | Since their names are more than a single character, long options can't | |
136 | be combined in the same way as short options. Arguments to long options | |
137 | may be given either in the same word, separated from the option name by | |
138 | an equals sign, or in the following word. | |
139 | .PP | |
140 | Long option names can be abbreviated if necessary, as long as the | |
141 | abbreviation is unique. This means that options can have sensible and | |
142 | memorable names but still not require much typing from an experienced | |
143 | user. | |
144 | .PP | |
145 | Like short options, long options can control flag settings. The options | |
146 | to manipulate these settings come in pairs: an option of the form | |
147 | .RB ` \-\-set\-flag ' | |
148 | might set the flag, while an option of the form | |
149 | .RB ` \-\-no\-set\-flag ' | |
150 | might clear it. | |
151 | .PP | |
152 | It is usual for applications to provide both short and long options with | |
153 | identical behaviour. Some applications with lots of options may only | |
154 | provide long options (although they will often be only two or three | |
155 | characters long). In this case, long options can be preceded with a | |
156 | single | |
157 | .RB ` \- ' | |
158 | character, and negated by a | |
159 | .RB ` + ' | |
160 | character. | |
161 | .SS "Numerical options" | |
162 | Finally, some (older) programs accept arguments of the form | |
163 | .RB ` \- \c | |
164 | .IR number ', | |
165 | to set some numerical parameter, typically a line count of some kind. | |
166 | .SH "PARSING OPTIONS WITH \fBmdwopt\fP" | |
167 | An application parses its options by calling | |
168 | .B mdwopt | |
169 | repeatedly. Each time it is called, | |
170 | .B mdwopt | |
171 | returns a value describing the option just read, and stores information | |
172 | about the option in a data block. | |
173 | .PP | |
174 | The data block is a structure containing at least the following members: | |
175 | .TP | |
ff76c38f | 176 | .B "char *arg" |
05fbeb03 | 177 | Pointer to the argument of the current option, or null. Argument |
178 | strings persist for as long as the underlying command line argument | |
179 | array | |
180 | .I argv | |
181 | does, so it's usually safe just to remember the pointer. | |
182 | .TP | |
ff76c38f | 183 | .B "int opt" |
05fbeb03 | 184 | Value of the current option |
185 | .TP | |
ff76c38f | 186 | .B "int ind" |
05fbeb03 | 187 | Must be initialized to 0 before the first call to |
188 | .BR mdwopt . | |
189 | After the last call, it is the index into | |
190 | .I argv | |
191 | of the first nonoption argument. | |
192 | .TP | |
ff76c38f | 193 | .B "int err" |
05fbeb03 | 194 | Set to nonzero to allow |
195 | .B mdwopt | |
196 | to emit error messages about illegal option syntax. (This would be a | |
197 | flag setting, but it has to be here for | |
198 | .B getopt | |
199 | compatibility.) | |
200 | .TP | |
ff76c38f | 201 | .B "char *prog" |
05fbeb03 | 202 | Contains the program's name, stripped of any path prefix. This is an |
203 | obsolete feature: the | |
204 | .BR quis (3) | |
205 | module does the job in a more sensible way. | |
206 | .PP | |
207 | Prior to the first call to | |
208 | .BR mdwopt , | |
209 | the | |
210 | .B err | |
211 | and | |
212 | .B ind | |
3751b763 | 213 | members of the structure must be initialized. |
05fbeb03 | 214 | .PP |
215 | The arguments | |
216 | .I argc | |
217 | and | |
218 | .I argv | |
219 | describe the command-line argument array which is to be parsed. These | |
220 | will usually be exactly the arguments passed to the program's | |
221 | .B main | |
222 | function. | |
223 | .SS "Short option parsing" | |
224 | Short options are described by a string, | |
225 | .IR shortopt , | |
226 | which once upon a time just contained the permitted option characters. | |
227 | Now the options string begins with a collection of flag characters, and | |
228 | various flag characters can be put after options characters to change | |
229 | their properties. | |
230 | .PP | |
231 | If the first character of the short options string is | |
232 | .RB ` + ', | |
233 | .RB ` \- ' | |
234 | or | |
235 | .RB ` ! ', | |
236 | the order in which options are read is modified, as follows: | |
237 | .TP | |
238 | .RB ` + ' | |
239 | Forces the POSIX order to be used. As soon as a non-option is found, | |
240 | .B mdwopt | |
241 | returns \-1. | |
242 | .TP | |
243 | .RB ` \- ' | |
244 | Makes | |
245 | .B mdwopt | |
246 | treat non-options as being `special' sorts of option. When a non-option | |
247 | word is found, the value 0 is returned, and the actual text of the word | |
248 | is stored as being the option's argument. | |
249 | .TP | |
250 | .RB ` ! ' | |
251 | forces the default order to be used regardless of environment variable | |
252 | settings. The entire command line is scanned for options, which are | |
253 | returned in order. However, during this process, the options are moved | |
254 | in the | |
255 | .I argv | |
256 | array, so that they appear before the non-options. | |
257 | .PP | |
258 | A | |
259 | .RB ` : ' | |
260 | character may be placed after the ordering flag (or at the very | |
261 | beginning if no ordering flag is given) which indicates that the | |
262 | character | |
263 | .RB ` : ', | |
264 | rather than | |
265 | .RB ` ? ', | |
266 | should be returned if a missing argument error is detected. | |
267 | .PP | |
268 | Each option in the string can be followed by a | |
269 | .RB ` + ' | |
270 | sign, indicating that it can be negated, a | |
271 | .RB ` : ' | |
272 | sign indicating that it requires an argument, or a | |
273 | .RB ` :: ' | |
274 | string, indicating an optional argument. Both | |
275 | .RB ` + ' | |
276 | and one of | |
277 | .RB ` : ' | |
278 | or | |
279 | .RB ` :: ' | |
280 | may be given, although the | |
281 | .RB ` + ' | |
282 | must come first. | |
283 | .PP | |
284 | If an option is found, the option character is returned to the caller. | |
285 | A pointer to an argument is stored in the | |
286 | .B arg | |
287 | member of the data block; a null pointer is stored if there was no | |
288 | argument. If a negated option was found, the option character is | |
d2a91066 | 289 | returned ORed with |
05fbeb03 | 290 | .B OPTF_NEGATED |
291 | (bit 8 set). | |
292 | .SS "Long option parsing" | |
293 | Long options are described in a table. Each entry in the | |
294 | table is of type | |
295 | .BR "struct option" , | |
296 | which contains the following members (in order): | |
297 | .TP | |
ff76c38f | 298 | .B "const char *name" |
05fbeb03 | 299 | Pointer to the option's name. |
300 | .TP | |
ff76c38f | 301 | .B "int has_arg" |
05fbeb03 | 302 | A flags word describing the option. (The name is historical.) |
303 | .TP | |
ff76c38f | 304 | .B "int *flag" |
05fbeb03 | 305 | Address of the flag variable to use when this option is matched. |
306 | .TP | |
ff76c38f | 307 | .B "int val" |
05fbeb03 | 308 | Value to store or return when this option is matched. |
309 | .PP | |
310 | The table is terminated by an entry whose | |
311 | .B name | |
312 | field is a null pointer. | |
313 | .PP | |
314 | When | |
315 | .B mdwopt | |
316 | finds a long option, it looks the name up in the table. The index of the | |
317 | matching entry is stored in the | |
318 | .I longind | |
319 | variable, passed to | |
320 | .B mdwopt | |
d4efbcd9 | 321 | (unless |
05fbeb03 | 322 | .I longind |
323 | is null): a value of \-1 indicates that no long option was found. The | |
324 | behaviour is then dependent on the values in the table entry. | |
325 | .PP | |
326 | If the flag bit | |
327 | .B OPTF_ARGREQ | |
328 | is set in | |
329 | .B has_arg | |
330 | then the option has a required argument, which may be separated from the | |
331 | option name by an equals sign or placed in the following word. If the | |
332 | flag bit | |
333 | .B OPTF_ARGOPT | |
334 | is set then the argument is optional. If present, the argument must be | |
335 | in the same word as the option name, separated by an equals sign. It is | |
336 | an error for both flags to be set; if neither is set then the option | |
337 | does not take an argument. | |
338 | .PP | |
339 | If | |
340 | .B flag | |
341 | is nonzero, it points to an integer to be modified by | |
342 | .BR mdwopt . | |
343 | Usually the value in the | |
344 | .B val | |
345 | field is simply stored in the | |
346 | .B flag | |
347 | variable. If the flag | |
348 | .B OPTF_SWITCH | |
349 | is set in the | |
350 | .B has_arg | |
351 | member, however, the value is combined with the existing value of the | |
352 | flags using a bitwise OR. If | |
353 | .B OPTF_NEGATE | |
354 | is set in the | |
355 | .B has_arg | |
356 | field, then the flag bit will be cleared if a matching negated long | |
357 | option is found. The value 0 is returned. | |
358 | .PP | |
359 | If | |
360 | .B flag | |
361 | is zero, the value in | |
362 | .B val | |
363 | is returned by | |
364 | .BR mdwopt , | |
365 | possibly with bit 8 set if the option was | |
366 | negated. | |
367 | .PP | |
3751b763 | 368 | Arguments from long options are stored in the |
05fbeb03 | 369 | .B arg |
3751b763 | 370 | member of the data block. |
05fbeb03 | 371 | .SS "Other optional features" |
372 | The | |
373 | .I flags | |
374 | argument contains a bitmask of features which may be enabled: | |
375 | .TP | |
376 | .B OPTF_NOLONGS | |
377 | Don't allow any long options. This makes | |
378 | .B mdwopt | |
379 | compatible with traditional Unix | |
380 | .BR getopt . | |
381 | .TP | |
382 | .B OPTF_NOSHORTS | |
383 | A slightly misnamed flag. Short options are read normally. However, | |
384 | long options may also begin with a single dash | |
385 | .RB ` \- ' | |
386 | (or the | |
387 | .RB ` + ' | |
388 | sign if negated). Long options may not be combined with short options: | |
389 | an option word which begins with a short option must contain only short | |
390 | options. | |
391 | .TP | |
392 | .B OPTF_NUMBERS | |
393 | Read numeric options. If a numeric option is found, the character | |
394 | .RB ` # ' | |
395 | is returned and the text of the number is stored in the | |
396 | .B arg | |
397 | member of the data block. | |
398 | .TP | |
399 | .B OPTF_NEGATION | |
400 | Allow negation of options. Negated options are returned ORed with | |
401 | .BR OPTF_NEGATED . | |
402 | .TP | |
403 | .B OPTF_ENVVAR | |
404 | Options will be read from an environment variable before scanning the | |
405 | actual command line provided. The name of the environment variable is | |
406 | found by capitalizing the program name. (This allows a user to have | |
407 | different default settings for a program, by calling it through | |
408 | different symbolic links.) | |
409 | .TP | |
410 | .B OPTF_NOPROGNAME | |
411 | Don't read the program name from | |
412 | .IR argv \c | |
413 | .BR [0] , | |
414 | and don't set the | |
415 | .B prog | |
416 | data block member. Options start right at the beginning of | |
417 | .IR argv . | |
418 | .TP | |
419 | .B OPTF_NEGNUMBER | |
420 | Allow negated numeric options. Negated numeric options begin with a | |
421 | .RB ` + ' | |
422 | rather than a | |
423 | .RB ` \- '. | |
424 | The return value is | |
425 | .RB ` # ' " | OPTF_NEGATED" . | |
426 | .SS "Compatibility features" | |
427 | The macros | |
428 | .BR getopt , | |
429 | .B getopt_long | |
430 | and | |
431 | .B getopt_long_only | |
432 | correspond to calls to | |
433 | .B mdwopt | |
434 | with various flag settings. See the macro definitions for the actual | |
435 | mappings, and the documentation for the functions to see how they're | |
436 | meant to work. | |
437 | .PP | |
438 | Additionally, there is a global data block, which is specified by | |
439 | passing a null | |
440 | .I data | |
441 | argument to | |
442 | .BR mdwopt . | |
443 | The members of this block may be referred to by their traditional names: | |
444 | .TP | |
445 | .B optarg | |
446 | The argument of the current option. | |
447 | .TP | |
448 | .B optopt | |
449 | Option code of the current option. | |
450 | .TP | |
451 | .B opterr | |
452 | Nonzero if | |
453 | .B mdwopt | |
454 | is to report errors. This is the default. | |
455 | .TP | |
456 | .B optind | |
457 | Index of the first non-option argument. | |
458 | .TP | |
459 | .B optprog | |
460 | Name of the program, stripped of path prefix. | |
461 | .PP | |
462 | These names aren't considered deprecated: they help make the code easier | |
463 | to read by people used to the traditional | |
464 | .B getopt | |
465 | function. | |
466 | .SH "SEE ALSO" | |
467 | .BR getopt (3), | |
468 | .BR mLib (3). | |
469 | .SH "AUTHOR" | |
9b5ac6ff | 470 | Mark Wooding, <mdw@distorted.org.uk> |