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
/amnt/loge/users/nistaff02/nistaff/rhaschke/nst7/man/../o.linux//../nstsrc/nst0.c