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 .BI "\*(mTint " argc ", char *const *" argv ,
12 .BI "\h'\w'\*(mT'u'const char *" shortopt ,
13 .BI "\h'\w'\*(mT'u'const struct option *" longopt ", int *" longind ,
14 .BI "\h'\w'\*(mT'u'mdwopt_data *" data ", int " flags );
16 .BI "int getopt(int " argc ", char *const *" argv ", const char *" o );
18 .ds mT \fBint getopt_long(
19 .BI "\*(mTint " argc ", char *const *" argv ,
20 .BI "\h'\w'\*(mT'u'const char * "shortopt ,
21 .BI "\h'\w'\*(mT'u'const struct option *" longopt ", int *" longind );
23 .ds mT \fBint getopt_long_only(
24 .BI "\*(mTint " argc ", char *const *" argv ,
25 .BI "\h'\w'\*(mT'u'const char * "shortopt ,
26 .BI "\h'\w'\*(mT'u'const struct option *" longopt ", int *" longind );
31 function is a command line options parser which is (mostly) compatible
32 with the standard POSIX and GNU
34 functions, although provides more features than either. It's not the
35 most featureful options parser around, but it's good enough for my
36 purposes at the moment.
38 A command line consists of a number of
40 (which may contain spaces, according to various shell quoting
41 conventions). A word may be an option, an argument to an option, or a
42 non-option. An option begins with a special character, usually
46 is also used sometimes. As special exceptions, the word containing only
49 is considered to be a non-option, since it usually represents standard
50 input or output as a filename, and the word containing only a
53 is used to mark all following words as being non-options regardless of
54 their initial character.
56 Traditionally, all words after the first non-option have been considered
57 to be non-options automatically, so that options must be specified
58 before filenames. However, this implementation can extract all the
59 options from the command line regardless of their position. This can
60 usually be disabled by setting one of the environment variables
63 .BR _POSIX_OPTION_ORDER .
65 There are two different styles of options:
69 Traditional Unix (and POSIX) only uses short options. The long options
71 .SS "Short option syntax"
72 Short options are the sort which Unix has known for ages: an option is a
73 single letter, preceded by a
75 Short options can be joined together to save space (and possibly to make
76 silly words): e.g., instead of giving options
80 Some short options can have arguments which appear after the option
81 letter, either immediately following, or in the next word; so an option
82 with an argument could be written as
86 Note that options with optional arguments must be written in the second
89 When a short option controls a flag setting, it is sometimes possible to
90 explicitly turn the flag off, as well as turning it on, (usually to
91 override default options). This is usually done by using a
95 to introduce the option. (Some programs use upper-case option letters
96 to indicate this instead.)
97 .SS "Long option syntax"
98 Long options, as popularized by the GNU utilities, are given long-ish
99 memorable names, preceded by a double-dash
101 Since their names are more than a single character, long options can't
102 be combined in the same way as short options. Arguments to long options
103 may be given either in the same word, separated from the option name by
104 an equals sign, or in the following word.
106 Long option names can be abbreviated if necessary, as long as the
107 abbreviation is unique. This means that options can have sensible and
108 memorable names but still not require much typing from an experienced
111 Like short options, long options can control flag settings. The options
112 to manipulate these settings come in pairs: an option of the form
113 .RB ` \-\-set\-flag '
114 might set the flag, while an option of the form
115 .RB ` \-\-no\-set\-flag '
118 It is usual for applications to provide both short and long options with
119 identical behaviour. Some applications with lots of options may only
120 provide long options (although they will often be only two or three
121 characters long). In this case, long options can be preceded with a
124 character, and negated by a
127 .SS "Numerical options"
128 Finally, some (older) programs accept arguments of the form
131 to set some numerical parameter, typically a line count of some kind.
132 .SH "PARSING OPTIONS WITH \fBmdwopt\fP"
133 An application parses its options by calling
135 repeatedly. Each time it is called,
137 returns a value describing the option just read, and stores information
138 about the option in a data block.
140 The data block is a structure containing at least the following members:
143 Pointer to the argument of the current option, or null. Argument
144 strings persist for as long as the underlying command line argument
147 does, so it's usually safe just to remember the pointer.
150 Value of the current option
153 Must be initialized to 0 before the first call to
155 After the last call, it is the index into
157 of the first nonoption argument.
160 Set to nonzero to allow
162 to emit error messages about illegal option syntax. (This would be a
163 flag setting, but it has to be here for
168 Contains the program's name, stripped of any path prefix. This is an
169 obsolete feature: the
171 module does the job in a more sensible way.
173 Prior to the first call to
179 members of the structure must be initialized.
185 describe the command-line argument array which is to be parsed. These
186 will usually be exactly the arguments passed to the program's
189 .SS "Short option parsing"
190 Short options are described by a string,
192 which once upon a time just contained the permitted option characters.
193 Now the options string begins with a collection of flag characters, and
194 various flag characters can be put after options characters to change
197 If the first character of the short options string is
202 the order in which options are read is modified, as follows:
205 Forces the POSIX order to be used. As soon as a non-option is found,
212 treat non-options as being `special' sorts of option. When a non-option
213 word is found, the value 0 is returned, and the actual text of the word
214 is stored as being the option's argument.
217 forces the default order to be used regardless of environment variable
218 settings. The entire command line is scanned for options, which are
219 returned in order. However, during this process, the options are moved
222 array, so that they appear before the non-options.
226 character may be placed after the ordering flag (or at the very
227 beginning if no ordering flag is given) which indicates that the
232 should be returned if a missing argument error is detected.
234 Each option in the string can be followed by a
236 sign, indicating that it can be negated, a
238 sign indicating that it requires an argument, or a
240 string, indicating an optional argument. Both
246 may be given, although the
250 If an option is found, the option character is returned to the caller.
251 A pointer to an argument is stored in the
253 member of the data block; a null pointer is stored if there was no
254 argument. If a negated option was found, the option character is
258 .SS "Long option parsing"
259 Long options are described in a table. Each entry in the
261 .BR "struct option" ,
262 which contains the following members (in order):
264 .B "const char *name"
265 Pointer to the option's name.
268 A flags word describing the option. (The name is historical.)
271 Address of the flag variable to use when this option is matched.
274 Value to store or return when this option is matched.
276 The table is terminated by an entry whose
278 field is a null pointer.
282 finds a long option, it looks the name up in the table. The index of the
283 matching entry is stored in the
289 is null): a value of \-1 indicates that no long option was found. The
290 behaviour is then dependent on the values in the table entry.
296 then the option has a required argument, which may be separated from the
297 option name by an equals sign or placed in the following word. If the
300 is set then the argument is optional. If present, the argument must be
301 in the same word as the option name, separated by an equals sign. It is
302 an error for both flags to be set; if neither is set then the option
303 does not take an argument.
307 is nonzero, it points to an integer to be modified by
309 Usually the value in the
311 field is simply stored in the
313 variable. If the flag
317 member, however, the value is combined with the existing value of the
318 flags using a bitwise OR. If
322 field, then the flag bit will be cleared if a matching negated long
323 option is found. The value 0 is returned.
327 is zero, the value in
331 possibly with bit 8 set if the option was
334 Arguments from long options are stored in the
336 member of the data block.
337 .SS "Other optional features"
340 argument contains a bitmask of features which may be enabled:
343 Don't allow any long options. This makes
345 compatible with traditional Unix
349 A slightly misnamed flag. Short options are read normally. However,
350 long options may also begin with a single dash
354 sign if negated). Long options may not be combined with short options:
355 an option word which begins with a short option must contain only short
359 Read numeric options. If a numeric option is found, the character
361 is returned and the text of the number is stored in the
363 member of the data block.
366 Allow negation of options. Negated options are returned ORed with
370 Options will be read from an environment variable before scanning the
371 actual command line provided. The name of the environment variable is
372 found by capitalizing the program name. (This allows a user to have
373 different default settings for a program, by calling it through
374 different symbolic links.)
377 Don't read the program name from
382 data block member. Options start right at the beginning of
386 Allow negated numeric options. Negated numeric options begin with a
391 .RB ` # ' " | OPTF_NEGATED" .
392 .SS "Compatibility features"
398 correspond to calls to
400 with various flag settings. See the macro definitions for the actual
401 mappings, and the documentation for the functions to see how they're
404 Additionally, there is a global data block, which is specified by
409 The members of this block may be referred to by their traditional names:
412 The argument of the current option.
415 Option code of the current option.
420 is to report errors. This is the default.
423 Index of the first non-option argument.
426 Name of the program, stripped of path prefix.
428 These names aren't considered deprecated: they help make the code easier
429 to read by people used to the traditional
436 Mark Wooding, <mdw@distorted.org.uk>
~mdw / mLib / blob