int vfprintf(FILE *__stream, const char *__fmt, va_list __ap)
vfprintf is the central facility of the
printf family of functions. It outputs values to
stream under control of a format string passed in
fmt. The actual values to print are passed as a
variable argument list ap.
vfprintf returns the number of characters written
to stream, or EOF in
case of an error. Currently, this will only happen if
stream has not been opened with write intent.
The format string is composed of zero or more directives: ordinary characters (not
%), which are copied unchanged to the output stream;
and conversion specifications, each of which results in fetching zero or more subsequent
arguments. Each conversion specification is introduced by the
% character. The arguments must properly correspond
(after type promotion) with the conversion specifier. After the
%, the following appear in sequence:
# The value should be converted to an
"alternate form". For c, d, i, s, and u conversions, this option has no
effect. For o conversions, the precision of the number is increased to force
the first character of the output string to a zero (except if a zero value
is printed with an explicit precision of zero). For x and X conversions, a
non-zero result has the string `0x' (or `0X' for X conversions) prepended to
it.
0 (zero) Zero padding. For all
conversions, the converted value is padded on the left with zeros rather
than blanks. If a precision is given with a numeric conversion (d, i, o, u,
i, x, and X), the 0 flag is ignored.
- A negative field width flag; the
converted value is to be left adjusted on the field boundary. The converted
value is padded on the right with blanks, rather than on the left with
blanks or zeros. A - overrides a 0 if both are given.
' ' (space) A blank should be left before a positive number produced by a signed conversion (d, or i).
+ A sign must always be placed before a
number produced by a signed conversion. A + overrides a space if both are
used.
An optional decimal digit string specifying a minimum field width. If the converted value has fewer characters than the field width, it will be padded with spaces on the left (or right, if the left-adjustment flag has been given) to fill out the field width.
An optional precision, in the form of a period . followed by an optional digit
string. If the digit string is omitted, the precision is taken as zero. This gives
the minimum number of digits to appear for d, i, o, u, x, and X conversions, or
the maximum number of characters to be printed from a string for
s conversions.
An optional l or
h length modifier, that specifies that the
argument for the d, i, o, u, x, or X conversion is a "long
int" rather than int. The
h is ignored, as "short
int" is equivalent to
int.
A character that specifies the type of conversion to be applied.
The conversion specifiers and their meanings are:
diouxX The int (or appropriate variant)
argument is converted to signed decimal (d and i), unsigned octal (o), unsigned
decimal (u), or unsigned hexadecimal (x and X) notation. The letters "abcdef" are
used for x conversions; the letters "ABCDEF" are used for X conversions. The
precision, if any, gives the minimum number of digits that must appear; if the
converted value requires fewer digits, it is padded on the left with zeros.
p The void *
argument is taken as an unsigned integer, and converted similarly as a
%#x command would do.
c The int
argument is converted to an "unsigned char", and
the resulting character is written.
s The "char
*" argument is expected to be a pointer to an array of
character type (pointer to a string). Characters from the array are written up to
(but not including) a terminating NUL character; if a precision is specified, no
more than the number specified are written. If a precision is given, no null
character need be present; if the precision is not specified, or is greater than
the size of the array, the array must contain a terminating NUL character.
% A % is
written. No argument is converted. The complete conversion specification is
"%%".
eE The double argument is rounded and
converted in the format "[-]d.ddde±dd" where
there is one digit before the decimal-point character and the number of digits
after it is equal to the precision; if the precision is missing, it is taken as 6;
if the precision is zero, no decimal-point character appears. An
E conversion uses the letter
'E' (rather than
'e') to introduce the exponent. The exponent
always contains two digits; if the value is zero, the exponent is 00.
fF The double argument is rounded and
converted to decimal notation in the format
"[-]ddd.ddd", where the number of digits after
the decimal-point character is equal to the precision specification. If the
precision is missing, it is taken as 6; if the precision is explicitly zero, no
decimal-point character appears. If a decimal point appears, at least one digit
appears before it.
gG The double argument is converted in style
f or e (or
F or E for
G conversions). The precision specifies the
number of significant digits. If the precision is missing, 6 digits are given; if
the precision is zero, it is treated as 1. Style
e is used if the exponent from its conversion
is less than -4 or greater than or equal to the precision. Trailing zeros are
removed from the fractional part of the result; a decimal point appears only if it
is followed by at least one digit.
S Similar to the
s format, except the pointer is expected to
point to a program-memory (ROM) string instead of a RAM string.
In no case does a non-existent or small field width cause truncation of a numeric field; if the result of a conversion is wider than the field width, the field is expanded to contain the conversion result.
Since the full implementation of all the mentioned features becomes fairly large,
three different flavours of vfprintf() can be selected using linker options. The default vfprintf() implements all the mentioned functionality except floating point
conversions. A minimized version of vfprintf() is available that only implements the very basic integer and string
conversion facilities, but only the # additional option
can be specified using conversion flags (these flags are parsed correctly from the
format specification, but then simply ignored). This version can be requested using the
following compiler options:
-Wl,-u,vfprintf -lprintf_min
If the full functionality including the floating point conversions is required, the following options should be used:
-Wl,-u,vfprintf -lprintf_flt -lm
The specified width and precision can be at most 255.
For floating-point conversions, if you link default or minimized version
of vfprintf(), the symbol ? will be
output and double argument will be skiped. So you output below will not be
crashed. For default version the width field and the "pad to left" ( symbol
minus ) option will work in this case.
The hh length modifier is ignored
(char argument is promouted to
int). More exactly, this realization does
not check the number of h symbols.
But the ll length modifier will to abort
the output, as this realization does not operate
long
long arguments.
The variable width or precision field (an asterisk
* symbol) is not realized and will to abort
the output.