Legal notice

Overview

Styles of command line arguments.

Optional arguments and default values.

Supported platforms

MIPSpro C/C++ on IRIX 6.2, 6.3 and IRIX64 6.2
DEC C/C++ on Digital Unix V4.0 (OSF/1)
GNU gcc/g++ 2.7.2 on SunOS 5.5.1 and Linux 2.0.30.

Installation

If you get the "all tests passed" message then you can be confident argtable is working properly.

Edit the INSTALL_DIR variable in the top level Makefile to be the path where you would like to install the argtable libraries and documentation. Nominally it is defined as INSTALL_DIR=/usr. The install process will put files in the directories:
${INSTALL_DIR}/include
${INSTALL_DIR}/lib
${INSTALL_DIR}/man/man3/
${INSTALL_DIR}/doc/argtable
If these directories do not already exist you may have to create them manually, depending upon your system.

As root, type make install to install argtable into ${INSTALL_DIR}. You may later use make uninstall to remove these files.

Argument tables in detail.

typedef enum {arg_int=0,arg_dbl,arg_str,arg_bool,arg_lit} arg_type;
typedef struct
  {
  char *tagstr;        /* argument tag string */
  char *argname;       /* argument name string */
  arg_type argtype;    /* argument data type */
  void *valueptr;      /* pointer to user storage location */
  char *defaultstr;    /* default argument value, as a string */
  char *argdescrip;    /* argument description string */
  } arg_rec;

int main(int argc, char **argv) 
  {
  char str[50]; 
  double grad; 
  int c; 
  arg_rec argtable[] = 
    {
    {"-tit ", "<title>", arg_str, str, "noname","\t\t title"}, 
    {"grad:", "gradient",arg_dbl, &grad, NULL, "\t line gradient"},
    {NULL, "y-int", arg_int, &c, "0", "\t\t y-intercept"} 
    }; 
  const size_t narg = sizeof(argtable)/sizeof(arg_rec); 
  ...

The name string:
The second field of arg_rec is the argument's name string. It is not actually used to process the command line arguments, rather it defines the name of the argument as it appears in the description strings generated by the arg_syntax() and arg_glossary() library functions. Those functions automatically substitute any NULL names with the argument's data type enclosed in angled brackets, as in "<int>" or "<string>".

The data type:
The third field is an enumerated type that defines the data type of the command line argument. Possible values are arg_int, arg_dbl, arg_str, arg_bool, and arg_lit. They represent integer, double, string, boolean, and literal arguments respectively.

The data pointer:
The fourth field is a pointer-to-void that gives the address of the user-defined program variable that is to be used to store the argument's value. A NULL pointer here causes the value to be discarded once is has been scanned.
Take care that the data type of of the target memory location matches that specified in the previous column. Arguments of type arg_int, arg_bool, and arg_lit must each point to an integer variable. Those of type arg_dbl must point to a double and those of arg_str must point to a char array.

The default value:
The fifth field is a string which contains an optional default value for the argument. It is defined as a string and automatically cast to the appropriate data type at run time. A NULL value indicates no default.

The description string:
The sixth and final field allows the programmer to enter a brief description of the argument. It is these descriptions that are output by the arg_glossary() function. A NULL value causes that entry to be omitted from the glossary output.

The argtable library functions

An example program

Usage: example [-tit<title>] grad:gradient [y-int]
   -tit<title>      title
   grad:gradient    line gradient 
   y-int            y-intercept

#include "argtable.h" 

int main(int argc, char **argv)
   {
   static char str[50]; 
   static double grad;
   static int c; 
   arg_rec argtable[] = 
      {
      {"-tit ","<title>", arg_str, str, "noname", "\t\t title"}, 
      {"grad:","gradient",arg_dbl, &grad, NULL, "\t line gradient"}, 
      {NULL, "y-int", arg_int, &c, "0", "\t\t y-intercept"} 
      }; 
   const size_t narg = sizeof(argtable)/sizeof(arg_rec); 

   /*-- process the command line args --*/ 
   if (argc==1) 
      { 
      /*-- display program usage and exit. --*/ 
      printf("Usage: %s %s\n", argv[0], arg_syntax(argtable,narg)); 
      printf("%s\n",arg_glossary(argtable,narg," ")); 
      return 0; 
      } 
   else 
      { 
      /*-- scan command line arguments from argv[] --*/
      char cmdline[200], errmsg[200], errmark[200]; 
      if (!arg_scanargv(argc,argv,argtable,narg,
                        cmdline,errmsg,errmark)) 
         { 
         /*-- arg error occurred, print error message and exit --*/ 
         printf("ERROR: %s\n", cmdline); 
         printf(" %s %s\n", errmark, errmsg); 
         return 1; 
         } 
      } 

   /*-- get here only if command line args ok --*/ 
   printf("title: \"%s\"\n",str); 
   printf("gradient: %f\n",grad); 
   printf("y-intercept: %d\n",c); 
   
   return 0; 
   }

$ example 
Usage: example [-tit <title>] grad:gradient [y-int]
   -tit <title>      title 
   grad:gradient     line gradient 
   y-int             y-intercept

$ example grad:10 
title: "noname"
gradient: 10.000000 
y-intercept: 0

$ example 7 grad:1.234 
title: "noname"
gradient: 1.234000 
y-intercept: 7

$ example -tit "hello world" grad:3.33 11 
title: "hello world"
gradient: 3.330000 
y-intercept: 11

$ example grad:oops 
ERROR: example grad:oops
                    ^ invalid grad:gradient argument

$ example grad:13 nope 
ERROR: example grad:13 nope
                       ^^^^ unexpected argument

$ example grad:13 99 uh oh 
ERROR: example grad:13 99 uh oh 
                          ^^ unexpected argument

History & Release Notes

Argtable-1.0 released November 13, 1998.

Argtable-1.1 released January 20, 1999.
This version fixes some cross-platform compilation errors, and saw the introduction of the multi-platform configuration. It also saw the addition of the arg_record() function and a change to the arg_scanargv() function so that it no longer requires argv[0] to be the first entry of the argument table. To maintain backwards compatibility, programs written for version 1.0 should now define the macro
#define ARGTABLE_COMPATIBILITY_10
prior to including the argtable.h header file.

From the author