GETARGS(3)

NAME
getargs() - parses arguments until a non-flag is reached

SYNOPSIS
#include <schily/getargs.h>
int getargs(pac, pav, fmt, a1, ..., an)
	int *pac;       /* pointer to arg count */
	char *(*pav)[]; /* pointer to address of arg vector */
	char *fmt;      /* format string */
	type *a1;       /* pointer to result 1 (corresponding */
	                /* to the first descriptor in fmt) */
	type *an;       /* pointer to result n (corresponding */
	                /* to the nth descriptor in fmt) */
int getlargs(pac, pav, props, fmt, a1, ..., an)
	int *pac;       /* pointer to arg count */
	char *(*pav)[]; /* pointer to address of arg vector */
	struct ga_props *props; /* control properties */
	char *fmt;      /* format string */
	type *a1;       /* pointer to result 1 (corresponding */
	                /* to the first descriptor in fmt) */
	type *an;       /* pointer to result n (corresponding */
	                /* to the nth descriptor in fmt) */

DESCRIPTION
getargs() looks at each argument that begins with '-', '+', or has an '=' in it and trys to find a matching description in fmt. If a match is found, the corresponding value pointed at by a1 to an is set to the value according to the conversion specification.

getlargs() is similar to getargs() but it implements an additional ga_props parameter that must be initialized with getarginit() before it is passed.

Each normal format takes one address argument from a1 to an and each function type format takes two address arguments from a1 to an.

If a match is not found, getargs() returns the error code -1 (BADFLAG), with *pav[0] pointing to the bad argument. If an argument that does not begin with '-' or '+' or contain an '=' is found, getargs() returns +1 (NOTAFLAG), again with pav[0] pointing to the non-flag argument. If the argument "-- " is found, getargs() returns +2 (FLAGDELIM) and pav[0] points to the argument after the argument "-- ".

In the description, it is assumed that pac=&ac and pav=&av, where ac and av are the two arguments passed to main(). The pointers are necessary so that getargs() can update ac and av as it verifies each argument and reflects the current position back to the user.

