1ARGTABLE2(3) Argtable programmer's manual ARGTABLE2(3)
2
6 argtable2 - an ANSI C library for parsing GNU style command line
7 options
8
10 #include <argtable2.h>
11 struct arg_lit
13 struct arg_int
14 struct arg_dbl
15 struct arg_str
16 struct arg_rex
17 struct arg_file
18 struct arg_date
19 struct arg_rem
20 struct arg_end
21 struct arg_lit* arg_lit0(const char *shortopts, const char *longopts, const char *glossary)
23 struct arg_lit* arg_lit1(const char *shortopts, const char *longopts, const char *glossary)
24 struct arg_lit* arg_litn(const char *shortopts, const char *longopts, int mincount, int maxcount, const char *glossary)
25 struct arg_int* arg_int0(const char* shortopts, const char* longopts, const char* datatype, const char* glossary)
27 struct arg_int* arg_int1(const char *shortopts, const char *longopts, const char* datatype, const char *glossary)
28 struct arg_int* arg_intn(const char *shortopts, const char *longopts, const char* datatype, int mincount, int maxcount, const char *glossary)
29 struct arg_dbl* arg_dbl0(const char *shortopts, const char *longopts, const char* datatype, const char *glossary)
31 struct arg_dbl* arg_dbl1(const char *shortopts, const char *longopts, const char* datatype, const char *glossary)
32 struct arg_dbl* arg_dbln(const char *shortopts, const char *longopts, const char* datatype, int mincount, int maxcount, const char *glossary)
33 struct arg_str* arg_str0(const char *shortopts, const char *longopts, const char* datatype, const char *glossary)
35 struct arg_str* arg_str1(const char *shortopts, const char *longopts, const char* datatype, const char *glossary)
36 struct arg_str* arg_strn(const char *shortopts, const char *longopts, const char* datatype, int mincount, int maxcount, const char *glossary)
37 struct arg_rex* arg_rex0(const char* shortopts, const char* longopts, const char* pattern, const char* datatype, int flags, const char* glossary)
39 struct arg_rex* arg_rex1(const char* shortopts, const char* longopts, const char* pattern, const char* datatype, int flags, const char* glossary)
40 struct arg_rex* arg_rexn(const char* shortopts, const char* longopts, const char* pattern, const char* datatype, int mincount, int maxcount, int flags, const char* glossary)
41 struct arg_file* arg_file0(const char* shortopts, const char* longopts, const char* datatype, const char* glossary)
43 struct arg_file* arg_file1(const char *shortopts, const char *longopts, const char* datatype, const char *glossary)
44 struct arg_file* arg_filen(const char *shortopts, const char *longopts, const char* datatype, int mincount, int maxcount, const char *glossary)
45 struct arg_date* arg_date0const char* shortopts, const char* longopts, const char* format, const char* datatype, const char *glossary)
47 struct arg_date* arg_date1const char* shortopts, const char* longopts, const char* format, const char* datatype, const char *glossary)
48 struct arg_date* arg_datenconst char* shortopts, const char* longopts, const char* format, const char* datatype, int mincount, int maxcount, const char *glossary)
49 struct arg_rem* arg_rem(const char *datatype, const char *glossary)
51 struct arg_end* arg_end(int maxerrors)
52 int arg_nullcheck(void **argtable)
54 int arg_parse(int argc, char **argv, void **argtable)
55 void arg_print_option(FILE *fp, const char *shortopts, const char *longopts, const char *datatype, const char *suffix)
56 void arg_print_syntax(FILE *fp, void **argtable, const char *suffix)
57 void arg_print_syntaxv(FILE *fp, void **argtable, const char *suffix)
58 void arg_print_glossary(FILE *fp, void **argtable, const char *format)
59 void arg_print_glossary_gnu(FILE *fp, void **argtable)
60 void arg_print_errors(FILE *fp, struct arg_end *end, const char *progname)
61 void arg_freetable(void **argtable, size_t n)
62
64 Argtable is an ANSI C library for parsing GNU style command line argu‐
65 ments with a minimum of fuss. It enables the programmer to define their
66 program's argument syntax directly in the source code as an array of
67 structs. The command line is then parsed according to that specifica‐
68 tion and the resulting values stored directly into user-defined program
69 variables where they are accessible to the main program.
70 This man page is only for reference. Introductory documentation and
72 example source code is typically installed under
73 /usr/share/doc/argtable2/ and is also available from the argtable home‐
74 page at http://argtable.sourceforge.net.
75 Constructing an arg_<xxx> data structure
78 Each arg_<xxx> struct has it own unique set of constructor functions
79 (defined above) which are typically of the form:
80 struct arg_int* arg_int0("f", "foo", "<int>", "the foo factor")
82 struct arg_int* arg_int1("f", "foo", "<int>", "the foo factor")
83 struct arg_int* arg_intn("f", "foo", "<int>", 2, 4, "the foo factor")
84 where arg_int0() and arg_int1() are merely abbreviated forms of
86 arg_intn(). They are provided for convenience when defining command
87 line options that have either zero-or-one occurrences (mincount=0,max‐
88 count=1) or exactly one occurrence (mincount=1,maxcount=1) respec‐
89 tively.
90 The shortopts="f" parameter defines the option's short form tag (eg
92 -f). Multiple alternative tags may be defined by concatenating them
93 (eg shortopts="abc" defines options -a, -b and -c as equivalent).
94 Specify shortopts=NULL when no short option is required.
95 The longopts="foo" parameter defines the option's long form tag (eg
97 --foo). Multiple alternative long form tags may be separated by commas
98 (eg longopts="size,limit" defines --size and --limit). Do not include
99 any whitespace in the longopts string. Specify longopts=NULL when no
100 long option is required.
101 If both shortopts and longopts are NULL then the option is an untagged
103 argument.
104 The datatype="<int>" parameter is a descriptive string that denotes the
106 argument data type in error messages, as in --foo=<int>. Specifying
107 datatype=NULL indicates the default datatype should be used. Specify‐
108 ing datatype="" effectively disables the datatype display.
109 The mincount=2 and maxcount=3 parameters specify the minimum and maxi‐
111 mum number of occurrences of the option on the command line. If the
112 command line option does not appear the required number of times then
113 the parser reports a syntax error.
114 The glossary="the foo factor" parameter is another descriptive string.
116 It appears only in the glossary table that is generated automatically
117 by the arg_print_glossary function (described later).
118 -f, --foo=<int> the foo factor
120 Specifying a NULL glossary string causes that option to be omitted from
122 the glossary table.
123 LITERAL COMMAND LINE OPTIONS
125 -x, -y, -z, --help, --verbose
126 struct arg_lit
128 {
129 struct arg_hdr hdr; /* internal argtable header */
130 int count; /* number of matching command line options */
131 };
132 Literal options take no argument values. Upon a successful parse, count
134 is guaranteed to be within the mincount and maxcount limits specified
135 at construction.
136 INTEGER COMMAND LINE OPTIONS
138 -x2, -z 32MB, --size=734kb, --hex 0x7, --binary 0b10011010, --octal
139 0o123
140 Argtable accepts command line integers in decimal (eg 123), hexadecimal
142 (eg 0xFF12), octal (eg 0o123) and binary (eg 0b0101110) formats. It
143 also accepts integers that are suffixed by "KB" (x1024), "MB"
144 (x1048576) or "GB" (x1073741824). All characters are case insensitive
145 struct arg_int
147 {
148 struct arg_hdr hdr; /* internal argtable header */
149 int count; /* number of values returned in ival[] */
150 int *ival; /* array of parsed integer values */
151 };
152 Upon a successful parse, count is guaranteed to be within the mincount
154 and maxcount limits set for the option at construction with the appro‐
155 priate values store in the ival array. The parser will not accept any
156 values beyond that limit.
157 Hint: It is legal to set default values in the ival array prior to
159 calling the arg_parse function. Argtable will not alter ival entries
160 for which no command line argument is received.
161 Hint: Untagged numeric arguments are not recommended because GNU getopt
163 mistakes negative values (eg -123) for tagged options (eg -1 -2 -3).
164 Tagged arguments (eg -x -123, --tag=-123) do not suffer this problem.
165 REAL/DOUBLE COMMAND LINE OPTIONS
167 -x2.234, -y 7e-03, -z-3.3E+6, --pi=3.1415, --tolerance 1.0E-6
168 struct arg_dbl
170 {
171 struct arg_hdr hdr; /* internal argtable header */
172 int count; /* number of values returned in dval[] */
173 double *dval; /* array of parsed double values */
174 };
175 Same as arg_int except the parsed values are stored in dval as doubles.
177 STRING COMMAND LINE OPTIONS
179 -Dmacro, -t mytitle, -m "my message string", --title="hello world"
180 struct arg_str
182 {
183 struct arg_hdr hdr; /* internal argtable header */
184 int count; /* number of strings returned in sval[] */
185 const char **sval; /* array of pointers to parsed argument strings */
186 };
187 Same as arg_int except pointers to the parsed strings are returned in
189 sval rather than a separate copy of the string. Indeed, these pointers
190 actually reference the original string buffers stored in argv[], so
191 their contents should not be altered. However, it is legal to ini‐
192 tialise the string pointers in the sval array to reference user-sup‐
193 plied default strings prior to calling arg_parse. Argtable will only
194 alter the contents of sval when matching command line arguments are
195 detected.
196 REGULAR EXPRESSION COMMAND LINE OPTIONS
198 commit, update, --command=commit, --command=update
199 struct arg_rex
201 {
202 struct arg_hdr hdr; /* internal argtable header */
203 int count; /* number of strings returned in sval[] */
204 const char **sval; /* array of pointers to parsed argument strings */
205 };
206 Similar to arg_str except the string argument values are only accepted
208 if they match a predefined regular expression. Regular expressions are
209 useful for matching command line keywords, particularly if case insen‐
210 sitive strings or pattern matching is required. The regular expression
211 is defined by the pattern parameter passed to the arg_rex constructor
212 and evaluated using regex. Its behaviour can be controlled via stan‐
213 dard regex bit flags. These are passed to argtable via the flags param‐
214 eter in the arg_rex constructor. However the only two of the standard
215 regex flags are relevant to argtable, namely REG_EXTENDED (use extended
216 regular expressions rather than basic ones) and REG_ICASE (ignore
217 case). These flags may be logically ORed if desired. See regex(3) for
218 more details of regular expression matching.
219 Restrictions: Argtable does not support arg_rex functionality under Mi‐
221 crosoft Windows platforms because the Microsoft compilers do include
222 the necessary regex support as standard.
223 FILENAME COMMAND LINE OPTIONS
225 -o myfile, -Ihome/foo/bar, --input=~/doc/letter.txt, --name a.out
226 struct arg_file
228 {
229 struct arg_hdr hdr; /* internal argtable header */
230 int count; /* number of filename strings returned */
231 const char **filename; /* pointer to full filename string */
232 const char **basename; /* pointer to filename excluding leading path */
233 const char **extension; /* pointer to the filename extension */
234 };
235 Similar to arg_str but the argument strings are presumed to refer to
237 filenames hence some additional parsing is done to separate out the
238 filename's basename and extension (if they exist). The three arrays
239 filename[], basename[], extension[] each store up to maxcount entries,
240 and the i'th entry of each of these arrays refer to different compo‐
241 nents of the same string buffer.
242 For example, -o /home/heitmann/mydir/foo.txt would be parsed as:
244 filename[i] = "/home/heitmann/mydir/foo.txt"
245 basename[i] = "foo.txt"
246 extension[i] = ".txt"
247 If the filename has no leading path then the basename is the same as
249 the filename. If no extension could be identified then it is given as
250 NULL. Extensions are considered as all text from the last dot in the
251 filename.
252 Hint: Argtable only ever treats the filenames as strings and never
254 attempts to open them as files or perform any directory lookups on
255 them.
256 DATE/TIME COMMAND LINE OPTIONS
258 12/31/04, -d 1982-11-28, --time 23:59
259 struct arg_date
261 {
262 struct arg_hdr hdr; /* internal argtable header */
263 const char *format; /* user-supplied date format string that was passed to constructor */
264 int count; /* number of datestamps returned in tmval[] */
265 struct tm *tmval; /* array of datestamps */
266 };
267 Accepts a timestamp string from the command line and converts it to
269 struct tm format using the system strptime function. The time format is
270 defined by the format string passed to the arg_date constructor, and is
271 passed directly to strptime. See strptime(3) for more details on the
272 format string.
273 Restrictions: Argtable does not support arg_date functionality under
275 Microsoft Windows because the Microsoft compilers do include the neces‐
276 sary strptime support as standard.
277 REMARK OPTIONS
279 struct arg_rem
280 {
281 struct arg_hdr hdr; /* internal argtable header */
282 };
283 The arg_rem struct is a dummy struct in the sense it does not represent
285 a command line option to be parsed. Instead it provides a means to
286 include additional datatype and glossary strings in the output of the
287 arg_print_syntax, arg_print_syntaxv, and arg_print_glossary functions.
288 As such, arg_rem structs may be used in the argument table to insert
289 additional lines of text into the glossary descriptions or to insert
290 additional text fields into the syntax description.
291 END-OF-TABLE OPTION
293 struct arg_end
294 {
295 struct arg_hdr hdr; /* internal argtable header */
296 int count; /* number of errors returned */
297 int *error; /* array of error codes */
298 void **parent; /* pointers to the erroneous command line options */
299 const char **argval; /* pointers to the erroneous command line argument values */
300 };
301 Every argument table must have an arg_end structure as its last entry.
303 It marks the end of an argument table and stores the error codes generated
304 by the parser as it processed the argument table.
305 The maxerrors parameter passed to the arg_end constructor
306 specifies the maximum number of errors that the structure can store.
307 Any further errors are discarded and replaced with the single error code
308 ARG_ELIMIT which is later reported to the user by the message "too many errors".
309 A maxerrors limit of 20 is quite reasonable.
310 The arg_print_errors function will print the errors stored
312 in the arg_end struct in the same order as they occurred,
313 so there is no need to understand the internals of the arg_end struct.
314
317 int arg_nullcheck (void **argtable)
318 Returns non-zero if the argtable[] array contains any NULL entries up
319 until the terminating arg_end* entry. Returns zero otherwise.
320 int arg_parse (int argc, char **argv, void **argtable)
322 Parse the command line arguments in argv[] using the command line syn‐
323 tax specified in argtable[], returning the number of errors encoun‐
324 tered. Error details are recorded in the argument table's arg_end
325 structure from where they can be displayed later with the
326 arg_print_errors function. Upon a successful parse, the arg_xxx struc‐
327 tures referenced in argtable[] will contain the argument values
328 extracted from the command line.
329 void arg_print_option (FILE *fp, const char *shortopts, const char *lon‐
331 gopts, const char *datatype, const char *suffix)
332 This function prints an option's syntax, as in -K|--scalar=<int>, where
333 the short options, long options, and datatype are all given as parame‐
334 ters of this function. It is primarily used within the arg_xxx struc‐
335 tures' errorfn functions as a way of displaying an option's syntax
336 inside of error messages. However, it can also be used in user code if
337 desired. The suffix string is provided as a convenience for appending
338 newlines and so forth to the end of the display and can be given as
339 NULL if not required.
340 void arg_print_syntax (FILE *fp, void **argtable, const char *suffix)
342 Prints the GNU style command line syntax for the given argument table,
343 as in: [-abcv] [--scalar=<n>] [-o myfile] <file> [<file>]
344 The suffix string is provided as a convenience for appending newlines
345 and so forth to the end of the display and can be given as NULL if not
346 required.
347 void arg_print_syntaxv (FILE *fp, void **argtable, const char *suffix)
349 Prints the verbose form of the command line syntax for the given argu‐
350 ment table, as in: [-a] [-b] [-c] [--scalar=<n>] [-o myfile] [-v|--ver‐
351 bose] <file> [<file>]
352 The suffix string is provided as a convenience for appending newlines
353 and so forth to the end of the display and can be given as NULL if not
354 required.
355 void arg_print_glossary (FILE *fp, void **argtable, const char *format)
357 Prints a glossary table describing each option in the given argument
358 table. The format string is passed to printf to control the formatting
359 of each entry in the the glossary. It must have exactly two "%s" for‐
360 mat parameters as in "%-25s %s\n", the first is for the option's syntax
361 and the second for its glossary string. If an option's glossary string
362 is NULL then that option in omitted from the glossary display.
363 void arg_print_glossary_gnu (FILE *fp, void **argtable)
365 An alternate form of arg_print_glossary() that prints the glossary
366 using strict GNU formatting conventions wherein long options are verti‐
367 cally aligned in a second column, and lines are wrapped at 80 charac‐
368 ters.
369 void arg_print_errors (FILE *fp, struct arg_end *end, const char *progname)
371 Prints the details of all errors stored in the end data structure. The
372 progname string is prepended to each error message.
373 void arg_freetable (void ** argtable, size_t n)
375 Deallocates the memory used by each arg_xxx struct referenced by
376 argtable[]. It does this by calling free for each of the n pointers in
377 the argtable array and then nulling them for safety.
378
381 /usr/include/argtable2.h
382 /usr/lib/libargtable2.a
383 /usr/lib/libargtable2.so
384 /usr/man3/argtable2.3
385 /usr/share/doc/argtable2/
386 /usr/share/doc/argtable2/example/
387
390 Stewart Heitmann <sheitmann@users.sourceforge.net>
391Argtable2-13 Jan 2008 ARGTABLE2(3)