.TH vfprintf() "" "" "STDIO Function (libc)"
.PC "Print formatted text into stream"
.B "#include <stdarg.h>"
.B "#include <stdio.h>"
\fBint\fR
\fBvfprintf(\fIfp\^\fB, \fIformat\^\fB, \fIarguments\^\fB)\fR
\fBFILE*\fIfp\^\fB; char *\fIformat\^\fB; va_list \fIarguments\^\fB;\fR
.PP
.II "stream^print formatted text"
.II "text^print formatted into stream"
.II "print formatted text into stream"
.B vfprintf()
constructs a formatted string and writes it into the stream pointed to by
.IR fp .
It translates integers, floating-point numbers, and strings
into a variety of text formats.
.B vfprintf()
can handle a variable list of arguments of various types.
It is roughly equivalent to \fBfprintf()\fR's conversion specifier
.BR %r .
.PP
.I format
points to a string that can contain text, character constants, and one or
more \fIconversion specifications\fR.
A conversion specification describes how to convert a
particular data type into text.
Each conversion specification is introduced with the
percent sign `%'.
(To print a literal percent sign, use the escape sequence `%%'.)
See
.B printf()
for further discussion of the conversion specification, and for a
table of the type specifiers that can be used with
.BR vfprintf() .
.PP
After
.I format
comes
.IR arguments .
This is of type
.BR va_list ,
which is defined in the header file
.BR stdarg.h .
It has been initialized by the macro
.B va_start()
and points to the base of the list of arguments used by
.BR vfprintf() .
For more information, see the Lexicon entry for
.BR "va_arg()" .
.PP
.I arguments
should access one argument for each conversion specification in
.IR format ,
of the type appropriate to its conversion specification.
For example, if
.I format
contains conversion specifications for an
.BR int ,
a
.BR long ,
and a string, then
.I arguments
access three arguments, being, respectively,
an
.BR int ,
a
.BR long ,
and a
.BR "char *" .
.I arguments
can take only the data types acceptable to the macro
.BR va_arg() ,
namely, the basic types that can be converted
to pointers simply by adding a `*' after the type name.
See
.B va_arg()
for more information on this point.
.PP
If there are fewer arguments than conversion specifications, then
.BR vfprintf() 's
behavior is undefined (and probably unwelcome).
If there are more,
.B vfprintf()
evaluates and then ignores
every argument without a corresponding conversion specification.
If an argument is not of the same type as its corresponding conversion
specifier, then the behavior of
.B vfprintf()
is undefined.
Thus, presenting an
.B int
where
.B vfprintf()
expects a
.B "char *"
may generate unwelcome results.
.PP
If it wrote the formatted string correctly,
.B vfprintf()
returns the number of characters written.
Otherwise, it returns a negative number.
.SH "See Also"
.Xr "fprintf()," fprintf
.Xr "libc," libc
.Xr "printf()," printf
.Xr "sprintf()," sprintf
.Xr "vprintf()," vprintf
.Xr "vsprintf()" vsprintf
.br
\*(AS, \(sc7.9.6.7
.SH Notes
.B vfprintf()
can construct a string up to at least 509 characters long.
