NAME

ascanf -- scan argument list

PROTOTYPE

int ascanf( int argn, char *argv[], char *tFmt1, void *pResult)

ARGUMENTS

int argn
argument count parameter from command line
char *argv[]
argument list from command line
char *tFmt1
format string specifying for which argument parameter to search (see below)
void *pResult
value of argument parameter found

DESCRIPTION:

Scans command line parameters and assigns value to *pResult according to keyword and format specification in tFmt. Return value is the position index of the argv -parameter the value of which was converted and assigned to *pResult. A return value of FALSE (=0) indicates that no assignment was made. For the sake of this convention, the parameter argv[0] is not accessible with this routine. In addition, there is a special mode to support error checking (see section ERROR CHECKING). The tFmt-Format string is expected to be of the form '!'[TokenString][' ']'%''%d'|'%f'|'%s'|'%c' where TokenString is an arbitrary string token not starting with a '!' and not containing the letter '%' or white space. If in the second form any initial '!' is absent, ascanf will sequentially search through all argument parameters until a parameter matches TokenString. If TokenString is followed by a space, the match must be complete, otherwise the argument parameter may consist of an initial portion that matches TokenString, followed by additional, arbitrary characters. If k initial '!'s are present, the search criterion is negated and the k -th non-matching argument parameter is determined. If tFmt is without any '%' -char, the routine just checks for the presence of TokenString and returns its position>0 in the argument list, or a value of zero, if absent. If TokenString is followed by '%x', with the format letter x from the set 'cdfs', and if there is no intervening space between TokenString and '%x', then the returned value will be determined from the unmatched portion of the found argument. Otherwise, the returned value will be determined from the argument parameter that follows the matched argument. Each additional percent-sign in front of the format letter has the effect to skip one additional parameter position to the right. If no format letter is specified, the format letter 's' is assumed. If, according to these rules, an argument parameter could be found, it is converted according to the format letter and the value is assigned to *pResult. Return value in this case is the argv -index position of the converted parameter. If no parameter could be found, the return value is zero.

ERROR CHECKING:

A call of ascanf(argn,argv,NULL,NULL) will return the number of unused command line arguments among argv[1..argn] since the last such call. If in addition argv!=NULL, a warning and a listing of the unused parameters will be printed to stderr. Therefore, to check whether a sequence of ascanf - calls uses all of the first argn command line arguments, enclose the sequence by the pair ascanf(0,NULL,NULL,NULL) and ascanf(argn,argv,NULL,NULL). The first call will initialize the bookkeeping, the second will evaluate it.

FORMAT EXAMPLES:

"-f%"
searches for an argument of the form "-fxy..z" and returns "xy..z"
"-f%d"
as before, but "xy..z" is expected to be a decimal integer the value of which is assigned to *pResult.
"-f %"
searches for an argument of the form "-f" and returns the string value of the argument parameter that follows "-f".
"-f %d"
as before, but the argument parameter is expected to be a decimal integer the value of which is assigned to *pResult.
"!!!-%"
returns third argument parameter that does not start with a letter '-'.
"!-%%"
returns second argument parameter that follows the first argument parameter that does not start with a letter '-'.
%%%d"
returns atoi(argv[3]) if present.

FILE

/local/homes/rhaschke/nst7/man/../o.linx86//../nstsrc/nst0.c