GETARGS(3)

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

SYNOPSIS
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) */

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.

If a match is not found, getargs() returns the error code -1, 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, again with av[0] pointing to the non-flag 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.

Descriptors are composed of standard characters, which must match, followed by a conversion character.

Legal conversions and their meanings are:

#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 NOMATCH 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 NOMATCH situation.

#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 NOMATCH situation.

?   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. If there are no more data in the argument the next argument is used, and if there is no next argument, a NOMATCH situation exists.

&   Function

    The address argument is a pointer to a function to call with a pointer to the current argument. The function must return one of these values: YES = +1, NOMATCH = -1, ERROR = -2.

    Because the argument just after the 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.

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

If no conversion is specified, the flag is assumed to be a Boolean indicator and the corresponding value is set to TRUE (+1).

Descriptors are separated by a ',' (without whitespace) in the format string. They correspond in order to the 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 error will result if this is attempted.

Although Boolean flags must appear exactly as they do in the format string, the format string does not contain the leading '-'.

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.

RETURNS

+1  if an argument does not appear to be a flag.

0   when all the arguments have been examined.

-1  signifying a bad flag argument.

-2  signifying a bad descriptor.

EXAMPLES

SEE ALSO

getallargs(3), getfiles(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
Seestr. 110
D-13353 Berlin
Germany

Mail bugs and suggestions to:

schilling@fokus.gmd.de or js@cs.tu-berlin.de or joerg@schily.isdn.cs.tu-berlin.de