arg_scanargv(3)

NAME
arg_scanargv - Scan the command line as per the given argument table.

SYNOPSIS
#include <argtable.h>

int (arg_scanargv)(int argc, char **argv, arg_rec *argtable, int n, char *CmdLine, char *ErrMsg, char *ErrMark);

PARAMETERS

int argc
    number of entries in 'argv'.

char **argv
    ptr to command line arguments.

arg_rec *argtable
    ptr to argument table.

int n
    number of entries in argtable[].

char *CmdLine
    ptr to storage for command line (may be NULL).

char *ErrMsg
    ptr to storage for error message (may be NULL).

char *ErrMark
    ptr to storage for error marker (may be NULL).

DESCRIPTION
Attempts to resolve the command line arguments given in argv[] with the specifications given in the argument table. The values scanned from the command line are written directly into the chosen memory locations as specified by each argument table entry. Notice that the program name, in argv[0], is not treated as an argument and does not require an entry in the argument table. During the process, a copy of the command line is written (as a single line of space separated arguments) into the user-supplied string at *CmdLine in case it is needed in future for error reporting. Should there be any conflict between the command line arguments and the argument table specifications, an error message and corresponding error marker are written into the user-supplied strings at *ErrMsg and *ErrMark respectively, after which the function returns zero. The error marker string is used to store a string of tilde characters formated in such a way that the tildes underscore the exact location of the error in *CmdLine when the strings are aligned one above the other. This can be useful for including in on-line error messages to help the user quickly pinpoint the cause of the error. If, on the other hand, all arguments were resolved successfully then *ErrMsg and *ErrMark are set to empty strings and the function returns 1. Either way, CmdLine, ErrMsg, or ErrMark can be safely ignored by passing them as NULL.

RETURN VALUE
Returns 1 upon success, 0 upon failure.

THE ARGUMENT TABLE
The argument table is an array of arg_rec structs, and has one entry for each command line argument that is expected. It is most conveniently defined and initialised as a static array within the main block, but need not be so. We know that the first argument in argv[0] is always going to be the name of the executable so arg_scanargv() skips it during the scanning phase, starting instead with argv[1]. Thus the first entry of an argument table refers to argv[1] and not argv[0] (This was not the case in argtable version 1.0).

ANATOMY OF AN ARGUMENT TABLE ENTRY
The arg_rec structure has six members; a tag string, an argument name, an argument type, a pointer to a user-supplied data location, a default value (as a string), and a description string. A typical table entry might look like, { "--bs", "<size>", arg_int, &blcksize, "1024", "\ttape block size" } Here, we have a tagged integer argument whose value is to be stored in the program variable called "blcksize". It would be used on the command line as --bs 2048 for example. In our case, the argument has a default value of 1024 that is converted from a string to an integer and written into blcksize whenever a corresponding argument cannot be found on the command line. If the default value was instead given as NULL then the argument would be regarded as mandatory. Because our argument has a tag it may, unlike untagged arguments, be used anywhere on the command line. Furthermore, there need not be any space between the tag and the subsequent argument value, so --bs 2048 and --bs2048 would both be accepted. You can force the presence of whitespace between the tag and the value by putting a trailing space in the tag string, as in "--bs ". The choice is yours. The argument name "<size>" has no effect on the argument processing. It is just a descriptive name used to represent the argument in the output of the arg_syntax() and arg_glossary() functions, which in our case would appear as "--bs<size>". The argument name can be whatever you want, and is a convenient place to communicate the default value to the user if you so wish, for example "<size>=1024". If instead you specify a NULL name string, it is automatically replaced by the arguments data type enclosed in angled brackets, as in "<integer>". If you dislike such behaviour, you can effectively suppress the name by defining it as an empty string. Like the name string, the description string "\ttape block size" does not affect the processing. It is only used by the arg_glossary function, which in our case would produce a glossary entry of "--bs<size> tape block size". Arguments with NULL description strings are omitted from the glossary altogether. See arg_syntax() and arg_glossary() for more details on the name and description fields. An argument may also be untagged, as in the following string argument, { NULL, "<infile>", arg_str, infilename, NULL, " input file" } This argument has no tag and no default value and stores its result in the user-defined string called "infilename". Untagged arguments are expected to appear on the command line in the same order as they are defined in the argument table. When tagged and untagged arguments are mixed, the argument table is processed in two passes. The first pass extracts all the tagged arguments from the command line, the second pass extracts the remaining untagged arguments from left to right. As a final note, argtable entries may be given a NULL in place of the pointer-to-void entry that specifies the location of the user-defined program variable. Such arguments are still scanned from the command line in the normal way, but the resulting value is discarded.

ARGUMENT DATA TYPES
It is imperative that the data type of program variable used to store the argument's value matches the enum arg_type given in the third column of the argument table. If you get this wrong you can you can expect very spurious behaviour from the argtable functions. The enum arg_type is defined as typedef enum {arg_int, arg_dbl, arg_str, arg_bool, arg_lit} arg_type; Its values correspond to integer, double, string and boolean data types followed by a special string literal type. The boolean type stores its value as an integer that is either 0 or 1. The arg_lit type is a special case which is discussed in detail later, for now it is suffice to say that it too stores an integer value. The arg_bool type does not read an integer value from the command line, rather it expects one of the keywords "true", "false", "yes", "no", "on", or "off" which it then converts to 0 (false,no,off) or 1 (true,yes,on). For example, the argument { "debug:", NULL, arg_bool, &dbg, "false", "\tdebugging option" } defines an optional tagged boolean argument whose default value is 0 (false). It may appear on the command line as any of debug:true, debug:yes, debug:on, debug:false, debug:off, or debug:no. The value 0 or 1 is written into the integer program variable "dbg". The arg_lit type represents a special argument type. Unlike the other arguments, it does not scan a parameterised value from the command line. Instead, it just expects a given string literal to be present on the command line, as in --verbose or --help. The string literal can be defined in either the tag or the name string fields. If you use the tag then the string literal, like other tagged arguments, may appear anywhere on the command line. On the other hand, if you use the name string, then the string literal must appear in that argument's position just as for normal untagged arguments. When a string literal is succesfully scanned, an integer value of 1 is written into its user-suplied program variable, otherwise it is assigned the default value (if it has one). If there is no default value, then the literal is regarded as a mandatory argument the same as for any other argument. The following arg_lit argument shows how to implement a --verbose command line switch, { "--verbose ", NULL, arg_lit, &verbosity, "0", "\tverbosity switch" } Should --verbose be given on the command line, the value 1 is written into the integer program variable named "verbosity", otherwise the default value of 0 is used instead. Another use of the arg_lit type is to enforce the presence of a given keyword on the command line. This is useful to help distinguish individual command line usages when multiple candidate argument tables can be be applied. For example, the argtable entry { NULL, "geometric", arg_lit, NULL, NULL, NULL } has no tag, no default, no storage location, and no description. It simply defines the string literal "geometric" which must be present at a specific location on the command line for the argument table to be succesfully resolved. A sister argument table might have the entry { NULL, "linear", arg_lit, NULL, NULL, NULL } in the same argument position. Thus, the keywords "geometric" and "linear" are used to distinguish the two possible usages.

SEE ALSO
arg_catargs(3), arg_dump(3), arg_glossary(3), arg_record(3), arg_scanstr(3), arg_syntax(3), arg_typestr(3)