.TH ARGTABLE2 3 "December 2005" "Argtable2-6" "Argtable programmer's manual"
.SH NAME
argtable2 \- an ANSI C library for parsing GNU style command line options
.SH SYNOPSIS
.nf
\fC#include <argtable2.h>\fP

.RB "struct " arg_lit
.RB "struct " arg_int
.RB "struct " arg_dbl
.RB "struct " arg_str
.RB "struct " arg_rex
.RB "struct " arg_file
.RB "struct " arg_date
.RB "struct " arg_rem
.RB "struct " arg_end
.PP
.RB "struct " arg_xxx "* " arg_xxx0 (...)
.RB "struct " arg_xxx "* " arg_xxx1 (...)
.RB "struct " arg_xxx "* " arg_xxxn (...)
.PP
.RB "int " arg_nullcheck "(void **argtable)"
.RB "int " arg_parse "(int argc, char **argv, void **argtable)"
.RB "void " arg_print_option "(FILE *fp, const char *shortopts, const char *longopts,"
.RB "        const char *datatype, const char *suffix)"
.RB "void " arg_print_syntax "(FILE *fp, void **argtable, const char *suffix)"
.RB "void " arg_print_syntaxv "(FILE *fp, void **argtable, const char *suffix)"
.RB "void " arg_print_glossary "(FILE *fp, void **argtable, const char *format)"
.RB "void " arg_print_glossary_gnu "(FILE *fp, void **argtable)"
.RB "void " arg_print_errors "(FILE *fp, struct arg_end *end, const char *progname)"
.RB "void " arg_freetable "(void **argtable, size_t n)"
.SH DESCRIPTION
Argtable is an ANSI C library for parsing GNU style command line arguments with a minimum of fuss. It enables the programmer to define their program's argument syntax directly in the source code as an array of structs. The command line is then parsed according to that specification and the resulting values stored directly into user-defined program variables where they are accessible to the main program.
.PP
This man page is only for reference. Introductory and advanced texts on argtable should be 
available on this system in pdf, html, and postscript from under \fB/usr/local/share/doc/argtable2/\fP along with example source code.
Alternatively refer to the argtable homepage at http://argtable.sourceforge.net.
.SS Constructing an arg_xxx data structure
Each \fBarg_xxx\fP struct has it own unique set of constructor functions
and while these may differ slightly between \fBarg_xxx\fP structs,
they are generally of the form:
.PP
struct \fBarg_xxx* arg_xxx0\fP (const char *shortopts, const char *longopts, const char *datatype, const char *glossary)
.PP
struct \fBarg_xxx* arg_xxx1\fP (const char *shortopts, const char *longopts, const char *datatype, const char *glossary)
.PP
struct \fBarg_xxx* arg_xxxn\fP (const char *shortopts, const char *longopts, const char *datatype, int mincount, int maxcount, const char *glossary)
.PP
The \fBarg_xxx0()\fP and \fBarg_xxx1()\fP forms are merely abbreviated
forms of \fBarg_xxxn()\fP and are provided as a convenience for
the most common arrangements of command line options; namely those
that have zero-or-one occurrences (mincount=0,maxcount=1) and those
that have one exactly one occurrence (mincount=1,maxcount=1) respectively.
.PP
The \fIconst char* shortopts\fP parameter defines the option's short
form tag (eg: -x, -k3, -D"macro").
It can be left as NULL if a short option is not required, otherwise use it to
specify the desired short option character in the string (without the
leading "-" and without any whitespace).
For example, the short option -v is defined simply as "v".
In fact, a command line option may have multiple alternate short form
tags defined for it by concatenating the desired characters into the
shortopts string.
For instance "abc" defines an option which will accept any of the three
equivalent short forms -a, -b, -c interchangeably.
.PP
The \fIconst char* longopts\fP parameter is similar to \fIshortopts\fP,
except it defines the option's long form tags (eg: --help, --depth=3, --name=myfile.txt).
It too can be left as NULL if not required, and it too can have multiple
equivalent tags defined but these must be separated by commas.
For example, if we wish to define two equivalent long options --quiet and
--silent then we would give longopts as "quiet,silent". Remember not to
include any whitespace.
.PP
If both \fIshortopts\fP and \fIlongopts\fP are given as NULL then the
resulting option is an untagged argument.
.PP
The \fIconst char* datatype\fP parameter is a descriptive string you
can use to customize the appearance of the argument data type in error
messages and so forth. It does not affect the actual data type definition
as that is a fixed property of the \fBarg_xxx\fP struct.
So for example, defining a \fIdatatype\fP of "<bar>" will result in the option
being display something like "-x <bar>" or "--foo=<bar>" depending upon
your option tags.
If given as NULL, the \fIdatatype\fP string will revert to the default
value for the particular \fBarg_xxx\fP struct.
You can effectively disable the default by specifying \fIdatatype\fP
as an empty string.
.PP
The \fIint mincount\fP parameter specifies the minimum number of occurrences
that the option must appear on the command line.
If the option does not appear at least that many times then the parser
reports it as a syntax error.
The \fImincount\fP defaults to 0 for the \fBarg_xxx0()\fP functions and
1 for \fBarg_xxx1()\fP functions.
.PP
The \fIint maxcount\fP parameter specifies the maximum number of occurrences
that the option may appear on the command line.
Any occurrences beyond the maximum are discarded by the parser
reported as syntax errors.
The \fImaxcount\fP defaults to 1 for both the \fBarg_xxx0()\fP and \fBarg_xxx1()\fP functions.
.PP
The \fIconst char* glossary\fP parameter is another descriptive string
but this one appears in the glossary table summarizing the program's
command line options.
The glossary table is generated automatically by the \fBarg_print_glossary\fP
function (see later). For example, a glossary string of "the foobar factor"
would appear in the glossary table along side the option something like:
.IP
\fC--foo=<bar>    the foobar factor\fP
.PP
Specifying a NULL glossary string causes that option to be omitted from
the glossary table.
.PP
See below for the exact definitions of the individual \fBarg_xxx\fP
structs and their constructor functions.
.fi