The format string is a series of one or more option descriptors. Each option descriptor starts with the option-name which is composed of characters, numbers, the underscore character `-', minus or plus, which must match the option parameter on the command line. It is followed by the optional format descriptor and an optional size modifier.

Legal conversions and their meanings are:

#c or #C
    Char integer

    The remainder of the current argument, or if it is empty, the next existing argument is converted to a character sized integer value. An error in conversion results in a BADFLAG situation.

#s or #S
    Short integer

    The remainder of the current argument, or if it is empty, the next existing argument is converted to a short integer value. An error in conversion results in a BADFLAG situation.

# or #i or #I
    Integer

    The remainder of the current argument, or, if it is empty, the next existing argument is converted to an int value. An error in conversion results in a BADFLAG situation.

#l or #L
    Long integer

    The remainder of the current argument, or if it is empty, the next existing argument is converted to a long integer value. An error in conversion results in a BADFLAG situation.

#ll or #LL
    Long long integer

    The remainder of the current argument, or if it is empty, the next existing argument is converted to a long long integer value. An error in conversion results in a BADFLAG situation.

+   Increment sized integer

    The value of the related argument pointer is incremented, assuming a size that depends on the optional size modifier after the +. See the integer conversions above for a list of valid size modifiers.

empty
    BOOLean TRUE

    If the option-name is not followed by a format descriptor, the value of the related argument pointer is interpreted as an integer and set to TRUE (+1).

%0 or %1
    Set sized BOOL

    The value of the related argument pointer is either set to 0 (when using the format %0), or set to 1 (when using the format %1), assuming a size that depends on the optional size modifier after the %0 or %1. See the integer conversions above for a list of valid size modifiers.

?   Character

    The next character in the current argument is the result. If there is no next char, the result is '\0'.

*   String

    A pointer to the remainder of the current argument is returned in the related argument pinter. If there are no more data in the argument the next argument is used, and if there is no next argument, a BADFLAG situation is returned.

&   Function

    This format takes two parameters in the argument list of getargs(). The first argument is a pointer to a function to call. The second argument is a pointer to a variable that is passed to the function as second argument.

    Because the argument just after the function address argument is passed as a second argument to the function, common routines can have their results in different places depending on which switch is invoked.

    The function is called with five arguments:

    1)  A pointer to the option argument, taken from the matching element from the command line from *pav.

    2)  A pointer to the variable that should be set by the function.

    3)  The current value of pac.

    4)  The current value of pav.

    5)  A pointer to the matching part of the format string.

    The function must return one of these values:

    FLAGDELIM = +2
        Pretend that "-- " stopped flag processing.

    FLAGPARSED = +1
        Option processing was successful.

    NOARGS = 0
        Pretend that all arguments have been examined.

    BADFLAG = -1
        The current flag argument or parameter is not understood.

    BADFMT = -2
        An unspecified error occurred.

    NOTAFILE = -3
        Probably another flag type argument. Tell the calling function (getargs()) to continue to check for other flag type arguments in the format string for a possible match.

    Note: If a flag is found multiple times, the function is called each time.

~   Function for BOOLean flag

    This is a variant of the &-format, but as a boolean flag is assumed, no option argument is assumed and if the related option is a single char option, it may be combined with other single char options. The called function permits to reset other options at the same time.

    As boolean flags take no arguments, the first argument of the called function points to an empty string.

Descriptors are separated by a ',' (without whitespace) in the format string. They correspond in order to the resultant pointers, a1...an. Note that function type formats take two arguments from resultant pointers, a1...an.

It is an error to expect more than one conversion from a single match (e.g., "x#*" to attempt to get both the numerical value and the actual string for the x flag); a -2 (BADFMT) error will result if this is attempted.

Although flags must appear exactly as they do in the format string, the format string does not contain the leading '-'. If the flag should start with a '+', the '+' needs to be in the format string. If the flag should start with a '--', a single '-' needs to be in the format string.

Flags, where conversion is to take place, may appear either as:

-fvalue
f=value
f= value
-f=value
-f= value

where f is the matching flag string. No additional effort is required to get these different ways of specifying values.

Long flags, where conversion is to take place, may appear either as:

-flagvalue
--flagvalue
flag=value
flag= value
-flag=value
--flag=value
-flag= value
--flag= value

where flag is the matching flag string. No additional effort is required to get these different ways of specifying values.

For flags or type: *, ?, & and #, when the format character is immediately followed by a space or underscore character, the permitted option calling variants are limited:

-   The underscore character enforces that option-name and option-argument need to be written as a single argument. This permits to implement options with optional arguments.

-   The space character enforces that option-name and option-argument need to be written as separate arguments.

RETURNS

FLAGDELIM 2
    The command line argument "-- " stopped flag processing.

NOTAFLAG  1
    The argument *pav does not appear to be a flag.

NOARGS    0
    All arguments have been successfully examined.

BADFLAG  -1
    A bad flag (option) argument was supplied to the program. The argument *pav contains the offending command line argument.

BADFMT  -2
    A bad format descriptor string has been detected. The calling program, rather than the user, was in error.

General rules for the return code:

> 0 A file type argument was found.

0   All arguments have been parsed.

< 0 An error occurred or not a file type argument.

Flag and file arg processing should be terminated after getting a return code <= 0.

EXAMPLES

SEE ALSO

getarginit(3), getallargs(3), getargerror(3), getfiles(3), getlallargs(3), getlargs(3), getlfiles(3), getvallargs(3), getvargs(3), getvfiles(3).

NOTES
getargs() assumes the first argument is at av[0]. Commands are invoked by the system with the command name in av[0] and the first argument in av[1], so they must increment av and decrement ac before calling getargs().

getargs() should only be used when the position of the switches influences how an argument is processed (e.g., format and pr commands), or when all switches must be before all the arguments (e.g, write command). In other cases, use getallargs().

BUGS
none

AUTHOR
Joerg Schilling
D-13353 Berlin
Germany