HP 3000 Manuals HP 3000 Manuals
vfprintf
Writes data in formatted form to an open stream using a variable argument
list.
Syntax
#include <stdarg.h>
#include <stdio.h>
int vfprintf (FILE *stream, const char *format,
va_list arg);
Parameters
stream A pointer to an open stream where data is to be written.
format A pointer to a character string defining the format (or the
character string itself enclosed in double quotes).
arg A variable argument list initialized by va_start (defined
in the header <stdarg.h>).
Return Values
>=0 The number of characters written.
<0 An error occurred.
Description
The vfprintf function enables you to output data in formatted form to an
open stream. In the vfprintf function, string points to an open stream,
and format points to a character string (or the character string itself
enclosed in double quotes) that specifies the format and content of the
data to be written. The arg parameter is a variable argument list
containing variables or expressions specifying the data to be written.
arg must be initialized by the va_start macro prior to a call to
vfprintf().
The arg parameter specifies conversion specifications and literal
characters. Literal characters are all characters that are not part of a
conversion specification. Literal characters are written to the open
stream exactly as they appear in the format.
Conversion Specifications
The following list shows the different components of a conversion
specification in their correct sequence:
1. A percent sign (%), which signals the beginning of a conversion
specification; to output a literal percent sign, you must type two
percent signs (%%).
2. Zero or more flags, which affect the way a value is written (see
below).
3. An optional decimal digit string which specifies a minimum field
width.
4. An optional precision consisting of a dot (.) followed by a
decimal digit string.
5. An optional l, h, or L indicating that the argument is of an
alternate type. When used in conjunction with an integer
conversion character, an l or h indicates a long or short integer
argument, respectively. When used in conjunction with a
floating-point conversion character, an L indicates a long double
argument.
6. A conversion character, which indicates the type of data to be
converted and printed.
A one-to-one correlation must exist between each specification
encountered and each item in the item list.
The available flags are:
- Causes the data to be left-justified within
its output field. Normally, the data is
right-justified.
+ Causes all signed data to begin with a sign (+ or
-). Normally, only negative values have signs.
blank Causes a blank to be inserted before a positive
signed value. This is used to line up positive and
negative values in columnar data. Otherwise, the
first digit of a positive value is lined up with
the negative sign of a negative value. If the
blank and + flags both appear, the blank flag is
ignored.
# Causes the data to be written in an alternate form.
Refer to the descriptions of the conversion
characters below for details concerning the effects
of this flag.
0 For d, i, o, u, x, X, e, E, f, g, and G
conversions, leading zeros (following any
indication of sign or base) are used to pad to the
field width. No space padding is performed. If
the 0 and - flags both appear, the 0 flag is
ignored. The 0 flag is also ignored for d, i, o,
u, x, and X conversions if a precision is
specified.
A field width, if specified, determines the minimum number of spaces
allocated to the output field for the particular piece of data being
printed. If the data happens to be smaller than the field width, the
data is blank- padded on the left (or on the right, if the - flag is
specified) to fill the field. If the data is larger than the field
width, the field width is simply expanded to accommodate the data. An
insufficient field width never causes data to be truncated. If field
width is not specified, the resulting field is made just large enough to
hold the data.
The precision is a value which means different things depending on the
conversion character specified. Refer to the descriptions of the
conversion characters below for more details.
NOTE A field width or precision may be replaced by an asterisk (*). If
so, the next item in the item list is fetched, and its value is
used as the field width or precision. The item fetched must be an
integer.
Conversion Characters
Conversion characters specify the type of data to expect in the item list
and cause the data to be formatted and printed appropriately. The
integer conversion characters are:
d, i An integer item is converted to signed decimal.
The precision, if given, specifies the minimum
number of digits to appear. If the value has fewer
digits than that specified by the precision, the
value is expanded with leading zeros. The default
precision is 1. A null string results if a zero
value is printed with a zero precision. The # flag
has no effect.
u An integer item is converted to unsigned decimal.
The effects of the precision and the # flag are the
same as for d.
o An integer item is converted to unsigned octal.
The # flag, if specified, causes the precision to
be expanded, and the octal value is printed with a
leading zero (a C convention). The precision
behaves the same as in d above, except that writing
a zero value with a zero precision results in only
the leading zero being written, if the # flag is
specified.
x An integer item is converted to hexadecimal. The
letters abcdef are used in writing hexadecimal
values. The # flag, if specified, causes the
precision to be expanded, and the hexadecimal value
is written with a leading "0x" (a C convention).
The precision behaves as in d above, except that
writing a zero value with a zero precision results
in only the leading "0x" being written, if the #
flag is specified.
X Same as x above, except that the letters ABCDEF are
used to write the hexadecimal value, and the # flag
causes the value to be written with a leading "0X".
The character conversion characters are as follows:
c The character specified by the char item is
written. The precision is meaningless, and the #
flag has no effect.
s The string pointed to by the character pointer item
is written. If a precision is specified,
characters from the string are written until the
number of characters indicated by the precision is
reached, or until a null character is encountered,
whichever comes first. If the precision is
omitted, all characters up to the first null
character are written. The # flag has no effect.
The floating-point conversion characters are:
f The float or double item is converted to decimal
notation in style f; that is, in the form
[-]ddd.ddd
where the number of digits after the decimal point
is equal to the precision. If precision is not
specified, six digits are written after the decimal
point. If the precision is explicitly zero, the
decimal point is eliminated entirely. If the #
flag is specified, a decimal point always appears,
even if no digits follow the decimal point.
e The float or double item is converted to scientific
notation in style e; that is, in the form
[-]d.ddde+-ddd
where there is always one digit before the decimal
point. The number of digits after the decimal
point is equal to the precision. If precision is
not given, six digits are written after the decimal
point. If the precision is explicitly zero, the
decimal point is eliminated entirely. The exponent
always contains exactly three digits. If the #
flag is specified, the result always contains a
decimal point, even if no digits follow the decimal
point.
E Same as e above, except that E is used to introduce
the exponent instead of e (style E).
g The float or double item is converted to either
style f or style e, depending on the size of the
exponent. If the exponent resulting from the
conversion is less than -4 or greater than the
precision, style e is used. Otherwise, style f is
used. The precision specifies the number of
significant digits. Trailing zeros are removed
from the result, and a decimal point appears only
if it is followed by a digit. If the # flag is
specified, the result always has a decimal point,
even if no digits follow the decimal point, and
trailing zeros are not removed.
G Same as the g conversion above, except that style E
is used instead of style e.
Other conversion characters are:
p The argument is a pointer to void. The value of
the pointer is converted to a sequence of printable
characters.
n The argument is a pointer to an integer into which
is written the number of characters written to the
output stream so far by this call to fprintf(). No
argument is converted.
% A % is written. No argument is converted. The
complete conversion specification is &%&%.
The items in the item list may be variable names or expressions. Note
that, with the exception of the s conversion, pointers are not required
in the item list. If the s conversion is used, a pointer to a character
string must be specified.
See Also
setlocale(), putc(), scanf(), fprintf(), printf(), vprintf(), vsprintf(),
stdio(), ANSI C 4.9.6.7