NAME¶
argtable2 - an ANSI C library for parsing GNU style command line options
SYNOPSIS¶
#include <argtable2.h>
struct arg_lit
struct arg_int
struct arg_dbl
struct arg_str
struct arg_rex
struct arg_file
struct arg_date
struct arg_rem
struct arg_end
struct arg_lit* arg_lit0(const char *shortopts, const char *longopts, const char *glossary)
struct arg_lit* arg_lit1(const char *shortopts, const char *longopts, const char *glossary)
struct arg_lit* arg_litn(const char *shortopts, const char *longopts, int mincount, int maxcount, const char *glossary)
struct arg_int* arg_int0(const char* shortopts, const char* longopts, const char* datatype, const char* glossary)
struct arg_int* arg_int1(const char *shortopts, const char *longopts, const char* datatype, const char *glossary)
struct arg_int* arg_intn(const char *shortopts, const char *longopts, const char* datatype, int mincount, int maxcount, const char *glossary)
struct arg_dbl* arg_dbl0(const char *shortopts, const char *longopts, const char* datatype, const char *glossary)
struct arg_dbl* arg_dbl1(const char *shortopts, const char *longopts, const char* datatype, const char *glossary)
struct arg_dbl* arg_dbln(const char *shortopts, const char *longopts, const char* datatype, int mincount, int maxcount, const char *glossary)
struct arg_str* arg_str0(const char *shortopts, const char *longopts, const char* datatype, const char *glossary)
struct arg_str* arg_str1(const char *shortopts, const char *longopts, const char* datatype, const char *glossary)
struct arg_str* arg_strn(const char *shortopts, const char *longopts, const char* datatype, int mincount, int maxcount, const char *glossary)
struct arg_rex* arg_rex0(const char* shortopts, const char* longopts, const char* pattern, const char* datatype, int flags, const char* glossary)
struct arg_rex* arg_rex1(const char* shortopts, const char* longopts, const char* pattern, const char* datatype, int flags, const char* glossary)
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)
struct arg_file* arg_file0(const char* shortopts, const char* longopts, const char* datatype, const char* glossary)
struct arg_file* arg_file1(const char *shortopts, const char *longopts, const char* datatype, const char *glossary)
struct arg_file* arg_filen(const char *shortopts, const char *longopts, const char* datatype, int mincount, int maxcount, const char *glossary)
struct arg_date* arg_date0const char* shortopts, const char* longopts, const char* format, const char* datatype, const char *glossary)
struct arg_date* arg_date1const char* shortopts, const char* longopts, const char* format, const char* datatype, const char *glossary)
struct arg_date* arg_datenconst char* shortopts, const char* longopts, const char* format, const char* datatype, int mincount, int maxcount, const char *glossary)
struct arg_rem* arg_rem(const char *datatype, const char *glossary)
struct arg_end* arg_end(int maxerrors)
int arg_nullcheck(void **argtable)
int arg_parse(int argc, char **argv, void **argtable)
void arg_print_option(FILE *fp, const char *shortopts, const char *longopts, const char *datatype, const char *suffix)
void arg_print_syntax(FILE *fp, void **argtable, const char *suffix)
void arg_print_syntaxv(FILE *fp, void **argtable, const char *suffix)
void arg_print_glossary(FILE *fp, void **argtable, const char *format)
void arg_print_glossary_gnu(FILE *fp, void **argtable)
void arg_print_errors(FILE *fp, struct arg_end *end, const char *progname)
void arg_freetable(void **argtable, size_t n)
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.
This man page is only for reference. Introductory documentation and example
source code is typically installed under
/usr/share/doc/argtable2/ and
is also available from the argtable homepage at
http://argtable.sourceforge.net.
Constructing an arg_<xxx> data structure¶
Each
arg_<xxx> struct has it own unique set of constructor
functions (defined above) which are typically of the form:
struct arg_int* arg_int0("f", "foo", "<int>", "the foo factor")
struct arg_int* arg_int1("f", "foo", "<int>", "the foo factor")
struct arg_int* arg_intn("f", "foo", "<int>", 2, 4, "the foo factor")
where arg_int0() and arg_int1() are merely abbreviated forms of arg_intn(). They
are provided for convenience when defining command line options that have
either zero-or-one occurrences (mincount=0,maxcount=1) or exactly one
occurrence (mincount=1,maxcount=1) respectively.
The shortopts="f" parameter defines the option's short form tag (eg
-f). Multiple alternative tags may be defined by concatenating them (eg
shortopts="abc" defines options -a, -b and -c as equivalent).
Specify shortopts=NULL when no short option is required.
The longopts="foo" parameter defines the option's long form tag (eg
--foo). Multiple alternative long form tags may be separated by commas (eg
longopts="size,limit" defines --size and --limit). Do not include
any whitespace in the longopts string. Specify longopts=NULL when no long
option is required.
If both shortopts and longopts are NULL then the option is an untagged argument.
The datatype="<int>" parameter is a descriptive string that
denotes the argument data type in error messages, as in --foo=<int>.
Specifying datatype=NULL indicates the default datatype should be used.
Specifying datatype="" effectively disables the datatype display.
The mincount=2 and maxcount=3 parameters specify the minimum and maximum number
of occurrences of the option on the command line. If the command line option
does not appear the required number of times then the parser reports a syntax
error.
The glossary="the foo factor" parameter is another descriptive string.
It appears only in the glossary table that is generated automatically by the
arg_print_glossary function (described later).
- -f, --foo=<int> the foo factor
Specifying a NULL glossary string causes that option to be omitted from the
glossary table.
LITERAL COMMAND LINE OPTIONS¶
-x, -y, -z, --help, --verbose
struct arg_lit
{
struct arg_hdr hdr; /* internal argtable header */
int count; /* number of matching command line options */
};
Literal options take no argument values. Upon a successful parse,
count
is guaranteed to be within the
mincount and
maxcount limits
specified at construction.
INTEGER COMMAND LINE OPTIONS¶
-x2, -z 32MB, --size=734kb, --hex 0x7, --binary 0b10011010, --octal 0o123
Argtable accepts command line integers in decimal (eg 123), hexadecimal (eg
0xFF12), octal (eg 0o123) and binary (eg 0b0101110) formats. It also accepts
integers that are suffixed by "KB" (x1024), "MB"
(x1048576) or "GB" (x1073741824). All characters are case
insensitive
struct arg_int
{
struct arg_hdr hdr; /* internal argtable header */
int count; /* number of values returned in ival[] */
int *ival; /* array of parsed integer values */
};
Upon a successful parse,
count is guaranteed to be within the
mincount and
maxcount limits set for the option at construction
with the appropriate values store in the
ival array. The parser will
not accept any values beyond that limit.
Hint: It is legal to set default values in the
ival array prior to
calling the
arg_parse function. Argtable will not alter
ival
entries for which no command line argument is received.
Hint:
Untagged numeric arguments are not recommended because GNU getopt
mistakes negative values (eg -123) for tagged options (eg -1 -2 -3).
Tagged arguments (eg -x -123, --tag=-123) do not suffer this problem.
REAL/DOUBLE COMMAND LINE OPTIONS¶
-x2.234, -y 7e-03, -z-3.3E+6, --pi=3.1415, --tolerance 1.0E-6
struct arg_dbl
{
struct arg_hdr hdr; /* internal argtable header */
int count; /* number of values returned in dval[] */
double *dval; /* array of parsed double values */
};
Same as
arg_int except the parsed values are stored in
dval as
doubles.
STRING COMMAND LINE OPTIONS¶
-Dmacro, -t mytitle, -m "my message string", --title="hello
world"
struct arg_str
{
struct arg_hdr hdr; /* internal argtable header */
int count; /* number of strings returned in sval[] */
const char **sval; /* array of pointers to parsed argument strings */
};
Same as
arg_int except pointers to the parsed strings are returned in
sval rather than a separate copy of the string. Indeed, these pointers
actually reference the original string buffers stored in argv[], so their
contents should not be altered. However, it is legal to initialise the string
pointers in the
sval array to reference user-supplied default strings
prior to calling arg_parse. Argtable will only alter the contents of
sval when matching command line arguments are detected.
REGULAR EXPRESSION COMMAND LINE OPTIONS¶
commit, update, --command=commit, --command=update
struct arg_rex
{
struct arg_hdr hdr; /* internal argtable header */
int count; /* number of strings returned in sval[] */
const char **sval; /* array of pointers to parsed argument strings */
};
Similar to
arg_str except the string argument values are only accepted if
they match a predefined regular expression. Regular expressions are useful for
matching command line keywords, particularly if case insensitive strings or
pattern matching is required. The regular expression is defined by the
pattern parameter passed to the
arg_rex constructor and
evaluated using regex. Its behaviour can be controlled via standard regex bit
flags. These are passed to argtable via the
flags parameter in the
arg_rex constructor. However the only two of the standard regex flags
are relevant to argtable, namely REG_EXTENDED (use extended regular
expressions rather than basic ones) and REG_ICASE (ignore case). These flags
may be logically ORed if desired. See
regex(3) for more details of
regular expression matching.
Restrictions: Argtable does not support
arg_rex functionality under
Microsoft Windows platforms because the Microsoft compilers do include the
necessary
regex support as standard.
FILENAME COMMAND LINE OPTIONS¶
-o myfile, -Ihome/foo/bar, --input=~/doc/letter.txt, --name a.out
struct arg_file
{
struct arg_hdr hdr; /* internal argtable header */
int count; /* number of filename strings returned */
const char **filename; /* pointer to full filename string */
const char **basename; /* pointer to filename excluding leading path */
const char **extension; /* pointer to the filename extension */
};
Similar to
arg_str but the argument strings are presumed to refer to
filenames hence some additional parsing 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.
For example,
-o /home/heitmann/mydir/foo.txt would be parsed as:
filename[i] = "/home/heitmann/mydir/foo.txt"
basename[i] = "foo.txt"
extension[i] = ".txt"
If the filename has no leading path then the basename is the same as the
filename. If no extension could be identified then it is given as NULL.
Extensions are considered as all text from the last dot in the filename.
Hint: Argtable only ever treats the filenames as strings and never attempts to
open them as files or perform any directory lookups on them.
DATE/TIME COMMAND LINE OPTIONS¶
12/31/04, -d 1982-11-28, --time 23:59
struct arg_date
{
struct arg_hdr hdr; /* internal argtable header */
const char *format; /* user-supplied date format string that was passed to constructor */
int count; /* number of datestamps returned in tmval[] */
struct tm *tmval; /* array of datestamps */
};
Accepts a timestamp string from the command line and converts it to
struct
tm format using the system
strptime function. The time format is
defined by the
format string passed to the
arg_date constructor,
and is passed directly to
strptime. See
strptime(3) for more
details on the format string.
Restrictions: Argtable does not support
arg_date functionality under
Microsoft Windows because the Microsoft compilers do include the necessary
strptime support as standard.
struct arg_rem
{
struct arg_hdr hdr; /* internal argtable header */
};
The
arg_rem 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
datatype and
glossary strings in the output of the
arg_print_syntax,
arg_print_syntaxv, and
arg_print_glossary
functions. As such,
arg_rem 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.
END-OF-TABLE OPTION¶
struct arg_end
{
struct arg_hdr hdr; /* internal argtable header */
int count; /* number of errors returned */
int *error; /* array of error codes */
void **parent; /* pointers to the erroneous command line options */
const char **argval; /* pointers to the erroneous command line argument values */
};
Every argument table must have an arg_end structure as its last entry.
It marks the end of an argument table and stores the error codes generated
by the parser as it processed the argument table.
The maxerrors parameter passed to the arg_end 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 maxerrors limit of 20 is quite reasonable.
The arg_print_errors function will print the errors stored
in the arg_end struct in the same order as they occurred,
so there is no need to understand the internals of the arg_end struct.
FUNCTION REFERENCE¶
int arg_nullcheck (void **argtable)¶
Returns non-zero if the
argtable[] array contains any NULL entries up
until the terminating
arg_end* entry. Returns zero otherwise.
int arg_parse (int argc, char **argv, void **argtable)¶
Parse the command line arguments in
argv[] using the command line syntax
specified in
argtable[], returning the number of errors encountered.
Error details are recorded in the argument table's
arg_end structure
from where they can be displayed later with the
arg_print_errors
function. Upon a successful parse, the
arg_xxx structures referenced in
argtable[] will contain the argument values extracted from the command
line.
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
-K|--scalar=<int>,
where the short options, long options, and datatype are all given as
parameters of this function. It is primarily used within the
arg_xxx
structures'
errorfn 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
suffix 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.
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>]
The
suffix 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.
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>]
The
suffix 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.
Prints a glossary table describing each option in the given argument table. The
format 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.
void arg_print_glossary_gnu (FILE *fp, void **argtable)¶
An alternate form of
arg_print_glossary() 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.
void arg_print_errors (FILE *fp, struct arg_end *end, const char *progname)¶
Prints the details of all errors stored in the
end data structure. The
progname string is prepended to each error message.
void arg_freetable (void ** argtable, size_t n)¶
Deallocates the memory used by each
arg_xxx struct referenced by
argtable[]. It does this by calling
free for each of the
n pointers in the argtable array and then nulling them for safety.
FILES¶
/usr/include/argtable2.h
/usr/lib/libargtable2.a
/usr/lib/libargtable2.so
/usr/man3/argtable2.3
/usr/share/doc/argtable2/
/usr/share/doc/argtable2/example/
AUTHOR¶
Stewart Heitmann <sheitmann@users.sourceforge.net>