3 .\" Manual for option parsing
5 .\" (c) 1999, 2001, 2005, 2007, 2009, 2023, 2024 Straylight/Edgeware
8 .\"----- Licensing notice ---------------------------------------------------
10 .\" This file is part of the mLib utilities library.
12 .\" mLib is free software: you can redistribute it and/or modify it under
13 .\" the terms of the GNU Library General Public License as published by
14 .\" the Free Software Foundation; either version 2 of the License, or (at
15 .\" your option) any later version.
17 .\" mLib is distributed in the hope that it will be useful, but WITHOUT
18 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
19 .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
20 .\" License for more details.
22 .\" You should have received a copy of the GNU Library General Public
23 .\" License along with mLib. If not, write to the Free Software
24 .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
27 .\"--------------------------------------------------------------------------
28 .so ../defs.man \" @@@PRE@@@
30 .\"--------------------------------------------------------------------------
31 .TH mdwopt 3mLib "6 July 1999" "Straylight/Edgeware" "mLib utilities library"
34 .\"--------------------------------------------------------------------------
36 mdwopt \- command-line option parser
38 .\"--------------------------------------------------------------------------
42 .B "#include <mLib/mdwopt.h>"
46 .B " char *arg, *prog;"
47 .B " int opt, ind, err;"
51 .B "char *optarg, optprog;"
52 .B "int optopt, opterr, optind;"
55 .B " const char *name;"
61 .B "#define OPTF_NOARG = ..."
62 .B "#define OPTF_ARGREQ = ..."
63 .B "#define OPTF_ARGOPT = ..."
64 .B "#define OPTF_ARG = ..."
65 .B "#define OPTF_SWITCH = ..."
66 .B "#define OPTF_NEGATE = ..."
68 .B "#define OPTF_NOLONGS = ..."
69 .B "#define OPTF_NOSHORTS = ..."
70 .B "#define OPTF_NUMBERS = ..."
71 .B "#define OPTF_NEGATION = ..."
72 .B "#define OPTF_ENVVAR = ..."
73 .B "#define OPTF_NOPROGNAME = ..."
74 .B "#define OPTF_NEGNUMBER = ..."
76 .B "#define OPTF_NEGATED = ..."
78 .ta \w'\fBint mdwopt('u
79 .BI "int mdwopt(int " argc ", char *const *" argv ,
80 .BI " const char *" shortopt ,
81 .BI " const struct option *" longopt ", int *" longind ,
82 .BI " mdwopt_data *" data ", int " flags );
84 .BI "int getopt(int " argc ", char *const *" argv ", const char *" o );
86 .ta \w'\fBint getopt_long('u
87 .BI "int getopt_long(int " argc ", char *const *" argv ,
88 .BI " const char * "shortopt ,
89 .BI " const struct option *" longopt ", int *" longind );
91 .ta \w'\fBint getopt_long_only('u
92 .BI "int getopt_long_only(int " argc ", char *const *" argv ,
93 .BI " const char * "shortopt ,
94 .BI " const struct option *" longopt ", int *" longind );
97 .\"--------------------------------------------------------------------------
102 function is a command line options parser which is (mostly) compatible
103 with the standard POSIX and GNU
105 functions, although provides more features than either. It's not the
106 most featureful options parser around, but it's good enough for my
107 purposes at the moment.
109 .\"--------------------------------------------------------------------------
112 A command line consists of a number of
114 (which may contain spaces, according to various shell quoting
115 conventions). A word may be an option, an argument to an option, or a
116 non-option. An option begins with a special character, usually
120 is also used sometimes. As special exceptions, the word containing only
123 is considered to be a non-option, since it usually represents standard
124 input or output as a filename, and the word containing only a
127 is used to mark all following words as being non-options regardless of
128 their initial character.
130 Traditionally, all words after the first non-option have been considered
131 to be non-options automatically, so that options must be specified
132 before filenames. However, this implementation can extract all the
133 options from the command line regardless of their position. This can
134 usually be disabled by setting one of the environment variables
137 .BR _POSIX_OPTION_ORDER .
139 There are two different styles of options:
143 Traditional Unix (and POSIX) only uses short options. The long options
144 are a GNU convention.
146 .SS "Short option syntax"
147 Short options are the sort which Unix has known for ages: an option is a
148 single letter, preceded by a
150 Short options can be joined together to save space (and possibly to make
151 silly words): e.g., instead of giving options
155 Some short options can have arguments which appear after the option
156 letter, either immediately following, or in the next word; so an option
157 with an argument could be written as
161 Note that options with optional arguments must be written in the second
164 When a short option controls a flag setting, it is sometimes possible to
165 explicitly turn the flag off, as well as turning it on, (usually to
166 override default options). This is usually done by using a
170 to introduce the option. (Some programs use upper-case option letters
171 to indicate this instead.)
173 .SS "Long option syntax"
174 Long options, as popularized by the GNU utilities, are given long-ish
175 memorable names, preceded by a double-dash
177 Since their names are more than a single character, long options can't
178 be combined in the same way as short options. Arguments to long options
179 may be given either in the same word, separated from the option name by
180 an equals sign, or in the following word.
182 Long option names can be abbreviated if necessary, as long as the
183 abbreviation is unique. This means that options can have sensible and
184 memorable names but still not require much typing from an experienced
187 Like short options, long options can control flag settings. The options
188 to manipulate these settings come in pairs: an option of the form
189 .RB ` \-\-set\-flag '
190 might set the flag, while an option of the form
191 .RB ` \-\-no\-set\-flag '
194 It is usual for applications to provide both short and long options with
195 identical behaviour. Some applications with lots of options may only
196 provide long options (although they will often be only two or three
197 characters long). In this case, long options can be preceded with a
200 character, and negated by a
204 .SS "Numerical options"
205 Finally, some (older) programs accept arguments of the form
208 to set some numerical parameter, typically a line count of some kind.
210 .\"--------------------------------------------------------------------------
211 .SH "PARSING OPTIONS WITH \fBmdwopt\fP"
213 An application parses its options by calling
215 repeatedly. Each time it is called,
217 returns a value describing the option just read, and stores information
218 about the option in a data block.
220 The data block is a structure containing at least the following members:
223 Pointer to the argument of the current option, or null. Argument
224 strings persist for as long as the underlying command line argument
227 does, so it's usually safe just to remember the pointer.
230 Value of the current option
233 Must be initialized to 0 before the first call to
235 After the last call, it is the index into
237 of the first nonoption argument.
240 Set to nonzero to allow
242 to emit error messages about illegal option syntax. (This would be a
243 flag setting, but it has to be here for
248 Contains the program's name, stripped of any path prefix. This is an
249 obsolete feature: the
251 module does the job in a more sensible way.
253 Prior to the first call to
259 members of the structure must be initialized.
265 describe the command-line argument array which is to be parsed. These
266 will usually be exactly the arguments passed to the program's
270 .SS "Short option parsing"
271 Short options are described by a string,
273 which once upon a time just contained the permitted option characters.
274 Now the options string begins with a collection of flag characters, and
275 various flag characters can be put after options characters to change
278 If the first character of the short options string is
283 the order in which options are read is modified, as follows:
286 Forces the POSIX order to be used. As soon as a non-option is found,
293 treat non-options as being `special' sorts of option. When a non-option
294 word is found, the value 0 is returned, and the actual text of the word
295 is stored as being the option's argument.
298 forces the default order to be used regardless of environment variable
299 settings. The entire command line is scanned for options, which are
300 returned in order. However, during this process, the options are moved
303 array, so that they appear before the non-options.
307 character may be placed after the ordering flag (or at the very
308 beginning if no ordering flag is given) which indicates that the
313 should be returned if a missing argument error is detected.
315 Each option in the string can be followed by a
317 sign, indicating that it can be negated, a
319 sign indicating that it requires an argument, or a
321 string, indicating an optional argument. Both
327 may be given, although the
331 If an option is found, the option character is returned to the caller.
332 A pointer to an argument is stored in the
334 member of the data block; a null pointer is stored if there was no
335 argument. If a negated option was found, the option character is
340 .SS "Long option parsing"
341 Long options are described in a table. Each entry in the
343 .BR "struct option" ,
344 which contains the following members (in order):
346 .B "const char *name"
347 Pointer to the option's name.
350 A flags word describing the option. (The name is historical.)
353 Address of the flag variable to use when this option is matched.
356 Value to store or return when this option is matched.
358 The table is terminated by an entry whose
360 field is a null pointer.
364 finds a long option, it looks the name up in the table. The index of the
365 matching entry is stored in the
371 is null): a value of \-1 indicates that no long option was found. The
372 behaviour is then dependent on the values in the table entry.
378 then the option has a required argument, which may be separated from the
379 option name by an equals sign or placed in the following word. If the
382 is set then the argument is optional. If present, the argument must be
383 in the same word as the option name, separated by an equals sign. It is
384 an error for both flags to be set; if neither is set then the option
385 does not take an argument.
389 is nonzero, it points to an integer to be modified by
391 Usually the value in the
393 field is simply stored in the
395 variable. If the flag
399 member, however, the value is combined with the existing value of the
400 flags using a bitwise OR. If
404 field, then the flag bit will be cleared if a matching negated long
405 option is found. The value 0 is returned.
409 is zero, the value in
413 possibly with bit 8 set if the option was
416 Arguments from long options are stored in the
418 member of the data block.
420 .SS "Other optional features"
423 argument contains a bitmask of features which may be enabled:
426 Don't allow any long options. This makes
428 compatible with traditional Unix
432 A slightly misnamed flag. Short options are read normally. However,
433 long options may also begin with a single dash
437 sign if negated). Long options may not be combined with short options:
438 an option word which begins with a short option must contain only short
442 Read numeric options. If a numeric option is found, the character
444 is returned and the text of the number is stored in the
446 member of the data block.
449 Allow negation of options. Negated options are returned ORed with
453 Options will be read from an environment variable before scanning the
454 actual command line provided. The name of the environment variable is
455 found by capitalizing the program name. (This allows a user to have
456 different default settings for a program, by calling it through
457 different symbolic links.)
460 Don't read the program name from
465 data block member. Options start right at the beginning of
469 Allow negated numeric options. Negated numeric options begin with a
474 .RB ` # ' " | OPTF_NEGATED" .
476 .SS "Compatibility features"
482 correspond to calls to
484 with various flag settings. See the macro definitions for the actual
485 mappings, and the documentation for the functions to see how they're
488 Additionally, there is a global data block, which is specified by
493 The members of this block may be referred to by their traditional names:
496 The argument of the current option.
499 Option code of the current option.
504 is to report errors. This is the default.
507 Index of the first non-option argument.
510 Name of the program, stripped of path prefix.
512 These names aren't considered deprecated: they help make the code easier
513 to read by people used to the traditional
517 .\"--------------------------------------------------------------------------
523 .\"--------------------------------------------------------------------------
526 Mark Wooding, <mdw@distorted.org.uk>
528 .\"----- That's all, folks --------------------------------------------------
~mdw / mLib / blob