IPRINTF(3)

HP-UX

NAME

iprintf − format and send data to a device

SYNOPSIS

#include <sicl.h>

int iprintf (INST id, char *fmt, ...);
int isprintf (char *buf, char *fmt, ...);
int ivprintf (INST id, char *fmt, ...);
int isvprintf (char *buf, char *fmt, ...);

DESCRIPTION

These routines convert data under the control of the format string. The format string specifies how the argument is converted before it is output. If the first argument is an INST, the data is sent to the device to which the INST references. If the first argument is a character buffer, the data is placed in the buffer.

The format string contains regular characters and special conversion sequences. The iprintf function sends the regular characters (not a % character) in the format string directly to the device. Conversion specifications are introduced by the % character. Conversion specifications control the type, the conversion, and the formatting of the arg parameters.

<need begin> <note> The formatted I/O routines, iprintf and ipromptf, can readdress the bus multiple times during execution. This behavior may cause problems with instruments which do not comply with IEEE 488.2.

Readdressing occurs under the following circumstances: <list tight> * After the internal buffer fills and flushes (see isetbuf) * When sending \n in the format string (see Conversion Character t) <

If you cannot avoid the above situations, format the data using other means (e.g., isprintf) and communicate using the lower-level SICL function iwrite.

This behavior affects only non-IEEE 488.2 devices on the GPIB interface. <0te> <need end>

IPRINTF Format String (Conversion Specifications)

Use the following special characters and conversion commands to create the format strings contents.

Special Characters

Special characters consist of a backslash (\) followed by another character. The list of special characters follows:

\n − Send an LF^END (see %t for sending LF without an ^END)
\r − Send an ASCII CR character
\\ − Send a backslash (\) character
\t − Send an ASCII TAB character
\nnn − Send the ASCII character specified by the octal value nnn
\" − Send an ASCII double-quote (") character

Format Conversion Commands
A format conversion command begins with a % character. After the
%, the following appear in order: flags, field width, a period with
precision, a comma operator, and an argument modifier. It ends with a
conversion character.
Conversion Commands are:

flags
Zero or more flags (in any order) that modify the
meaning of the conversion character. See list of
flags below.

field width
An optional minimum field width. If the
formatted data has fewer characters than
field width, it will be padded. The padded
character is dependent on various flags.

.
An optional period; needed only if the
precision value is provided.

precision
The optional precision for conversion
characters e, E, and f specifies the
number of digits to the right of the
decimal point. For the d, i, o, u, x,
X conversion characters, it specifies
the minimum number of digits to appear.
For the s, and S conversion characters,
the precision specifies the maximum
number of characters to be written
from the users arg string.

,dd
The optional comma operator for
conversion characters d, and f. This
is a comma followed by a number.
This indicates that a list of comma
separated numbers is to be generated.
The user argument is now an array of
the specified type instead of the type
(i.e. an array of int’s instead of an
int). An asterisk (*) may appear for
the number, in which case it will take
another arg to satisfy this
conversion command. The next arg
will be an int that is the number of
elements in the array.

arg modifier
The optional argument modifiers h,l,w,z,Z
the meaning is dependent on the
conversion character.

conv char
A character that specifies the type of
the user’s arg and the conversion to
be applied.

Flags are:

@1
convert to an NR1 number (an IEEE 488.2 format integer with no
decimal point). Valid only for %d and %f. Note that
%f values will be truncated to the integer value.

@2
convert to an NR2 number (an IEEE 488.2 format floating point
number with at least one digit to the right of the decimal
point). Valid only for %d and %f.

@3
convert to an NR3 number (an IEEE 488.2 format number expressed
in exponential notation). Valid only for %d and %f.

@H
convert to an IEEE 488.2 format hexadecimal number in the form
#Hxxxx. Valid only for %d and %f. Note that %f
values will be truncated to the integer value.

@Q
convert to an IEEE 488.2 format octal number in the form
#Qxxxx. Valid only for %d and %f. Note that %f
values will be truncated to the integer value.

@B
convert to an IEEE 488.2 format binary number in the form
#Bxxxx. Valid only for %d and %f. Note that %f
values will be truncated to the integer value.

-
left justify the result.

+
prefix result with a sign (+ or -) if the output is a
signed type.

space
prefix result with a blank ( ) if the output is
signed and positive. Ignored if both blank and +
specified.

#
use alternate form. For the o conversion, it prints a leading
zero. For x, or X, a nonzero will have 0x, or 0X as a prefix.
For e, E, f, g, and G, the result will always have one digit on
the right of the decimal point.

0
will cause the left pad character to be a zero (0) for all
numeric conversion types.

Conversion characters are:

