.TH ARGTABLE2 3 "December 2003" "Argtable-2.2" "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_file
.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_errors "(FILE *fp, struct arg_end *end, const char *progname)"
.RB "void " arg_freetable "(void **argtable, size_t n)"
.SH DESCRIPTION
To parse the command line options, first construct an \fBarg_xxx\fP
struct for each option expected. These structs will hold the values
that are extracted from the command line.
There are various forms of the \fBarg_xxx\fP structs, each one specialized
for a particular type of option (ie: literal, integer, double, string,
filename). Each option may be given a short option tag (eg: -x) and/or
a long option tag (eg: --verbose), or no tags at all in which case the
argument is identified by its position on the command line. The latter
are called untagged arguments.
.PP
Each \fBarg_xxx\fP struct can store multiple occurrences of a command
line option.
When an \fBarg_xxx\fP struct is constructed, we specify the
minimum and maximum number of occurrences that we wish the option to
handle. The \fBarg_xxx\fP constructor function will then allocate sufficient
storage within the struct for the maximum number of occurrences.
If we wish to handle an infinite number of occurrences of an option
then we really only need specify the maximum number to be equal to argc
as that is the maximum number of occurrences that is possible for
any given command line invocation.
Later on when the parsing is performed, the number of occurrences of the
option on the command line is checked for legality. Too many or too
few will be flagged accordingly.
.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:
.HP
struct \fBarg_xxx* arg_xxx0\fP (const char *shortopts, const char *longopts, const char *datatype, const char *glossary)
.HP
struct \fBarg_xxx* arg_xxx1\fP (const char *shortopts, const char *longopts, const char *datatype, const char *glossary)
.HP
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
.SS "Defining the argument table"
.PP
Once the \fBarg_xxx\fP structs are in hand they must be collated into an
argument table. The argument table is merely an array of void pointers
that point to the various \fBarg_xxx\fP structs constructed previously.
The last entry of the argument table must always point to an \fBarg_end\fP struct.
The \fBarg_end\fP struct is a special case in that it does not represent
a command line option but instead serves to terminate the argument table.
It also stores the errors encountered by the parser for that argument table.
Thus when we construct the \fBarg_end\fP struct we specify the maximum number of errors
we wish it to store, errors beyond that limit are discarded.
An arbitrary number like 20 usually suffices.
.PP
The following example shows an argument table that defines the command
line options: [-a] [-b] [-c] [--scalar=<n>] [-v|--verbose] [-o myfile] <file> [<file>]
.nf
.IP
\fCstruct arg_lit *a     = arg_lit0("a", NULL, "the -a option");\fP
\fCstruct arg_lit *b     = arg_lit0("b", NULL, "the -b option");\fP
\fCstruct arg_lit *c     = arg_lit0("c", NULL, "the -c option");\fP
\fCstruct arg_int *scal  = arg_int0(NULL, "scalar","<n>", "foo value");\fP
\fCstruct arg_lit *verb  = arg_lit0("v", "verbose, "verbose output");\fP
\fCstruct arg_file *o    = arg_file0("o", NULL,"myfile", "output file");\fP
\fCstruct arg_file *file = arg_filen(NULL,NULL,"<file>",1,2,"input files");\fP
\fCstruct arg_end *end   = arg_end(20);\fP
\fCvoid *argtable[] = {a,b,c,scal,verb,o,file,end}; \fP
.fi
.PP
Having constructed our \fBarg_xxx\fP structs we should ensure
that all of them were successfully allocated by checking that none
of them returned NULL.
We could do that manually, but the \fBarg_nullcheck\fP function has been
provided for just that purpose. It checks the argument table for
NULL entries and returns non-zero if any were encountered.
.nf
.IP
\fCif (arg_nullcheck(argtable) != 0)
    printf("error: insufficient memory");\fP
.fi
.SS Parsing the command line
With the argument table defined, it is simply a matter of passing it
onto the \fBarg_parse\fP function along with \fBargc\fP and \fBargv\fP.
The parser will extract the command line arguments according to the specifications within the argument table and store the results back
in the \fBarg_xxx\fP data structures.
Any errors that are encountered are recorded in the argument table's
\fBarg_end\fP struct for reporting later and a count of those errors
is returned by the function.
.IP
\fCint nerrors = arg_parse(argc,argv,argtable);\fP
.PP
If the number of errors returned is zero then we know
that the command line arguments were all correctly parsed and their
results are stored in the \fBarg_xxx\fP structs ready for use.
Otherwise we can choose to retry parsing the command line with an
alternative argument table if we have one, or just display the errors and exit.
.SS Error Reporting
If the \fBarg_parse\fP function reported errors then we need to display them
as \fBarg_parse\fP does not do so itself.
As mentioned earlier, the arg_parse function stores the errors it
encounters in the argument table's \fBarg_end\fP struct.
We don't need to know the internal details of the \fBarg_end\fP struct,
we simply call the \fBarg_print_errors\fP function to print those errors in
the order they were encountered.
.IP
\fCif (nerrors>0)
    arg_print_errors(stdout,end,"myprog");\fP
.fi
.PP
Notice that we also pass it the program name, in this case "myprog",
as the function prepends the name to each error
message it prints as in \fBmyprog: invalid option "-x"\fP.
.SS Displaying the command line syntax
The \fBarg_print_syntax\fP and \fBarg_print_syntaxv\fP functions display the
command line syntax defined by an argument table.
The latter is the verbose form (distinguished by the "v" suffix on the function name)
and displays all alternative forms of each option verbatim,
for example:
.IP
[-a] [-b] [-c] [--scalar=<n>] [-o myfile] [-v|--verbose] <file> [<file>]
.PP
Whereas the former displays the syntax in abbreviated GNU style wherein only
the first form of each option is displayed.
Furthermore all short options are concatenated into a single option
string at the head of the display, so for example \fB-a -b -c -v\fP
is displayed as \fB-abcv\fP.
.IP
[-abcv] [--scalar=<n>] [-o myfile] <file> [<file>]
.PP
Notice that optional command line arguments are automatically enclosed in
square brackets whereas mandatory arguments are not.
.SS Displaying the option glossary
The \fBarg_print_glossary\fP function displays a glossary table of
all the command line options defined by an argument table in which
the option's syntax is shown beside the option's glossary string.
.IP
\fCarg_print_glossary(stdout, argtable, "  %-25s %s\\n");\fP
.PP
The format string passed to the \fBarg_print_glossary\fP
function is actually a printf format string.
It must contain exactly two "%s" format parameters, the first
is for the option's syntax string and the second is for the
argument's glossary string.
Here is some example output:
.IP
.nf \fC
-a                the -a option
-b                the -b option
-c                the -c option
--scalar=<n>      foo value
-v,--verbose      verbose option
-o myfile         output file
<file>            input files
\fP
.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_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"
.SS 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
.in +1c
.ti -1c
struct \fBarg_lit* arg_lit0\fP (const char *shortopts, const char *longopts, const char *glossary)
.ti -1c
struct \fBarg_lit* arg_lit1\fP (const char *shortopts, const char *longopts, const char *glossary)
.ti -1c
struct \fBarg_lit* arg_litn\fP (const char *shortopts, const char *longopts, int mincount, int maxcount, const char *glossary)
.in -1c
.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"
.SS 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
.in +1c
.ti -1c
struct \fBarg_int* arg_int0\fP (const char *shortopts, const char *longopts, const char *datatype, const char *glossary)
.ti -1c
struct \fBarg_int* arg_int1\fP (const char *shortopts, const char *longopts, const char *datatype, const char *glossary)
.ti -1c
struct \fBarg_int* arg_intn\fP (const char *shortopts, const char *longopts, const char *datatype, int mincount, int maxcount, const char *glossary
.in -1c
.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"
.SS 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
.in +1c
.ti -1c
struct \fBarg_dbl* arg_dbl0\fP (const char *shortopts, const char *longopts, const char *datatype, const char *glossary)
.ti -1c
struct \fBarg_dbl* arg_dbl1\fP (const char *shortopts, const char *longopts, const char *datatype, const char *glossary)
.ti -1c
struct \fBarg_dbl* arg_dbln\fP (const char *shortopts, const char *longopts, const char *datatype, int mincount, int maxcount, const char *glossary
.in -1c
.SS Description
Like \fBarg_int\fP but the arguments values are stored as doubles in \fIdval\fP.

.SH "STRING OPTIONS"
.SS 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
.in +1c
.ti -1c
struct \fBarg_str* arg_str0\fP (const char *shortopts, const char *longopts, const char *datatype, const char *glossary)
.ti -1c
struct \fBarg_str* arg_str1\fP (const char *shortopts, const char *longopts, const char *datatype, const char *glossary)
.ti -1c
struct \fBarg_str* arg_strn\fP (const char *shortopts, const char *longopts, const char *datatype, int mincount, int maxcount, const char *glossary)
.in -1c
.SS Description
Like \fBarg_int\fP but the arguments values are pointers to strings.
Note that the string pointers in \fIsval[]\fP actually refer to the original
\fIargv[]\fP command line string buffers so you should not attempt to alter them.

.SH "FILENAME OPTIONS"
.SS Examples
-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
.in +1c
.ti -1c
struct \fBarg_file* arg_file0\fP (const char *shortopts, const char *longopts, const char *datatype, const char *glossary)
.ti -1c
struct \fBarg_file* arg_file1\fP (const char *shortopts, const char *longopts, const char *datatype, const char *glossary)
.ti -1c
struct \fBarg_file* arg_filen\fP (const char *shortopts, const char *longopts, const char *datatype, int mincount, int maxcount, const char *glossary)
.in -1c
.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 "REMARK OPTION"
.SS Data Structure
.nf
struct \fBarg_rem\fP
   {
   struct \fBarg_hdr\fP hdr;
   };
.fi
.SS Constructor Function
.in +1c
.ti -1c
struct \fBarg_rem* arg_rem\fP (const char* datatype, const char* glossary)
.in -1c
.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 OPTION"
.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
.in +1c
.ti -1c
struct \fBarg_end* arg_end\fP (int maxerrors)
.in -1c
.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"
<installdir>/include/argtable2.h
.br
<installdir>/lib/libargtable2.a
.br
<installdir>/man/man3/argtable2.3
.br
<installdir>/share/doc/argtable2-x/
.br
<installdir>/share/doc/argtable2-x/examples/
.PP
where <installdir> is typically /usr/local.

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