HP-UX

NAME

iscanf − reads data from a device and converts it

SYNOPSIS

 #include <sicl.h>
 
 int iscanf (INST id, char *fmt, ...);
 int isscanf (char *buf, char *fmt, ...);
 int ivscanf (id, char *fmt,...);
 int isvscanf (char *buf, char *fmt, ...);
 

DESCRIPTION

These functions are used to read formatted data and convert it and place the results into the user’s “args”.  This function reads bytes from the specified device, or from “buf”, and converts them using conversion rules contained in the format string.  The number of “args” converted is returned. 
 
The format string contains:
 
* White-space characters, which are spaces, tabs, or special
  characters.  The special characters consist of a backslash
  (“&´’) followed by another character.  The list of
  white-space characters follows:
 

  \t    the ASCII “TAB” character
  \v    the ASCII “VERTICAL TAB” character
  \f    the ASCII “FORM FEED” character
  space the ASCII “space” character

 * An ordinary character (not “%”) which must match the next
  non-white-space character read from the device.
 * Conversion specifications, consisting of a “%” character followed by
  an optional assignment suppression character “*”, optional field
  width, optional comma operator, optional argument modifier, and a
  conversion character, in that order.
 NOTES:
 1.  Unlike C’s “scanf” function, SICL’s “iscanf” functions do
not treat the newline (\n) and carriage return (\r) characters
as white-space.  Therefore, they are treated as ordinary characters and
must match input characters.
 2.  The comma operator reads a list of comma separated numbers.  The