d
corresponding arg is an integer. If no flags are given,
send the number in IEEE 488.2 NR1 (integer) format. If flags
indicate an NR2 (floating point) or NR3 (floating point) format,
convert the argument to a floating point number. This argument
supports all six flag modifier formatting options: NR1 -
@1, NR2 - @’, NR3 - @3, @H, @Q, or @B.
If the l (ell) argument modifier is present, the arg must be a
long integer. If the h argument modifier is present, the
arg must be a short integer.

f
corresponding arg is a double. If no flags are given, send
the number in IEEE 488.2 NR2 (floating point) format. If flags
indicate that NR1 format is to be used, the arg will be
truncated to an integer. This argument supports all six
flag modifier formatting options: NR1 - @1, NR2 -
@2, NR3 - @3, @H, @Q, or @B. If the l (ell)
argument modifier is present, the arg must be a double. If
the L argument modifier is present, the arg must be a long
double.

b
corresponding arg is a pointer to an arbitrary block of
data. The data is sent as IEEE 488.2 Definite Length
Arbitrary Block Response Data. The field width must
be present and will specify the number of elements in the data
block. An asterisk (*) can be used in place of the integer,
it indicates that two args are used. The first is a long
used to specify the number of elements. The second is the
pointer to the data block. No byte swapping is performed.
If the w argument modifier is present, the block of data is an
array of unsigned short integers. The data block is sent to the
device as an array of words (16 bits). The field width value now
corresponds to the number of short integers, not bytes. Each
word will be appropriately byte swapped and padded so that they
are converted from the internal computer format to the standard
IEEE 488.2 format.
If the l (ell) argument modifier is present, the block of data is
an array of unsigned long integers. The data block is sent to
the device as an array of longwords (32 bits). The field width
value now corresponds to the number of long integers, not bytes.
Each word will be appropriately byte swapped and padded so that
they are converted from the internal computer format to the
standard IEEE 488.2 format.
If the z argument modifier is present, the block of data is an
array of floats. The data is sent to the device as an array of
32-bit IEEE 754 format floating point numbers. The field width
is the number of floats.
If the Z argument modifier is present, the block of data is an
array of doubles. The data is sent to the device as an array of
64-bit IEEE 754 format floating point numbers. The field width
is the number of doubles.

B
Same as b, except that the data block is sent as IEEE 488.2
Indefinite Length Arbitrary Block Response Data. Note that this
format involves sending a newline with an END indicator on the
last byte of the data block.

c
corresponding arg is a character.

C
corresponding arg is a character, send with END indicator.

t
Control sending the END indicator with each LF character in the
format string. A + flag indicates to send an END with each
succeeding LF character (default), a - flag indicates to not
send END. If no + or - flag appears, an error is generated.

s
corresponding arg is a pointer to a null terminated string
that is sent as a string.

S
corresponding arg is a pointer to a null terminated string
that is sent as an IEEE 488.2 string response data block. An
IEEE 488.2 string response data block consists of a leading
double quote (") followed by non-double quote characters and
terminated with a double quote.

%
send the ASCII percent (%) character.

i
corresponding arg is an integer. Same as d except that the
six flag modifier formatting options: NR1 - @1, NR2 - @2,
NR3 - @3, @H, @Q, or @B are ignored.

o,u,x,X
corresponding arg is an unsigned integer. The argument is
converted to an unsigned octal (o), or unsigned decimal (u), or
unsigned hexadecimal (x,X). The letters abcdef are used
with x, and the letters ABCDEF are used with X. The
precision specifies the minimum number of characters to appear.
If the value can be represented with fewer than precision digits,
leading zeros are added. If the precision is set to zero and the
value is zero, no characters are printed.

e,E
corresponding arg is a double. The argument is converted to
exponential format (i.e. [-]d.dddde+/-dd). The precision
specifies the number of digits to the right of the decimal point.
If no precision is specified then six digits will be converted.
The letter ’e’ will be used with e and the letter ’E’ will be
used with E.

g,G
corresponding arg is a double. The argument is converted to
exponential (’e’ with g, or ’E’ with G) or floating point format
depending on the value of the arg and the precision. The
exponential style will be used if the resulting exponent is less
than -4 or greater than the precision, otherwise it will be
printed as a float.

n
corresponding arg is a pointer to an integer. The number
of bytes written to the device for the entire iprintf call is
written to the arg. No argument is converted.

F
corresponding arg is a pointer to a FILE descriptor. The
data will be read from the file that the FILE descriptor points
to and written to the device. The FILE descriptor must be
opened for reading. No flags or modifiers are allowed with
this conversion character.

RETURN VALUE

Iprintf returns the number of args formatted.

ERRORS

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

[I_ERR_BADID] The INST id is invalid

[I_ERR_BADFMT] Bad format string

[I_ERR_OVERFLOW] Numeric overflow during conversion

AUTHOR

iprintf was developed by HP.

Hewlett-Packard Company — May 05, 1994

Museum