chiark / gitweb /
cleanup: All the whitespace fixes, all at once.
[mLib] / man / mdwopt.3
CommitLineData
05fbeb03 1.\" -*-nroff-*-
fbf20b5b 2.TH mdwopt 3 "6 July 1999" "Straylight/Edgeware" "mLib utilities library"
05fbeb03 3.SH "NAME"
4mdwopt \- command-line option parser
5.\" @mdwopt
6.SH "SYNOPSIS"
7.nf
8.B "#include <mLib/mdwopt.h>"
9
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 );
14
15.BI "int getopt(int " argc ", char *const *" argv ", const char *" o );
16
17.BI "int getopt_long(int " argc ", char *const *" argv ,
18.BI " const char * "shortopt ,
19.BI " const struct option *" longopt ", int *" longind );
20
21.BI "int getopt_long_only(int " argc ", char *const *" argv ,
22.BI " const char * "shortopt ,
23.BI " const struct option *" longopt ", int *" longind );
24.fi
25.SH "OVERVIEW"
26The
27.B mdwopt
28function is a command line options parser which is (mostly) compatible
29with the standard POSIX and GNU
30.B getopt
31functions, although provides more features than either. It's not the
32most featureful options parser around, but it's good enough for my
33purposes at the moment.
34.SH "OPTION SYNTAX"
35A command line consists of a number of
36.I words
37(which may contain spaces, according to various shell quoting
38conventions). A word may be an option, an argument to an option, or a
39non-option. An option begins with a special character, usually
40.RB ` \- ',
41although
42.RB ` + '
43is also used sometimes. As special exceptions, the word containing only
44a
45.RB ` \- '
46is considered to be a non-option, since it usually represents standard
47input or output as a filename, and the word containing only a
48double-dash
3751b763 49.RB ` \-\- '
05fbeb03 50is used to mark all following words as being non-options regardless of
51their initial character.
52.PP
53Traditionally, all words after the first non-option have been considered
54to be non-options automatically, so that options must be specified
55before filenames. However, this implementation can extract all the
56options from the command line regardless of their position. This can
57usually be disabled by setting one of the environment variables
58.B POSIXLY_CORRECT
59or
60.BR _POSIX_OPTION_ORDER .
61.PP
62There are two different styles of options:
63.I short
64and
65.IR long .
66Traditional Unix (and POSIX) only uses short options. The long options
67are a GNU convention.
68.SS "Short option syntax"
69Short options are the sort which Unix has known for ages: an option is a
70single letter, preceded by a
3751b763 71.RB ` \- '.
05fbeb03 72Short options can be joined together to save space (and possibly to make
73silly words): e.g., instead of giving options
74.RB ` "\-x \-y" ',
75a user could write
76.RB ` \-xy '.
77Some short options can have arguments which appear after the option
78letter, either immediately following, or in the next word; so an option
79with an argument could be written as
80.RB ` "\-o foo" '
81or as
82.RB ` \-ofoo ').
83Note that options with optional arguments must be written in the second
84style.
85.PP
86When a short option controls a flag setting, it is sometimes possible to
87explicitly turn the flag off, as well as turning it on, (usually to
88override default options). This is usually done by using a
89.RB ` + '
d4efbcd9 90instead of a
05fbeb03 91.RB ` \- '
92to introduce the option. (Some programs use upper-case option letters
93to indicate this instead.)
94.SS "Long option syntax"
95Long options, as popularized by the GNU utilities, are given long-ish
96memorable names, preceded by a double-dash
97.RB ` \-\- '.
98Since their names are more than a single character, long options can't
99be combined in the same way as short options. Arguments to long options
100may be given either in the same word, separated from the option name by
101an equals sign, or in the following word.
102.PP
103Long option names can be abbreviated if necessary, as long as the
104abbreviation is unique. This means that options can have sensible and
105memorable names but still not require much typing from an experienced
106user.
107.PP
108Like short options, long options can control flag settings. The options
109to manipulate these settings come in pairs: an option of the form
110.RB ` \-\-set\-flag '
111might set the flag, while an option of the form
112.RB ` \-\-no\-set\-flag '
113might clear it.
114.PP
115It is usual for applications to provide both short and long options with
116identical behaviour. Some applications with lots of options may only
117provide long options (although they will often be only two or three
118characters long). In this case, long options can be preceded with a
119single
120.RB ` \- '
121character, and negated by a
122.RB ` + '
123character.
124.SS "Numerical options"
125Finally, some (older) programs accept arguments of the form
126.RB ` \- \c
127.IR number ',
128to set some numerical parameter, typically a line count of some kind.
129.SH "PARSING OPTIONS WITH \fBmdwopt\fP"
130An application parses its options by calling
131.B mdwopt
132repeatedly. Each time it is called,
133.B mdwopt
134returns a value describing the option just read, and stores information
135about the option in a data block.
136.PP
137The data block is a structure containing at least the following members:
138.TP
ff76c38f 139.B "char *arg"
05fbeb03 140Pointer to the argument of the current option, or null. Argument
141strings persist for as long as the underlying command line argument
142array
143.I argv
144does, so it's usually safe just to remember the pointer.
145.TP
ff76c38f 146.B "int opt"
05fbeb03 147Value of the current option
148.TP
ff76c38f 149.B "int ind"
05fbeb03 150Must be initialized to 0 before the first call to
151.BR mdwopt .
152After the last call, it is the index into
153.I argv
154of the first nonoption argument.
155.TP
ff76c38f 156.B "int err"
05fbeb03 157Set to nonzero to allow
158.B mdwopt
159to emit error messages about illegal option syntax. (This would be a
160flag setting, but it has to be here for
161.B getopt
162compatibility.)
163.TP
ff76c38f 164.B "char *prog"
05fbeb03 165Contains the program's name, stripped of any path prefix. This is an
166obsolete feature: the
167.BR quis (3)
168module does the job in a more sensible way.
169.PP
170Prior to the first call to
171.BR mdwopt ,
172the
173.B err
174and
175.B ind
3751b763 176members of the structure must be initialized.
05fbeb03 177.PP
178The arguments
179.I argc
180and
181.I argv
182describe the command-line argument array which is to be parsed. These
183will usually be exactly the arguments passed to the program's
184.B main
185function.
186.SS "Short option parsing"
187Short options are described by a string,
188.IR shortopt ,
189which once upon a time just contained the permitted option characters.
190Now the options string begins with a collection of flag characters, and
191various flag characters can be put after options characters to change
192their properties.
193.PP
194If the first character of the short options string is
195.RB ` + ',
196.RB ` \- '
197or
198.RB ` ! ',
199the order in which options are read is modified, as follows:
200.TP
201.RB ` + '
202Forces the POSIX order to be used. As soon as a non-option is found,
203.B mdwopt
204returns \-1.
205.TP
206.RB ` \- '
207Makes
208.B mdwopt
209treat non-options as being `special' sorts of option. When a non-option
210word is found, the value 0 is returned, and the actual text of the word
211is stored as being the option's argument.
212.TP
213.RB ` ! '
214forces the default order to be used regardless of environment variable
215settings. The entire command line is scanned for options, which are
216returned in order. However, during this process, the options are moved
217in the
218.I argv
219array, so that they appear before the non-options.
220.PP
221A
222.RB ` : '
223character may be placed after the ordering flag (or at the very
224beginning if no ordering flag is given) which indicates that the
225character
226.RB ` : ',
227rather than
228.RB ` ? ',
229should be returned if a missing argument error is detected.
230.PP
231Each option in the string can be followed by a
232.RB ` + '
233sign, indicating that it can be negated, a
234.RB ` : '
235sign indicating that it requires an argument, or a
236.RB ` :: '
237string, indicating an optional argument. Both
238.RB ` + '
239and one of
240.RB ` : '
241or
242.RB ` :: '
243may be given, although the
244.RB ` + '
245must come first.
246.PP
247If an option is found, the option character is returned to the caller.
248A pointer to an argument is stored in the
249.B arg
250member of the data block; a null pointer is stored if there was no
251argument. If a negated option was found, the option character is
d2a91066 252returned ORed with
05fbeb03 253.B OPTF_NEGATED
254(bit 8 set).
255.SS "Long option parsing"
256Long options are described in a table. Each entry in the
257table is of type
258.BR "struct option" ,
259which contains the following members (in order):
260.TP
ff76c38f 261.B "const char *name"
05fbeb03 262Pointer to the option's name.
263.TP
ff76c38f 264.B "int has_arg"
05fbeb03 265A flags word describing the option. (The name is historical.)
266.TP
ff76c38f 267.B "int *flag"
05fbeb03 268Address of the flag variable to use when this option is matched.
269.TP
ff76c38f 270.B "int val"
05fbeb03 271Value to store or return when this option is matched.
272.PP
273The table is terminated by an entry whose
274.B name
275field is a null pointer.
276.PP
277When
278.B mdwopt
279finds a long option, it looks the name up in the table. The index of the
280matching entry is stored in the
281.I longind
282variable, passed to
283.B mdwopt
d4efbcd9 284(unless
05fbeb03 285.I longind
286is null): a value of \-1 indicates that no long option was found. The
287behaviour is then dependent on the values in the table entry.
288.PP
289If the flag bit
290.B OPTF_ARGREQ
291is set in
292.B has_arg
293then the option has a required argument, which may be separated from the
294option name by an equals sign or placed in the following word. If the
295flag bit
296.B OPTF_ARGOPT
297is set then the argument is optional. If present, the argument must be
298in the same word as the option name, separated by an equals sign. It is
299an error for both flags to be set; if neither is set then the option
300does not take an argument.
301.PP
302If
303.B flag
304is nonzero, it points to an integer to be modified by
305.BR mdwopt .
306Usually the value in the
307.B val
308field is simply stored in the
309.B flag
310variable. If the flag
311.B OPTF_SWITCH
312is set in the
313.B has_arg
314member, however, the value is combined with the existing value of the
315flags using a bitwise OR. If
316.B OPTF_NEGATE
317is set in the
318.B has_arg
319field, then the flag bit will be cleared if a matching negated long
320option is found. The value 0 is returned.
321.PP
322If
323.B flag
324is zero, the value in
325.B val
326is returned by
327.BR mdwopt ,
328possibly with bit 8 set if the option was
329negated.
330.PP
3751b763 331Arguments from long options are stored in the
05fbeb03 332.B arg
3751b763 333member of the data block.
05fbeb03 334.SS "Other optional features"
335The
336.I flags
337argument contains a bitmask of features which may be enabled:
338.TP
339.B OPTF_NOLONGS
340Don't allow any long options. This makes
341.B mdwopt
342compatible with traditional Unix
343.BR getopt .
344.TP
345.B OPTF_NOSHORTS
346A slightly misnamed flag. Short options are read normally. However,
347long options may also begin with a single dash
348.RB ` \- '
349(or the
350.RB ` + '
351sign if negated). Long options may not be combined with short options:
352an option word which begins with a short option must contain only short
353options.
354.TP
355.B OPTF_NUMBERS
356Read numeric options. If a numeric option is found, the character
357.RB ` # '
358is returned and the text of the number is stored in the
359.B arg
360member of the data block.
361.TP
362.B OPTF_NEGATION
363Allow negation of options. Negated options are returned ORed with
364.BR OPTF_NEGATED .
365.TP
366.B OPTF_ENVVAR
367Options will be read from an environment variable before scanning the
368actual command line provided. The name of the environment variable is
369found by capitalizing the program name. (This allows a user to have
370different default settings for a program, by calling it through
371different symbolic links.)
372.TP
373.B OPTF_NOPROGNAME
374Don't read the program name from
375.IR argv \c
376.BR [0] ,
377and don't set the
378.B prog
379data block member. Options start right at the beginning of
380.IR argv .
381.TP
382.B OPTF_NEGNUMBER
383Allow negated numeric options. Negated numeric options begin with a
384.RB ` + '
385rather than a
386.RB ` \- '.
387The return value is
388.RB ` # ' " | OPTF_NEGATED" .
389.SS "Compatibility features"
390The macros
391.BR getopt ,
392.B getopt_long
393and
394.B getopt_long_only
395correspond to calls to
396.B mdwopt
397with various flag settings. See the macro definitions for the actual
398mappings, and the documentation for the functions to see how they're
399meant to work.
400.PP
401Additionally, there is a global data block, which is specified by
402passing a null
403.I data
404argument to
405.BR mdwopt .
406The members of this block may be referred to by their traditional names:
407.TP
408.B optarg
409The argument of the current option.
410.TP
411.B optopt
412Option code of the current option.
413.TP
414.B opterr
415Nonzero if
416.B mdwopt
417is to report errors. This is the default.
418.TP
419.B optind
420Index of the first non-option argument.
421.TP
422.B optprog
423Name of the program, stripped of path prefix.
424.PP
425These names aren't considered deprecated: they help make the code easier
426to read by people used to the traditional
427.B getopt
428function.
429.SH "SEE ALSO"
430.BR getopt (3),
431.BR mLib (3).
432.SH "AUTHOR"
9b5ac6ff 433Mark Wooding, <mdw@distorted.org.uk>