2 .TH mdwopt 3 "6 July 1999" "Straylight/Edgeware" "mLib utilities library"
4 mdwopt \- command-line option parser
8 .B "#include <mLib/mdwopt.h>"
12 .B " char *arg, *prog;"
13 .B " int opt, ind, err;"
17 .B "char *optarg, optprog;"
18 .B "int optopt, opterr, optind;"
21 .B " const char *name;"
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 = ..."
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 = ..."
42 .B "#define OPTF_NEGATED = ..."
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 );
50 .BI "int getopt(int " argc ", char *const *" argv ", const char *" o );
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 );
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 );
65 function is a command line options parser which is (mostly) compatible
66 with the standard POSIX and GNU
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.
72 A command line consists of a number of
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
80 is also used sometimes. As special exceptions, the word containing only
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
87 is used to mark all following words as being non-options regardless of
88 their initial character.
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
97 .BR _POSIX_OPTION_ORDER .
99 There are two different styles of options:
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
109 Short options can be joined together to save space (and possibly to make
110 silly words): e.g., instead of giving options
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
120 Note that options with optional arguments must be written in the second
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
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
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.
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
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 '
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
158 character, and negated by a
161 .SS "Numerical options"
162 Finally, some (older) programs accept arguments of the form
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
169 repeatedly. Each time it is called,
171 returns a value describing the option just read, and stores information
172 about the option in a data block.
174 The data block is a structure containing at least the following members:
177 Pointer to the argument of the current option, or null. Argument
178 strings persist for as long as the underlying command line argument
181 does, so it's usually safe just to remember the pointer.
184 Value of the current option
187 Must be initialized to 0 before the first call to
189 After the last call, it is the index into
191 of the first nonoption argument.
194 Set to nonzero to allow
196 to emit error messages about illegal option syntax. (This would be a
197 flag setting, but it has to be here for
202 Contains the program's name, stripped of any path prefix. This is an
203 obsolete feature: the
205 module does the job in a more sensible way.
207 Prior to the first call to
213 members of the structure must be initialized.
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
223 .SS "Short option parsing"
224 Short options are described by a string,
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
231 If the first character of the short options string is
236 the order in which options are read is modified, as follows:
239 Forces the POSIX order to be used. As soon as a non-option is found,
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.
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
256 array, so that they appear before the non-options.
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
266 should be returned if a missing argument error is detected.
268 Each option in the string can be followed by a
270 sign, indicating that it can be negated, a
272 sign indicating that it requires an argument, or a
274 string, indicating an optional argument. Both
280 may be given, although the
284 If an option is found, the option character is returned to the caller.
285 A pointer to an argument is stored in the
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
292 .SS "Long option parsing"
293 Long options are described in a table. Each entry in the
295 .BR "struct option" ,
296 which contains the following members (in order):
298 .B "const char *name"
299 Pointer to the option's name.
302 A flags word describing the option. (The name is historical.)
305 Address of the flag variable to use when this option is matched.
308 Value to store or return when this option is matched.
310 The table is terminated by an entry whose
312 field is a null pointer.
316 finds a long option, it looks the name up in the table. The index of the
317 matching entry is stored in the
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.
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
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.
341 is nonzero, it points to an integer to be modified by
343 Usually the value in the
345 field is simply stored in the
347 variable. If the flag
351 member, however, the value is combined with the existing value of the
352 flags using a bitwise OR. If
356 field, then the flag bit will be cleared if a matching negated long
357 option is found. The value 0 is returned.
361 is zero, the value in
365 possibly with bit 8 set if the option was
368 Arguments from long options are stored in the
370 member of the data block.
371 .SS "Other optional features"
374 argument contains a bitmask of features which may be enabled:
377 Don't allow any long options. This makes
379 compatible with traditional Unix
383 A slightly misnamed flag. Short options are read normally. However,
384 long options may also begin with a single dash
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
393 Read numeric options. If a numeric option is found, the character
395 is returned and the text of the number is stored in the
397 member of the data block.
400 Allow negation of options. Negated options are returned ORed with
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.)
411 Don't read the program name from
416 data block member. Options start right at the beginning of
420 Allow negated numeric options. Negated numeric options begin with a
425 .RB ` # ' " | OPTF_NEGATED" .
426 .SS "Compatibility features"
432 correspond to calls to
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
438 Additionally, there is a global data block, which is specified by
443 The members of this block may be referred to by their traditional names:
446 The argument of the current option.
449 Option code of the current option.
454 is to report errors. This is the default.
457 Index of the first non-option argument.
460 Name of the program, stripped of path prefix.
462 These names aren't considered deprecated: they help make the code easier
463 to read by people used to the traditional
470 Mark Wooding, <mdw@distorted.org.uk>
~mdw / mLib / blob