Man Linux: Main Page and Category List

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_xxx* arg_xxx0(...)
       struct arg_xxx* arg_xxx1(...)
       struct arg_xxx* arg_xxxn(...)

       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 and advanced texts on
       argtable  should  be  available  on  this  system  in  pdf,  html,  and
       postscript from  under  /usr/share/doc/argtable2/  along  with  example
       source   code.    Alternatively  refer  to  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  and
       while  these  may  differ  slightly  between  arg_xxx structs, they are
       generally of the form:

       struct arg_xxx* arg_xxx0 (const char *shortopts, const char  *longopts,
       const char *datatype, const char *glossary)

       struct  arg_xxx* arg_xxx1 (const char *shortopts, const char *longopts,
       const char *datatype, const char *glossary)

       struct arg_xxx* arg_xxxn (const char *shortopts, const char  *longopts,
       const char *datatype, int mincount, int maxcount, const char *glossary)

       The arg_xxx0() and arg_xxx1() forms are  merely  abbreviated  forms  of
       arg_xxxn()  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.

       The const char* shortopts 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.

       The  const  char* longopts parameter is similar to shortopts, 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.

       If  both  shortopts  and  longopts are given as NULL then the resulting
       option is an untagged argument.

       The const char* datatype 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  arg_xxx struct.  So for example,
       defining a datatype 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 datatype string will revert to the default
       value  for  the particular arg_xxx struct.  You can effectively disable
       the default by specifying datatype as an empty string.

       The int mincount 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 mincount defaults to 0 for the arg_xxx0() functions
       and 1 for arg_xxx1() functions.

       The int maxcount 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
       maxcount   defaults  to  1  for  both  the  arg_xxx0()  and  arg_xxx1()
       functions.

       The const char* glossary 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  arg_print_glossary  function  (see later). For example, a glossary
       string of "the foobar factor" would appear in the glossary table  along
       side the option something like:

              --foo=<bar>    the foobar factor

       Specifying a NULL glossary string causes that option to be omitted from
       the glossary table.

       See below for the exact definitions of the individual  arg_xxx  structs
       and their constructor functions.

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.

   void arg_print_glossary (FILE *fp, void **argtable, const char *format)
       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.

LITERAL OPTIONS (struct arg_lit)

   Command line examples
       -x, -y, -z, --help, --verbose

   Data Structure
       struct arg_lit
          {
          struct arg_hdr hdr;
          int count;
          };

   Constructor Functions
       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)

   Description
       Literal options take no argument values so all that is to  be  seen  in
       the  arg_lit  struct is the count of the number of times the option was
       present on the  command  line.   Upon  a  successful  parse,  count  is
       guaranteed  to  be  within the mincount and maxcount limits set for the
       option at construction.

INTEGER OPTIONS (struct arg_int)

   Command line examples
       -x2, -y 7, -z-3, --size=734, --count 124

   Data Structure
       struct arg_int
          {
          struct arg_hdr hdr;
          int count;
          int *ival;
          };

   Constructor Functions
       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

   Description
       The arg_int struct contains the count of the number of times the option
       was  present  on  the  command  line  and  a pointer (ival) to an array
       containing the integer values given with those particular options.  The
       array  is fixed at construction time to hold maxcount integers at most.

       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.

       It is quite acceptable to set default values in the ival array prior to
       calling arg_parse if desired as the parser does alter ival entries  for
       which no command line argument is received.

DOUBLE OPTIONS (struct arg_dbl)

   Command line examples
       -x2.234, -y 7e-03, -z-3.3E+6, --pi=3.1415, --tolerance 1.0E-6

   Data Structure
       struct arg_dbl
          {
          struct arg_hdr hdr;
          int count;
          double *dval;
          };

   Constructor Functions
       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

   Description
       Like arg_int but the arguments values are stored as doubles in dval.

STRING OPTIONS (struct arg_str)

   Command line examples
       -Dmacro, -t mytitle, -m "my message string", --title="hello world"

   Data Structure
       struct arg_str
          {
          struct arg_hdr hdr;
          int count;
          const char **sval;
          };

   Constructor Functions
       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)

   Description
       The arg_str struct contains the count of the number of times the option
       was present on the command line  and  a  pointer  (sval)  to  an  array
       containing pointers to the parsed string values.  The array is fixed at
       construction time to hold maxcount  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 sval array prior to calling  arg_parse  as  the  parser
       does alter them if no matching command line argument is received.