.SH FUNCTION REFERENCE
.in +1c
.SS "int arg_nullcheck (void **argtable)"
Returns non-zero if the \fIargtable[]\fP array contains any NULL entries
up until the terminating \fBarg_end*\fP entry.
Returns zero otherwise.
.SS "int arg_parse (int argc, char **argv, void **argtable)"
Parse the command line arguments in \fIargv[]\fP using the command line syntax
specified in \fIargtable[]\fP, returning the number of errors encountered.
Error details are recorded in the argument table's
\fBarg_end\fP structure from where they can be displayed later with
the \fBarg_print_errors\fP function.
Upon a successful parse, the \fBarg_xxx\fP structures referenced in \fIargtable[]\fP
will contain the argument values extracted from the command line.
.SS "void arg_print_option (FILE *fp, const char *shortopts, const char *longopts, const char *datatype, const char *suffix)"
This function prints an option's syntax, as in \fB-K|--scalar=<int>\fP,
where the short options, long options, and datatype are all given
as parameters of this function.
It is primarily used within the \fBarg_xxx\fP structures' \fIerrorfn\fP
functions as a way of displaying an option's syntax inside of error
messages. However, it can also be used in user code if desired.
The \fIsuffix\fP string is provided as a convenience for appending newlines
and so forth to the end of the display and can be given as NULL if not required.
.SS "void arg_print_syntax (FILE *fp, void **argtable, const char *suffix)"
Prints the GNU style command line syntax for the given argument table,
as in: [-abcv] [--scalar=<n>] [-o myfile] <file> [<file>]
.br
The \fIsuffix\fP string is provided as a convenience for appending newlines
and so forth to the end of the display and can be given as NULL if not required.
.SS "void arg_print_syntaxv (FILE *fp, void **argtable, const char *suffix)"
Prints the verbose form of the command line syntax for the given argument table,
as in: [-a] [-b] [-c] [--scalar=<n>] [-o myfile] [-v|--verbose] <file> [<file>]
.br
The \fIsuffix\fP string is provided as a convenience for appending newlines
and so forth to the end of the display and can be given as NULL if not required.
.SS "void arg_print_glossary (FILE *fp, void **argtable, const char *format)"
Prints a glossary table describing each option in the given argument table.
The \fIformat\fP string is passed to printf to control the formatting of
each entry in the the glossary.
It must have exactly two "%s" format parameters as in "%-25s %s\\n",
the first is for the option's syntax and the second for its glossary string.
If an option's glossary string is NULL then that option in omitted from
the glossary display.
.SS "void arg_print_glossary_gnu (FILE *fp, void **argtable)"
An alternate form of \fBarg_print_glossary()\fP that prints the glossary
using strict GNU formatting conventions wherein long options are vertically aligned in
a second column, and lines are wrapped at 80 characters.
.SS "void arg_print_errors (FILE *fp, struct \fBarg_end\fP *end, const char *progname)"
Prints the details of all errors stored in the \fIend\fP data structure.
The \fIprogname\fP string is prepended to each error message.
.SS "void arg_freetable (void ** argtable, size_t n)"
Deallocates the memory used by each \fBarg_xxx\fP struct referenced by \fIargtable[]\fP.
It does this by calling \fBfree\fP for each of the \fIn\fP pointers in the argtable array
and then nulling them for safety.

