.TH vsprintf() "" "" "STDIO Function (libc)"
.PC "Print formatted text into string"
.B "#include <stdarg.h>"
.B "#include <stdio.h>"
\fBint\fR
\fBvsprintf(\fIstring\^\fB, \fIformat\^\fB, \fIarguments\^\fB)\fR
\fBchar *\fIstring\^\fB, *\fIformat\^\fB; va_list \fIarguments\^\fB;\fR
.PP
.II "string^print formatted text"
.II "text^print formatted into string"
.B vsprintf()
constructs a formatted string in the area pointed to by
.IR string .
It translates integers, floating-point numbers, and strings
into a variety of text formats.
.B vsprintf()
can handle a variable list of arguments of various types.
It is roughly equivalent to
the `%r' conversion
specifier to \fBsprintf()\fR.
.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 a particular text format.
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 vsprintf() .
.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 vsprintf() .
For more information, see
.BR va_arg() .
.PP
.I arguments
should access one argument for each conversion specification in
.I format
of the type appropriate to the 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 *" .
If there are fewer arguments than conversion specifications, then
.BR vsprintf() 's
behavior is undefined (and probably unwelcome).
If there are more,
.B vsprintf()
evaluates and then ignores every argument without a corresponding
conversion specification.
If an argument is not of the same type as its corresponding type
specification, then the behavior of
.B vsprintf()
is undefined; thus, accessing an
.B int
where
.B vsprintf
expects a
.B "char *"
may generate unwelcome results.
.PP
If it writes the formatted string correctly,
.B vsprintf()
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.9
.SH Notes
.B vsprintf()
can construct a string up to at least 509 characters long.
.\".PP
.\"The character that
.\".B vsprintf
.\"uses to represent the decimal point is affected by the program's locale,
.\"as set by the function
.\".BR setlocale .
.\"For more information, see
.\".BR localization .
