2 .TH mdwopt 3 "6 July 1999" "Straylight/Edgeware" "mLib utilities library"
4 mdwopt \- command-line option parser
8 .B "#include <mLib/mdwopt.h>"
10 .BI "int mdwopt(int " argc ", char *const *" argv ,
11 .BI " const char *" shortopt ,
12 .BI " const struct option *" longopt ", int *" longind ,
13 .BI " mdwopt_data *" data ", int " flags );
15 .BI "int getopt(int " argc ", char *const *" argv ", const char *" o );
17 .BI "int getopt_long(int " argc ", char *const *" argv ,
18 .BI " const char * "shortopt ,
19 .BI " const struct option *" longopt ", int *" longind );
21 .BI "int getopt_long_only(int " argc ", char *const *" argv ,
22 .BI " const char * "shortopt ,
23 .BI " const struct option *" longopt ", int *" longind );
28 function is a command line options parser which is (mostly) compatible
29 with the standard POSIX and GNU
31 functions, although provides more features than either. It's not the
32 most featureful options parser around, but it's good enough for my
33 purposes at the moment.
35 A command line consists of a number of
37 (which may contain spaces, according to various shell quoting
38 conventions). A word may be an option, an argument to an option, or a
39 non-option. An option begins with a special character, usually
43 is also used sometimes. As special exceptions, the word containing only
46 is considered to be a non-option, since it usually represents standard
47 input or output as a filename, and the word containing only a
50 is used to mark all following words as being non-options regardless of
51 their initial character.
53 Traditionally, all words after the first non-option have been considered
54 to be non-options automatically, so that options must be specified
55 before filenames. However, this implementation can extract all the
56 options from the command line regardless of their position. This can
57 usually be disabled by setting one of the environment variables
60 .BR _POSIX_OPTION_ORDER .
62 There are two different styles of options:
66 Traditional Unix (and POSIX) only uses short options. The long options
68 .SS "Short option syntax"
69 Short options are the sort which Unix has known for ages: an option is a
70 single letter, preceded by a
72 Short options can be joined together to save space (and possibly to make
73 silly words): e.g., instead of giving options
77 Some short options can have arguments which appear after the option
78 letter, either immediately following, or in the next word; so an option
79 with an argument could be written as
83 Note that options with optional arguments must be written in the second
86 When a short option controls a flag setting, it is sometimes possible to
87 explicitly turn the flag off, as well as turning it on, (usually to
88 override default options). This is usually done by using a
92 to introduce the option. (Some programs use upper-case option letters
93 to indicate this instead.)
94 .SS "Long option syntax"
95 Long options, as popularized by the GNU utilities, are given long-ish
96 memorable names, preceded by a double-dash
98 Since their names are more than a single character, long options can't
99 be combined in the same way as short options. Arguments to long options
100 may be given either in the same word, separated from the option name by
101 an equals sign, or in the following word.
103 Long option names can be abbreviated if necessary, as long as the
104 abbreviation is unique. This means that options can have sensible and
105 memorable names but still not require much typing from an experienced
108 Like short options, long options can control flag settings. The options
109 to manipulate these settings come in pairs: an option of the form
110 .RB ` \-\-set\-flag '
111 might set the flag, while an option of the form
112 .RB ` \-\-no\-set\-flag '
115 It is usual for applications to provide both short and long options with
116 identical behaviour. Some applications with lots of options may only
117 provide long options (although they will often be only two or three
118 characters long). In this case, long options can be preceded with a
121 character, and negated by a
124 .SS "Numerical options"
125 Finally, some (older) programs accept arguments of the form
128 to set some numerical parameter, typically a line count of some kind.
129 .SH "PARSING OPTIONS WITH \fBmdwopt\fP"
130 An application parses its options by calling
132 repeatedly. Each time it is called,
134 returns a value describing the option just read, and stores information
135 about the option in a data block.
137 The data block is a structure containing at least the following members:
140 Pointer to the argument of the current option, or null. Argument
141 strings persist for as long as the underlying command line argument
144 does, so it's usually safe just to remember the pointer.
147 Value of the current option
150 Must be initialized to 0 before the first call to
152 After the last call, it is the index into
154 of the first nonoption argument.
157 Set to nonzero to allow
159 to emit error messages about illegal option syntax. (This would be a
160 flag setting, but it has to be here for
165 Contains the program's name, stripped of any path prefix. This is an
166 obsolete feature: the
168 module does the job in a more sensible way.
170 Prior to the first call to
176 members of the structure must be initialized.
182 describe the command-line argument array which is to be parsed. These
183 will usually be exactly the arguments passed to the program's
186 .SS "Short option parsing"
187 Short options are described by a string,
189 which once upon a time just contained the permitted option characters.
190 Now the options string begins with a collection of flag characters, and
191 various flag characters can be put after options characters to change
194 If the first character of the short options string is
199 the order in which options are read is modified, as follows:
202 Forces the POSIX order to be used. As soon as a non-option is found,
209 treat non-options as being `special' sorts of option. When a non-option
210 word is found, the value 0 is returned, and the actual text of the word
211 is stored as being the option's argument.
214 forces the default order to be used regardless of environment variable
215 settings. The entire command line is scanned for options, which are
216 returned in order. However, during this process, the options are moved
219 array, so that they appear before the non-options.
223 character may be placed after the ordering flag (or at the very
224 beginning if no ordering flag is given) which indicates that the
229 should be returned if a missing argument error is detected.
231 Each option in the string can be followed by a
233 sign, indicating that it can be negated, a
235 sign indicating that it requires an argument, or a
237 string, indicating an optional argument. Both
243 may be given, although the
247 If an option is found, the option character is returned to the caller.
248 A pointer to an argument is stored in the
250 member of the data block; a null pointer is stored if there was no
251 argument. If a negated option was found, the option character is
255 .SS "Long option parsing"
256 Long options are described in a table. Each entry in the
258 .BR "struct option" ,
259 which contains the following members (in order):
261 .B "const char *name"
262 Pointer to the option's name.
265 A flags word describing the option. (The name is historical.)
268 Address of the flag variable to use when this option is matched.
271 Value to store or return when this option is matched.
273 The table is terminated by an entry whose
275 field is a null pointer.
279 finds a long option, it looks the name up in the table. The index of the
280 matching entry is stored in the
286 is null): a value of \-1 indicates that no long option was found. The
287 behaviour is then dependent on the values in the table entry.
293 then the option has a required argument, which may be separated from the
294 option name by an equals sign or placed in the following word. If the
297 is set then the argument is optional. If present, the argument must be
298 in the same word as the option name, separated by an equals sign. It is
299 an error for both flags to be set; if neither is set then the option
300 does not take an argument.
304 is nonzero, it points to an integer to be modified by
306 Usually the value in the
308 field is simply stored in the
310 variable. If the flag
314 member, however, the value is combined with the existing value of the
315 flags using a bitwise OR. If
319 field, then the flag bit will be cleared if a matching negated long
320 option is found. The value 0 is returned.
324 is zero, the value in
328 possibly with bit 8 set if the option was
331 Arguments from long options are stored in the
333 member of the data block.
334 .SS "Other optional features"
337 argument contains a bitmask of features which may be enabled:
340 Don't allow any long options. This makes
342 compatible with traditional Unix
346 A slightly misnamed flag. Short options are read normally. However,
347 long options may also begin with a single dash
351 sign if negated). Long options may not be combined with short options:
352 an option word which begins with a short option must contain only short
356 Read numeric options. If a numeric option is found, the character
358 is returned and the text of the number is stored in the
360 member of the data block.
363 Allow negation of options. Negated options are returned ORed with
367 Options will be read from an environment variable before scanning the
368 actual command line provided. The name of the environment variable is
369 found by capitalizing the program name. (This allows a user to have
370 different default settings for a program, by calling it through
371 different symbolic links.)
374 Don't read the program name from
379 data block member. Options start right at the beginning of
383 Allow negated numeric options. Negated numeric options begin with a
388 .RB ` # ' " | OPTF_NEGATED" .
389 .SS "Compatibility features"
395 correspond to calls to
397 with various flag settings. See the macro definitions for the actual
398 mappings, and the documentation for the functions to see how they're
401 Additionally, there is a global data block, which is specified by
406 The members of this block may be referred to by their traditional names:
409 The argument of the current option.
412 Option code of the current option.
417 is to report errors. This is the default.
420 Index of the first non-option argument.
423 Name of the program, stripped of path prefix.
425 These names aren't considered deprecated: they help make the code easier
426 to read by people used to the traditional
433 Mark Wooding, <mdw@nsict.org>
~mdw / mLib / blob