1ARGTABLE2(3)             Argtable programmer's manual             ARGTABLE2(3)
2
3
4

NAME

6       argtable2  -  an  ANSI  C  library  for  parsing GNU style command line
7       options
8

SYNOPSIS

10       #include <argtable2.h>
11
12       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
22       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
26       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
30       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
34       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
38       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
42       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
46       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
50       struct arg_rem* arg_rem(const char *datatype, const char *glossary)
51       struct arg_end* arg_end(int maxerrors)
52
53       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

DESCRIPTION

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
71       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
76
77   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
81       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
85       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
91       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
96       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
102       If both shortopts and longopts are NULL then the option is an  untagged
103       argument.
104
105       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
110       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
115       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
119              -f, --foo=<int>    the foo factor
120
121       Specifying a NULL glossary string causes that option to be omitted from
122       the glossary table.
123
124   LITERAL COMMAND LINE OPTIONS
125       -x, -y, -z, --help, --verbose
126
127       struct arg_lit
128          {
129          struct arg_hdr hdr;  /* internal argtable header */
130          int count;           /* number of matching command line options */
131          };
132
133       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
137   INTEGER COMMAND LINE OPTIONS
138       -x2, -z 32MB, --size=734kb, --hex  0x7,  --binary  0b10011010,  --octal
139       0o123
140
141       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
146       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
153       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
158       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
162       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
166   REAL/DOUBLE COMMAND LINE OPTIONS
167       -x2.234, -y 7e-03, -z-3.3E+6, --pi=3.1415, --tolerance 1.0E-6
168
169       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
176       Same as arg_int except the parsed values are stored in dval as doubles.
177
178   STRING COMMAND LINE OPTIONS
179       -Dmacro, -t mytitle, -m "my message string", --title="hello world"
180
181       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
188       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
197   REGULAR EXPRESSION COMMAND LINE OPTIONS
198       commit, update, --command=commit, --command=update
199
200       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
207       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
220       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
224   FILENAME COMMAND LINE OPTIONS
225       -o myfile, -Ihome/foo/bar, --input=~/doc/letter.txt, --name a.out
226
227       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
236       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
243       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
248       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
253       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
257   DATE/TIME COMMAND LINE OPTIONS
258       12/31/04, -d 1982-11-28, --time 23:59
259
260       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
268       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
274       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
278   REMARK OPTIONS
279       struct arg_rem
280          {
281          struct arg_hdr hdr;  /* internal argtable header */
282          };
283
284       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
292   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
302       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
311       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
315

FUNCTION REFERENCE

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
321   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
330   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
341   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
348   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
356   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
364   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
370   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
374   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
379

FILES

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
388

AUTHOR

390       Stewart Heitmann <sheitmann@users.sourceforge.net>
391
392
393
394Argtable2-13                       Jan 2008                       ARGTABLE2(3)
Impressum