2 .TH mdwopt 3 "6 July 1999" "Straylight/Edgeware" "mLib utilities library"
4 mdwopt \- command-line option parser
8 .B "#include <mLib/mdwopt.h>"
11 .B "\h'4n'char *arg, *prog;"
12 .B "\h'4n'int opt, ind, err;"
16 .B "char *optarg, optprog;"
17 .B "int optopt, opterr, optind;"
20 .B "\h'4n'const char *name;"
21 .B "\h'4n'int has_arg;"
26 .B "#define OPTF_NOARG = ..."
27 .B "#define OPTF_ARGREQ = ..."
28 .B "#define OPTF_ARGOPT = ..."
29 .B "#define OPTF_ARG = ..."
30 .B "#define OPTF_SWITCH = ..."
31 .B "#define OPTF_NEGATE = ..."
33 .B "#define OPTF_NOLONGS = ..."
34 .B "#define OPTF_NOSHORTS = ..."
35 .B "#define OPTF_NUMBERS = ..."
36 .B "#define OPTF_NEGATION = ..."
37 .B "#define OPTF_ENVVAR = ..."
38 .B "#define OPTF_NOPROGNAME = ..."
39 .B "#define OPTF_NEGNUMBER = ..."
41 .B "#define OPTF_NEGATED = ..."
44 .BI "\*(mTint " argc ", char *const *" argv ,
45 .BI "\h'\w'\*(mT'u'const char *" shortopt ,
46 .BI "\h'\w'\*(mT'u'const struct option *" longopt ", int *" longind ,
47 .BI "\h'\w'\*(mT'u'mdwopt_data *" data ", int " flags );
49 .BI "int getopt(int " argc ", char *const *" argv ", const char *" o );
51 .ds mT \fBint getopt_long(
52 .BI "\*(mTint " argc ", char *const *" argv ,
53 .BI "\h'\w'\*(mT'u'const char * "shortopt ,
54 .BI "\h'\w'\*(mT'u'const struct option *" longopt ", int *" longind );
56 .ds mT \fBint getopt_long_only(
57 .BI "\*(mTint " argc ", char *const *" argv ,
58 .BI "\h'\w'\*(mT'u'const char * "shortopt ,
59 .BI "\h'\w'\*(mT'u'const struct option *" longopt ", int *" longind );
64 function is a command line options parser which is (mostly) compatible
65 with the standard POSIX and GNU
67 functions, although provides more features than either. It's not the
68 most featureful options parser around, but it's good enough for my
69 purposes at the moment.
71 A command line consists of a number of
73 (which may contain spaces, according to various shell quoting
74 conventions). A word may be an option, an argument to an option, or a
75 non-option. An option begins with a special character, usually
79 is also used sometimes. As special exceptions, the word containing only
82 is considered to be a non-option, since it usually represents standard
83 input or output as a filename, and the word containing only a
86 is used to mark all following words as being non-options regardless of
87 their initial character.
89 Traditionally, all words after the first non-option have been considered
90 to be non-options automatically, so that options must be specified
91 before filenames. However, this implementation can extract all the
92 options from the command line regardless of their position. This can
93 usually be disabled by setting one of the environment variables
96 .BR _POSIX_OPTION_ORDER .
98 There are two different styles of options:
102 Traditional Unix (and POSIX) only uses short options. The long options
103 are a GNU convention.
104 .SS "Short option syntax"
105 Short options are the sort which Unix has known for ages: an option is a
106 single letter, preceded by a
108 Short options can be joined together to save space (and possibly to make
109 silly words): e.g., instead of giving options
113 Some short options can have arguments which appear after the option
114 letter, either immediately following, or in the next word; so an option
115 with an argument could be written as
119 Note that options with optional arguments must be written in the second
122 When a short option controls a flag setting, it is sometimes possible to
123 explicitly turn the flag off, as well as turning it on, (usually to
124 override default options). This is usually done by using a
128 to introduce the option. (Some programs use upper-case option letters
129 to indicate this instead.)
130 .SS "Long option syntax"
131 Long options, as popularized by the GNU utilities, are given long-ish
132 memorable names, preceded by a double-dash
134 Since their names are more than a single character, long options can't
135 be combined in the same way as short options. Arguments to long options
136 may be given either in the same word, separated from the option name by
137 an equals sign, or in the following word.
139 Long option names can be abbreviated if necessary, as long as the
140 abbreviation is unique. This means that options can have sensible and
141 memorable names but still not require much typing from an experienced
144 Like short options, long options can control flag settings. The options
145 to manipulate these settings come in pairs: an option of the form
146 .RB ` \-\-set\-flag '
147 might set the flag, while an option of the form
148 .RB ` \-\-no\-set\-flag '
151 It is usual for applications to provide both short and long options with
152 identical behaviour. Some applications with lots of options may only
153 provide long options (although they will often be only two or three
154 characters long). In this case, long options can be preceded with a
157 character, and negated by a
160 .SS "Numerical options"
161 Finally, some (older) programs accept arguments of the form
164 to set some numerical parameter, typically a line count of some kind.
165 .SH "PARSING OPTIONS WITH \fBmdwopt\fP"
166 An application parses its options by calling
168 repeatedly. Each time it is called,
170 returns a value describing the option just read, and stores information
171 about the option in a data block.
173 The data block is a structure containing at least the following members:
176 Pointer to the argument of the current option, or null. Argument
177 strings persist for as long as the underlying command line argument
180 does, so it's usually safe just to remember the pointer.
183 Value of the current option
186 Must be initialized to 0 before the first call to
188 After the last call, it is the index into
190 of the first nonoption argument.
193 Set to nonzero to allow
195 to emit error messages about illegal option syntax. (This would be a
196 flag setting, but it has to be here for
201 Contains the program's name, stripped of any path prefix. This is an
202 obsolete feature: the
204 module does the job in a more sensible way.
206 Prior to the first call to
212 members of the structure must be initialized.
218 describe the command-line argument array which is to be parsed. These
219 will usually be exactly the arguments passed to the program's
222 .SS "Short option parsing"
223 Short options are described by a string,
225 which once upon a time just contained the permitted option characters.
226 Now the options string begins with a collection of flag characters, and
227 various flag characters can be put after options characters to change
230 If the first character of the short options string is
235 the order in which options are read is modified, as follows:
238 Forces the POSIX order to be used. As soon as a non-option is found,
245 treat non-options as being `special' sorts of option. When a non-option
246 word is found, the value 0 is returned, and the actual text of the word
247 is stored as being the option's argument.
250 forces the default order to be used regardless of environment variable
251 settings. The entire command line is scanned for options, which are
252 returned in order. However, during this process, the options are moved
255 array, so that they appear before the non-options.
259 character may be placed after the ordering flag (or at the very
260 beginning if no ordering flag is given) which indicates that the
265 should be returned if a missing argument error is detected.
267 Each option in the string can be followed by a
269 sign, indicating that it can be negated, a
271 sign indicating that it requires an argument, or a
273 string, indicating an optional argument. Both
279 may be given, although the
283 If an option is found, the option character is returned to the caller.
284 A pointer to an argument is stored in the
286 member of the data block; a null pointer is stored if there was no
287 argument. If a negated option was found, the option character is
291 .SS "Long option parsing"
292 Long options are described in a table. Each entry in the
294 .BR "struct option" ,
295 which contains the following members (in order):
297 .B "const char *name"
298 Pointer to the option's name.
301 A flags word describing the option. (The name is historical.)
304 Address of the flag variable to use when this option is matched.
307 Value to store or return when this option is matched.
309 The table is terminated by an entry whose
311 field is a null pointer.
315 finds a long option, it looks the name up in the table. The index of the
316 matching entry is stored in the
322 is null): a value of \-1 indicates that no long option was found. The
323 behaviour is then dependent on the values in the table entry.
329 then the option has a required argument, which may be separated from the
330 option name by an equals sign or placed in the following word. If the
333 is set then the argument is optional. If present, the argument must be
334 in the same word as the option name, separated by an equals sign. It is
335 an error for both flags to be set; if neither is set then the option
336 does not take an argument.
340 is nonzero, it points to an integer to be modified by
342 Usually the value in the
344 field is simply stored in the
346 variable. If the flag
350 member, however, the value is combined with the existing value of the
351 flags using a bitwise OR. If
355 field, then the flag bit will be cleared if a matching negated long
356 option is found. The value 0 is returned.
360 is zero, the value in
364 possibly with bit 8 set if the option was
367 Arguments from long options are stored in the
369 member of the data block.
370 .SS "Other optional features"
373 argument contains a bitmask of features which may be enabled:
376 Don't allow any long options. This makes
378 compatible with traditional Unix
382 A slightly misnamed flag. Short options are read normally. However,
383 long options may also begin with a single dash
387 sign if negated). Long options may not be combined with short options:
388 an option word which begins with a short option must contain only short
392 Read numeric options. If a numeric option is found, the character
394 is returned and the text of the number is stored in the
396 member of the data block.
399 Allow negation of options. Negated options are returned ORed with
403 Options will be read from an environment variable before scanning the
404 actual command line provided. The name of the environment variable is
405 found by capitalizing the program name. (This allows a user to have
406 different default settings for a program, by calling it through
407 different symbolic links.)
410 Don't read the program name from
415 data block member. Options start right at the beginning of
419 Allow negated numeric options. Negated numeric options begin with a
424 .RB ` # ' " | OPTF_NEGATED" .
425 .SS "Compatibility features"
431 correspond to calls to
433 with various flag settings. See the macro definitions for the actual
434 mappings, and the documentation for the functions to see how they're
437 Additionally, there is a global data block, which is specified by
442 The members of this block may be referred to by their traditional names:
445 The argument of the current option.
448 Option code of the current option.
453 is to report errors. This is the default.
456 Index of the first non-option argument.
459 Name of the program, stripped of path prefix.
461 These names aren't considered deprecated: they help make the code easier
462 to read by people used to the traditional
469 Mark Wooding, <mdw@distorted.org.uk>
~mdw / mLib / blob