PARSEARGS

Section: C Library Functions (3)
Index Return to Main Contents

NAME

parseargs, usage - parse command line argument vectors

SYNOPSIS

void parseargs(argv, argd)
char *argvp[];
ARGDESC argd[];

void usage(argd)

DESCRIPTION

Given a vector of string-valued arguments such as that passed to main and a vector describing the possible arguments, parseargs matches actual arguments to possible arguments, converts values to the desired type, and diagnoses problems such as missing arguments, extra arguments, and argument values that are syntactically incorrect.

When invoked interactively, under the UNIX operating system and if parseargs has been compiled for interactive operation, parseargs prompts the user for argument values that are required but are not given on the command line, and values that are supplied but syntactically incorrect.

By default this option is not compiled in to avoid problems in shell scripts, where a program unexpectedly going into interactive mode might tun out to be a little disconcerting.

Given a description of possible arguments, usage prints a reasonably friendly version of this description.

The argument description vector contains one entry for each possible flag. Each entry has five fields:

name: The single character name of the associated flag. For example, to indicate that the program is expecting a ``-x'' flag, this field would contain 'x'. Positional arguments (those without a ``-x'' prefix) are indicated by passing a ``space'' character.
flags: Flags modifying the semantics of this entry, These should have one of ARGREQ to indicate a required argument or ARGOPT to indicate an optional argument. ARGHIDDEN can be ``ored'' in to indicate a flag that should not be printed in usage messages --- for example, flags intended for internal debugging purposes.
type: The type of the argument. This is actually a pointer to a function, as described below. Standard types include argBool (Boolean flags), argStr (string-valued arguments), argList (a LIFO list of string-valued arguments), argChar (char-valued arguments), argInt (native integer arguments), argShort (short integer arguments), argLong (long integer arguments), argFloat (short floating point arguments), and argDouble (long floating point arguments).
valp: A pointer to the variable that should receive the converted value. Since this is typed as ``pointer to anything'', this field should be preceded with a double underscore (``__'') (a macro defined in parseargs.h) to perform the appropriate type cast.
prompt: The string used when prompting interactively for argument values, and printed in usage messages.

The list of arguments is terminated using ENDOFARGS.

For example, consider the description:

int     RepCount =      2;
BOOL    Verbose =       FALSE;
char    *InFile;
char    *OutFile =      CHARNULL;
BOOL    XRated =        FALSE;
struct namelist *Files = NULL;

ARGDESC Args[] =
{
        'c',    ARGOPT,         argInt,         __ &RepCount,   "REPcount",
        'v',    ARGOPT,         argBool,        __ &Verbose,    "Verbose",
        ' ',    ARGREQ,         argStr,         __ &InFile,     "INPUTfile",
        ' ',    ARGOPT,         argStr,         __ &OutFile,    "OUTPUTfile",
        'X',    ARGHIDDEN,      argBool,        __ &XRated,     "XratedMODE",
        ' ',    ARGOPT,         argList,        __ &Files,      "File",
        ENDOFARGS
};

This describes a program accepting up to three flag arguments and one or two positional arguments, plus a list of additional file arguments. Only the first positional argument is required. The possible flags (in UNIX) are:

-c count: An integer repetition count. This defaults to two.
-v: A Boolean ``verbose'' flag. It defaults to FALSE.
-X: A Boolean ``X Rated'' flag. This is not printed in the usage message.

The two positional arguments are both strings, as is the final list. In AmigaDOS, the options would be REP count, V, and MODE.

ARGUMENT TYPE FUNCTIONS

The argument types recognized by parseargs can be extended by adding new type functions. Argument type functions are declared as:

BOOL argXxx(argd, argp, copyf)
        ARGDESC *argd;
        char *argp;
        BOOL copyf;

The argd argument points to the descriptor for the argument being converted. Its main use is to find the location in which to store the converted value, located in argd->ad_valp. The string value to be converted is passed in argp. The copyf flag is TRUE if the argp string value must be copied when saved. Most non-string types are copied implicitly (for example, integer arguments are stored in binary form, so the original string value need not be saved), so this argument can usually be ignored. Put simply, this flag is TRUE when argp points to a temporary buffer area.

The type function successfully converts the value, it should return TRUE. Otherwise, it should print a message using usrerr(3) and return FALSE. This message should be of the form "invalid xxxx option 'yyyy' for Zzzz", where xxxx is the type of the option, yyyy is the string passed in vp, and zzzz is the name (taken from ad->ad_prompt).

For example, a type function that took a filename and stored an open file pointer might be coded as:

/*ARGSUSED*/
BOOL
argReadFile(argd, argp, copyf)
        register ARGDESC *argd;
        register char *argp;
        BOOL copyf;
{
        register FILE *fp;

        fp = fopen(argp, "r");
        if (fp == NULL)
        {
                usrerr("cannot open '%s' for reading as %s",
                        argp, argd->ad_prompt);
                return (FALSE);
        }
        *(FILE *) argd->ad_valp = fp;
        return (TRUE);
}

AUTHOR

Eric Allman, University of California, Berkeley

MODIFICATIONS

Modified to accept a vector of arguments, better error messages, and AmigaDOS version by Peter da Silva.

This document was created by man2html, using the manual pages.
Time: 21:53:14 GMT, February 02, 2023