comma operator is in the form of “,dd”, where “dd” is the number
of array elements to read.  A pound sign (#) can be substituted for the
number, in which case the next argument is a pointer to an integer which
is the number of elements in the array.  The function will set this to
the number of elements read.  This operator is only valid with the
conversion characters “d” and “f”.  The users argument must be an
array of the type specified.
 The conversion specification directs the assignment of the next user
“arg”.  The “iscanf” function places the converted input in the
corresponding users variable, unless the “*” assignment suppression
character causes it to use no “arg” and ignore the input.
 This function ignores all white-space characters in the input stream.
  ISCANF Format String (Conversion Specifications)
 Conversion characters are:
 

d,i
corresponding “arg” must be a pointer to an integer.
The library reads characters until an entire number is read.  It
will accept any valid IEEE 488.2 NRf format number.  If the
“l” (ell) argument modifier is used, the argument must
be a pointer to a long integer.  If the “h” argument modifier
is used, the argument must be a pointer to a short
integer.
 

e,f,g
corresponding “arg” must be a pointer to a float.
The library reads characters until an entire number is read.  It
will accept any valid IEEE 488.2 NRf format number.  If the
“l” (ell) argument modifier is used, the argument must
be a pointer to a double.  If the “L” argument modifier is
used, the argument must be a pointer to a long double.
 

c
corresponding “arg” is a pointer to a character sequence.
Reads the number of characters specified by field width (default
1) from the device into the buffer pointed to by “arg”.  White
space is not ignored with “%c”.  No null character is added
to the end of the string.
 

s
corresponding “arg” is a pointer to a string.  All leading
white-space characters are ignored, then all characters from the
device are read into a string until a white-space character is
read.  An optional “field width” indicates the maximum length
of the string.  Note that the user should specify the
maximum field width of the buffer being used to prevent
overflows.
 

S
corresponding “arg” is a pointer to a string.  This data is
received as an IEEE 488.2 string response data block.  An
optional “field width” indicates the maximum length of the
string.  Note that the user should specify the maximum
field width of the buffer being used to prevent overflows.
 

t
corresponding “arg” is a pointer to a string.  Read all
characters from the device into a string until an “END”
indicator is read.  An optional “field width” indicates the
maximum length of the string.  All characters read beyond the
maximum length are ignored until the “END” indicator is
received.  Note that the user should specify the maximum
field width of the buffer being used to prevent overflows.
 

b
corresponding “arg” is a pointer to a buffer.  This conversion
code reads an array of data from the device.  The data must be
in IEEE 488.2 Arbitrary Block Program Data format.  Note that,
depending on the structure of the data, data may be read until
an END indicator is read.
 The “field width” must be present to specify the
maximum number of elements the buffer can hold.  The “field
width” can be a pound sign (#).  If the “field width” is a
pound sign, then two arguments are used to fulfill this
conversion type.  The first argument is a point to a long
integer that will be used as the “field width”.  The second
will be the pointer to the buffer that will hold the data.
After this conversion is satisfied, the “field width” pointer
is assigned the number of elements read into the buffer.
Otherwise, there is no way to know the actual number of elements
read into the buffer.
 If there is more data than what will fit into the buffer, the
extra data is lost.
 If no argument modifier is specified, the array is assumed to be
an array of bytes.
 If the ’w’ argument modifier is specified, then the array is
assumed to be an array of short integers (16 bits).  The data
read from the device is byte swapped and padded as necessary to
convert from IEEE 488.2 byte ordering to the internal ordering.
The “field width” is the number of words.
 If the ’l’ (ell) argument modifier is specified, then the array
is assumed to be an array of long integers (32 bits).  The data
read from the device is byte swapped and padded as necessary to
convert from IEEE 488.2 byte ordering to the ordering of this
system.  The “field width” is the number of long words.
 If the ’z’ argument modifier is specified, then the array is
assumed to be an array of floats.  The data read from the device
is an array of 32 bit IEEE-754 floating point numbers.  The
“field width” is the number of floats.
 If the ’Z’ argument modifier is specified, then the array is
assumed to be an array of doubles.  The data read from the
device is an array of 64 bit IEEE-754 floating point numbers.
The “field width” is the number of doubles.
 

o
corresponding “arg” must be a pointer to an unsigned
integer.  The library reads characters until an entire number is
read.  It will accept a valid IEEE 488.2 OCT format number, as
well as just an octal number.  If the “l” (ell) argument
modifier is used, the argument must be a pointer to an
unsigned long integer.  If the “h” argument modifier is used,
the argument must be a pointer to an unsigned short
integer.
 

u
corresponding “arg” must be a pointer to an unsigned
integer.  The library reads characters until an entire number is
read.  It will accept any valid decimal number.  If the “l”
(ell) argument modifier is used, the argument must be a
pointer to an unsigned long integer.  If the “h” argument
modifier is used, the argument must be a pointer to an
unsigned short integer.
 

x
corresponding “arg” must be a pointer to an unsigned
integer.  The library reads characters until an entire number is
read.  It will accept any valid hexadecimal number.  If the “l”
(ell) argument modifier is used, the argument must be a
pointer to an unsigned long integer.  If the “h” argument
modifier is used, the argument must be a pointer to an
unsigned short integer.
 

[
corresponding “arg” must be a character pointer.  The
“[” conversion type matches a nonempty sequence of characters
from a set of expected characters.  The characters between the
“[” and the “]” are the scanlist.  The scanset is the set of
characters that match the scanlist, unless the circumflex (^) is
specified.  If the circumflex is specified, then the scanset is
the set of characters that do not match the scanlist.  The
circumflex must be the first character after the “[”,
otherwise it will be added to the scanlist.
 The “-” can be used to build a scanlist.  It means to include
all characters between the two character in which it appears
(e.g.  %[a-z] means to match all the lower case letters between
and including ’a’ and ’z’).  If the “-” appears at the
beginning or the end of conversion string “-” is added
to the scanlist.
 

n
corresponding “arg” is a pointer to an integer.  The number of
bytes read from the device for this iscanf call is written to
the “arg”.  No argument is converted.
 

F
corresponding “arg” is a pointer to a FILE descriptor.  The
input data read from the device is written to the file referred
to by the FILE descriptor until the END indicator is received.
The file must be opened for writing.
No other modifiers or flags are valid with this conversion
character.
 

RETURN VALUE

iscanf returns the number of args formatted. 

ERRORS

Iscanf fails under the following circumstances, and sets the error condition to one of the following:
 

­[I_ERR_BADID] The INST id is invalid

­[I_ERR_BADFMT] Bad format string

­[I_ERR_OVERFLOW] Numeric overflow during conversion

SEE ALSO

iprintf(3), ifread(3), ifwrite(3), iflush(3), isetbuf(3), isetubuf(3)
 

AUTHOR

iscanf was developed by HP. 

Hewlett-Packard Company  —  May 05, 1994