.SH "LITERAL OPTIONS (struct arg_lit)"
.SS Command line examples
-x, -y, -z, --help, --verbose
.SS Data Structure
.nf
struct \fBarg_lit\fP
   {
   struct \fBarg_hdr\fP hdr;
   int count;
   };
.fi
.SS Constructor Functions
.PP
.HP
struct \fBarg_lit* arg_lit0\fP (const char *shortopts, const char *longopts, const char *glossary)
.HP
struct \fBarg_lit* arg_lit1\fP (const char *shortopts, const char *longopts, const char *glossary)
.HP
struct \fBarg_lit* arg_litn\fP (const char *shortopts, const char *longopts, int mincount, int maxcount, const char *glossary)
.SS Description
Literal options take no argument values so all that is to be seen in the
\fBarg_lit\fP struct is the \fIcount\fP of the number of times the option was
present on the command line.
Upon a successful parse, \fIcount\fP is guaranteed to be within
the \fImincount\fP and \fImaxcount\fP limits set for the option at construction.

.SH "INTEGER OPTIONS (struct arg_int)"
.SS Command line examples
-x2, -y 7, -z-3, --size=734, --count 124
.SS Data Structure
.nf
struct \fBarg_int\fP
   {
   struct \fBarg_hdr\fP hdr;
   int count;
   int *ival;
   };
