vPrintf(3)

HP-UX

NAME

viPrintf − Converts, formats and sends data to the specified device

SYNOPSIS

viPrintf(ViSession vi, ViString writeFmt, arg1, arg2,...);

Description

This function converts, formats, and sends the parameters arg1, arg2, ... to the device as specified by the format string. Before sending the data, the function formats the arg characters in the parameter list as specified in the writeFmt string. You should not use the viWrite and viPrintf functions in the same session.

The writeFmt string can include regular character sequences, special formatting characters, and special format specifiers. The regular characters (including white spaces) are written to the device unchanged. The special characters consist of (backslash) followed by a character. The format specifier sequence consists of % (percent) followed by an optional modifier (flag), followed by a conversion character.

Parameters

vi An input parameter. Unique logical identifier to a session.

writeFmt An input parameter. String describing the format for arguments.

arg1, arg2 Input parameters. Parameters format string is applied to.

Special Formatting Characters

The special formatting characters and what they send to the device are:

\n   − Sends the ASCII LF character. The END
         identifier will also be automatically sent.
\r   − Sends an ASCII CR character.
\t   − Sends an ASCII TAB character.
\### − Sends the ASCII character specified by the octal value.
\"   − Sends the ASCII double-quote (") character.
\\ − Sends a backslash () character.

Format Specifiers

The format specifiers convert the next parameter in the sequence according to the modifier and conversion character, after which the formatted data is written to the specified device. The format specifier has the following syntax:

%[modifiers]conversion character

where conversion character specifies which data type the argument is represented in. The modifiers are optional codes that describe the target data.

In the following tables, a d conversion character refers to all conversion codes of type integer (d, i, o, u, x, X), unless specified as %d only. Similarly, an f conversion character refers to all conversion codes of type float (f, e, E, g, G), unless specified as %f only.

Every conversion command starts with the % character and ends with a conversion character. Between the % character and the conversion character, the modifiers in the following tables can appear in the sequence.

ANSI C Standard Modifiers:

An integer specifying field width. d, f, s conversion characters This specifies the minimum field width of the converted argument. If an argument is shorter than the field width, it will be padded on the left (or on the right if the - flag is present).

An asterisk (*) may be present in lieu of a field width modifier, in which case an extra arg is used. This arg must be an integer representing the field width.

An integer specifying precision. d, f, s conversion characters The precision string consists of a string of decimal digits. A . (decimal point) must prefix the precision string. The precision string specifies the following:

1. The minimum number of digits to appear for the i, o, u, x, and X conversion characters.

2. The maximum number of digits after the decimal point in case of f conversion characters.

3. The maximum numbers of characters for the string (s) specifier.

4. Maximum significant digits for g conversion character. An asterisk (*) may be present in lieu of a precision modifier, in which case an extra arg is used. This arg must be an integer representing the precision of a numeric field.

An argument length modifier. h, l, and L are legal values. h (d conversion character) l (d, f conversion character) L (f conversion character) The argument length modifiers specify one of the following:

1. The h modifier indicates the argument is a short or unsigned short, depending on the conversion character type.

2. The l modifier indicates the argument is a long or unsigned long.

3. The L modifier indicates the argument is a long double parameter.

Enhanced Modifiers to ANSI C Standard:

A comma (,) followed by an integer n, where n represents the array size. %d and %f only The corresponding argument is interpreted as a reference to the first element of an array of size n. The first n elements of this list are printed in the format specified by the conversion character.

An asterisk (*) may be present after the , modifier, in which case an extra arg is used. This arg must be an integer representing the array size of the given type.

The following are the allowed conversion characters. A format specifier sequence should include one and only one conversion character.

Standard ANSI C Conversion Characters

% - Send the ASCII percent (%) character.
c - Argument type: A character to be sent.
d - Argument type: An integer.

Default functionality
Print an integer in NR1 format (an integer without a decimal point).

field width
Minimum field width of the output number.

Length modifier l
arg is a long integer.

Length modifier h
arg is a short integer.

, array size
arg points to an array of integers (or long or short integers, depending on the length modifier) of size array size. The elements of this array are separated by array size - 1 commas and output in the specified format.

f Argument type: A floating point number.

Default functionality Print a floating point number in NR2 format (a number with at least one digit after the decimal point).

field width Minimum field width of the output number.

Length modifier l arg is a double float.

Length modifier L arg is a long double.

, array size arg points to an array of floats (or doubles or long doubles), depending on the length modifier) of size array size. The elements of this array are separated by array size - 1 commas and output in the specified format.

s Argument type: A reference to a NULL-terminated string

Return Values

This is the functional return status. It returns either a completion code or an error code as follows.

VI_SUCCESS Parameters were successfully formatted.

VI_ERROR_INV_SESSION VI_ERROR_INV_OBJECT The given session or object reference is invalid (both are the same value).

VI_ERROR_IO Could not perform write function because of I/O error.

VI_ERROR_TMO Timeout expired before write function completed.

VI_ERROR_INV_FMT A format specifier in the writeFmt string is invalid.

VI_ERROR_NSUP_FMT A format specifier in the writeFmt string is not supported.

VI_ERROR_ALLOC The system could not allocate a formatted I/O buffer because of insufficient resources.

AUTHOR

viPrintf was developed by HP

Hewlett-Packard Comapny — September 29, 1999

Museum