REGULAR EXPRESSION OPTIONS (struct arg_rex)

   Command line examples
       "hello  world",  -t  mytitle,  -m  "my  message string", --title="hello
       world"

   Data Structure
       struct arg_rex
          {
          struct arg_hdr hdr;
          int count;
          const char **sval;
          };

   Constructor Functions
       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)

   Description
       Like arg_str but but the string argument values are  only  accepted  if
       they  match a predefined regular expression.  The regular expression is
       defined by the pattern parameter passed  to  the  arg_rex  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 flags parameter in the arg_rex 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  regex(3)  for
       more details of regular expression matching.

   Restrictions
       Argtable  does  not  support  arg_date  functionality  under  Microsoft
       Windows platforms as the Microsoft compilers do include  the  necessary
       regex support as standard.

FILENAME OPTIONS (struct arg_file)

   Command line xamples
       -o myfile, -Ihome/foo/bar, --input=~/doc/letter.txt, --name a.out

   Data Structure
       struct arg_file
          {
          struct arg_hdr hdr;
          int count;
          const char **filename;
          const char **basename;
          const char **extension;
          };

   Constructor Functions
       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)

   Description
       Like  arg_str  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.

       For instance, -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, 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 -o foo would be parsed
       as:
           filename[i]  = "foo"
           basename[i]  = "foo"
           extension[i] = NULL

       As with arg_str, the string pointers  in  filename[],  basename[],  and
       extension[]  actually  refer to the original argv[] command line string
       buffers so you should not attempt to alter them.

       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.

DATE/TIME OPTIONS (struct arg_date)

   Command line examples
       12/31/04, -d 1982-11-28, --time 23:59

   Data Structure
       struct arg_date
          {
          struct arg_hdr hdr;
          const char *format;
          int count;
          struct tm *tmval;
          };

   Constructor Functions
       struct  arg_date*  arg_date0  (const  char   *shortopts,   const   char
              *longopts,  const char *format, const char *datatype, const char
              *glossary)

       struct  arg_date*  arg_date1  (const  char   *shortopts,   const   char
              *longopts,  const char *format, const char *datatype, const char
              *glossary)

       struct  arg_date*  arg_daten  (const  char   *shortopts,   const   char
              *longopts,   const  char  *format,  const  char  *datatype,  int
              mincount, int maxcount, const char *glossary)

   Description
       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  as  the  Microsoft compilers do include the necessary strptime
       support as standard.

REMARK OPTIONS (struct arg_rem)

   Data Structure
       struct arg_rem
          {
          struct arg_hdr hdr;
          };

   Constructor Function
       struct arg_rem* arg_rem (const char* datatype, const char* glossary)

   Description
       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.   It  has  no  data
       members apart from the mandatory arg_hdr struct.

END-OF-TABLE OPTIONS (struct arg_end)

   Data Structure
       struct arg_end
          {
          struct arg_hdr hdr;
          int count;
          int *error;
          void **parent;
          const char **argval;
          };

   Constructor Function
       struct arg_end* arg_end (int maxerrors)

   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 arg_end structure as its last entry.

       Apart  from  terminating the argument table, the arg_end structure also
       stores the error codes  generated  by  the  arg_parse  function  as  it
       attempts  to parse the command line with the given 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.

       For those that are curious, the three  arrays  error[],  parent[],  and
       argval[]  are  each  allocated  maxerrors  entries at construction.  As
       usual, the  count 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.

       The  error[i]  entry  holds  the  error code returned by the hdr.scanfn
       function of the particular arg_xxx that is reporting  the  error.   The
       meaning  if  the  code  is  usually  known  only to the issuing arg_xxx
       struct. The predefined error codes that arg_end handles from the parser
       itself are the exceptions.

       The  parent[i]  entry  points  to  the  parent  arg_xxx  structure that
       reported the error.  That same arg_xxx structure  is  also  responsible
       for displaying a pertinent error message when called on to do so by the
       arg_print_errors function.  It calls the hdr.errorfn function  of  each
       parent arg_xxx struct listed in the arg_end structure.

       Lastly,  the  argval[i]  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.

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>