.fi
.SS Constructor Functions
.PP
.HP
struct \fBarg_int* arg_int0\fP (const char *shortopts, const char *longopts, const char *datatype, const char *glossary)
.HP
struct \fBarg_int* arg_int1\fP (const char *shortopts, const char *longopts, const char *datatype, const char *glossary)
.HP
struct \fBarg_int* arg_intn\fP (const char *shortopts, const char *longopts, const char *datatype, int mincount, int maxcount, const char *glossary
.SS Description
The \fBarg_int\fP struct contains the \fIcount\fP of the number of times
the option was present on the command line and a pointer (\fIival\fP) to
an array containing the integer values given with those particular options.
The array is fixed at construction time to hold \fImaxcount\fP integers at most.
.PP
Upon a successful parse, \fIcount\fP is guaranteed to be within
the \fImincount\fP and \fImaxcount\fP limits set for the option at construction
with the appropriate values store in the \fIival\fP array.
The parser will not accept any values beyond that limit.
.PP
It is quite acceptable to set default values in the \fIival\fP array prior
to calling arg_parse if desired as the parser does alter \fIival\fP entries
for which no command line argument is received.

.SH "DOUBLE OPTIONS (struct arg_dbl)"
.SS Command line examples
-x2.234, -y 7e-03, -z-3.3E+6, --pi=3.1415, --tolerance 1.0E-6
.SS Data Structure
.nf
struct \fBarg_dbl\fP
   {
   struct \fBarg_hdr\fP hdr;
   int count;
   double *dval;
   };
.fi
.SS Constructor Functions
.PP
.HP
struct \fBarg_dbl* arg_dbl0\fP (const char *shortopts, const char *longopts, const char *datatype, const char *glossary)
.HP
struct \fBarg_dbl* arg_dbl1\fP (const char *shortopts, const char *longopts, const char *datatype, const char *glossary)
.HP
struct \fBarg_dbl* arg_dbln\fP (const char *shortopts, const char *longopts, const char *datatype, int mincount, int maxcount, const char *glossary
.SS Description
Like \fBarg_int\fP but the arguments values are stored as doubles in \fIdval\fP.

.SH "STRING OPTIONS (struct arg_str)"
.SS Command line examples
-Dmacro, -t mytitle, -m "my message string", --title="hello world"
.SS Data Structure
.nf
struct \fBarg_str\fP
   {
   struct \fBarg_hdr\fP hdr;
   int count;
   const char **sval;
   };
.fi
.SS Constructor Functions
.PP
.HP
struct \fBarg_str* arg_str0\fP (const char *shortopts, const char *longopts, const char *datatype, const char *glossary)
.HP
struct \fBarg_str* arg_str1\fP (const char *shortopts, const char *longopts, const char *datatype, const char *glossary)
.HP
struct \fBarg_str* arg_strn\fP (const char *shortopts, const char *longopts, const char *datatype, int mincount, int maxcount, const char *glossary)
.SS Description
The \fBarg_str\fP struct contains the \fIcount\fP of the number of times
the option was present on the command line and a pointer (\fIsval\fP) to
an array containing pointers to the parsed string values.
The array is fixed at construction time to hold \fImaxcount\fP string pointers at most.
These pointers in this array reference the actual command line string buffers stored in argv[],
so the string contents should not be should not be altered.
Although it is quite acceptable to set default string pointers in the \fIsval\fP array prior
to calling arg_parse as the parser does alter them if no matching command line argument is received.

.SH "REGULAR EXPRESSION OPTIONS (struct arg_rex)"
.SS Command line examples
"hello world", -t mytitle, -m "my message string", --title="hello world"
.SS Data Structure
.nf
struct \fBarg_rex\fP
   {
   struct \fBarg_hdr\fP hdr;
   int count;
   const char **sval;
   };
.fi
.SS Constructor Functions
.PP
.HP
struct \fBarg_rex* arg_rex0\fP (const char *shortopts, const char *longopts, const char *pattern, const char *datatype, int flags, const char *glossary)
.HP
struct \fBarg_rex* arg_rex1\fP (const char *shortopts, const char *longopts, const char *pattern, const char *datatype, int flags, const char *glossary)
.HP
struct \fBarg_rex* arg_rexn\fP (const char *shortopts, const char *longopts, const char *pattern, const char *datatype, int mincount, int maxcount, int flags, const char *glossary)
.SS Description
Like \fBarg_str\fP but but the string argument values are only accepted if they match a predefined regular expression.
The regular expression is defined by the \fIpattern\fP parameter passed to the \fIarg_rex\fP constructor.
The regular expression parsing is done using regex, and its behaviour can be controlled via standard regex bit flags
which are passed to argtable via the \fIflags\fP parameter in the \fIarg_rex\fP conbstructors. However the only two regex
flags that are relevant to argtable are REG_EXTENDED (use extended regular expressions rather than basic ones)
and REG_ICASE (ignore case). These may be logically ORed if desired.
This argument type is useful for matching command line keywords, particularly if case insensitive strings or pattern matching is required. See \fBregex(3)\fP for more details of regular expression matching.
.SS Restrictions
Argtable does not support \fBarg_date\fP functionality under Microsoft Windows platforms as the
Microsoft compilers do include the necessary \fBregex\fP support as standard.

.SH "FILENAME OPTIONS (struct arg_file)"
.SS Command line xamples
-o myfile, -Ihome/foo/bar, --input=~/doc/letter.txt, --name a.out
.SS Data Structure
.nf
struct \fBarg_file\fP
   {
   struct \fBarg_hdr\fP hdr;
   int count;
   const char **filename;
   const char **basename;
   const char **extension;
   };
.fi
.SS Constructor Functions
.PP
.HP
struct \fBarg_file* arg_file0\fP (const char *shortopts, const char *longopts, const char *datatype, const char *glossary)
.HP
struct \fBarg_file* arg_file1\fP (const char *shortopts, const char *longopts, const char *datatype, const char *glossary)
.HP
struct \fBarg_file* arg_filen\fP (const char *shortopts, const char *longopts, const char *datatype, int mincount, int maxcount, const char *glossary)
.SS Description
Like \fBarg_str\fP but the argument strings are presumed to
have filename qualities so some additional pasring is done to
separate out the filename's basename and extension (if they exist).
The three arrays filename[], basename[], extension[] each store up
to maxcount entries, and the i'th entry of each of these arrays
refer to different components of the same string buffer.
.PP
For instance, \fB-o /home/heitmann/mydir/foo.txt\fP would be parsed as:
.in +1c
.nf
filename[i]  = "/home/heitmann/mydir/foo.txt"
basename[i]  =                      "foo.txt"
extension[i] =                          "txt"
.fi
.out -1c
.PP
If the filename has no leading path then the
basename is the same as the filename,
and if no extension could be identified
then it is given as NULL. Note that filename
extensions are defined as all text following the last "."
in the filename.
Thus \fB-o foo\fP would be parsed as:
.in +1c
.nf
filename[i]  = "foo"
basename[i]  = "foo"
extension[i] = NULL
.fi
.out -1c
.PP
As with arg_str, the string pointers in \fIfilename[]\fP,
\fIbasename[]\fP, and \fIextension[]\fP actually refer to
the original \fIargv[]\fP command line string buffers
so you should not attempt to alter them.
.PP
Note also that the parser only ever treats the filenames as strings
and never attempts to open them as files or perform any directory
lookups on them.

.SH "DATE/TIME OPTIONS (struct arg_date)"
.SS Command line examples
12/31/04, -d 1982-11-28, --time 23:59
.SS Data Structure
.nf
struct \fBarg_date\fP
   {
   struct \fBarg_hdr\fP hdr;
   const char *format; 
   int count;
   struct tm *tmval;
   };
.fi
.SS Constructor Functions
.PP
.HP
struct \fBarg_date* arg_date0\fP (const char *shortopts, const char *longopts, const char *format, const char *datatype, const char *glossary) 
.HP
struct \fBarg_date* arg_date1\fP (const char *shortopts, const char *longopts, const char *format, const char *datatype, const char *glossary)
.HP
struct \fBarg_date* arg_daten\fP (const char *shortopts, const char *longopts, const char *format, const char *datatype, int mincount, int maxcount, const char *glossary)
.SS Description
Accepts a timestamp string from the command line and converts it to \fIstruct tm\fP format using the system \fBstrptime\fP
function. The time format is defined by the \fIformat\fP string passed to the \fIarg_date\fP constructor, and is passed
directly to \fBstrptime\fP. See \fBstrptime(3)\fP for more details on the format string.
.SS Restrictions
Argtable does not support \fBarg_date\fP functionality under Microsoft Windows as the
Microsoft compilers do include the necessary \fBstrptime\fP support as standard.

.SH "REMARK OPTIONS (struct arg_rem)"
.SS Data Structure
.nf
struct \fBarg_rem\fP
   {
   struct \fBarg_hdr\fP hdr;
   };
.fi
.SS Constructor Function
.PP
.HP
struct \fBarg_rem* arg_rem\fP (const char* datatype, const char* glossary)
.SS Description
The \fBarg_rem\fP struct is a dummy struct in the sense it does not
represent a command line option to be parsed.
Instead it provides a means to include additional \fIdatatype\fP and
\fIglossary\fP strings in the output of the \fBarg_print_syntax\fP,
\fBarg_print_syntaxv\fP, and \fBarg_print_glossary functions\fP.
As such, \fBarg_rem\fP structs may be used in the argument table to
insert additional lines of text into the glossary descriptions
or to insert additional text fields into the syntax description.
It has no data members apart from the mandatory \fIarg_hdr\fP struct.

.SH "END-OF-TABLE OPTIONS (struct arg_end)"
.SS Data Structure
.nf
struct \fBarg_end\fP
   {
   struct \fBarg_hdr\fP hdr;
   int count;
   int *error;
   void **parent;
   const char **argval;
   };
.fi
.SS Constructor Function
.PP
.HP
struct \fBarg_end* arg_end\fP (int maxerrors)
.SS Description
The arg_end struct is primarily used to mark the end of an argument table
and doesn't represent any command line option.
Every argument table must have an \fBarg_end\fP structure as its last entry.
.PP
Apart from terminating the argument table, the \fBarg_end\fP structure
also stores the error codes generated by the \fBarg_parse\fP function
as it attempts to parse the command line with the given argument table.
The \fImaxerrors\fP parameter passed to the \fBarg_end\fP constructor
specifies the maximum number of errors that the structure can store.
Any further errors are discarded and replaced with the single error code
ARG_ELIMIT which is later reported to the user by the message "too many errors".
A \fImaxerrors\fP limit of 20 is quite reasonable.
.PP
The \fBarg_print_errors\fP function will print the errors stored
in the \fBarg_end\fP struct in the same order as they occurred,
so there is no need to understand the internals of the \fBarg_end\fP struct.
.PP
For those that are curious, the three arrays \fIerror[]\fP, \fIparent[]\fP,
and \fIargval[]\fP are each allocated \fImaxerrors\fP entries at construction.
As usual, the \fI count\fP variable gives the number of entries actually
stored in these arrays. The same value applies to all three arrays as
the i'th entry of each all refer to different aspects of the same error
condition.
.PP
The \fIerror[i]\fP entry holds the error code returned by the \fIhdr.scanfn\fP
function of the particular \fBarg_xxx\fP that is reporting the error.
The meaning if the code is usually known only to the issuing \fBarg_xxx\fP
struct. The predefined error codes that \fBarg_end\fP handles from the
parser itself are the exceptions.
.PP
The \fIparent[i]\fP entry points to the parent \fBarg_xxx\fP
structure that reported the error.
That same \fBarg_xxx\fP structure is also responsible for displaying a
pertinent error message when called on to do so
by the \fBarg_print_errors\fP function.
It calls the \fIhdr.errorfn\fP function of each parent \fBarg_xxx\fP struct
listed in the \fBarg_end\fP structure.
.PP
Lastly, the \fIargval[i]\fP entry points to the command line argument at
which the error occurred, although this may be NULL when there is no relevant
command line value. For instance, if an error reports a missing option
then there will be no matching command line argument value.

.SH "FILES"
/usr/local/include/argtable2.h
.br
/usr/local/lib/libargtable2.a
.br
/usr/local/lib/libargtable2.so
.br
/usr/local/man3/argtable2.3
.br
/usr/local/share/doc/argtable2/
.br
/usr/local/share/doc/argtable2/example/

.SH "AUTHOR"
Stewart Heitmann <sheitmann@users.sourceforge.net>