Chapter Contents |
Previous |
Next |
vsnprintf |
Portability: | SAS/C extension |
SYNOPSIS | |
DESCRIPTION | |
RETURN VALUE | |
CAUTION | |
IMPLEMENTATION | |
EXAMPLE | |
RELATED FUNCTIONS | |
SEE ALSO |
SYNOPSIS |
#include <stdarg.h> #include <lcio.h> int vsnprintf(char *dest, size_t maxlen, const char *format, va_list arg);
DESCRIPTION |
The
vsnprintf
function is equivalent to the
snprintf
function, except that
arg
replaces
the variable-argument list.
arg
must have
been initialized by the
va_start
macro
and possibly
va_arg
calls. The
vsnprintf
function does not invoke the
va_end
macro. See va_arg,
va_end, and va_start for details
on varying-length argument-list functions. The
vsnprintf
function writes formatted output to the area addressed by
dest
under control of the string addressed by
format
until either all format conversion specifications
have been satisfied or until
maxlen
characters
have been written. If the
maxlen
limit
is reached
maxlen
vsnprintf
function returns a negative value whose magnitude is equal to the value of
maxlen
.
In all other respects,
vsnprintf
behaves identically to
vsprintf
. The string
pointed to by format is in the same form as that used
by
fprintf
. Refer to the
fprintf
function description for detailed information concerning the
format conversions.
RETURN VALUE |
The
vsnprintf
function returns an integer value that equals in magnitude the number
of characters written to the area addressed by
dest
. If the value returned is negative, then either the
maxlen
character limit was reached or some other error, such as an
invalid format specification, has occurred. The one exception to this is
if an error occurs before any characters are stored,
vsnprintf
returns INT_MIN (-2**31).
CAUTION |
If the
maxlen
value is 0, no characters are written, and
vsnprintf
returns 0. If the value is greater than
INT_MAX
, then
vsnprintf
behaves
identically to
vsprintf
in that no limit
checking is done on the number of characters written to the output area. No
warnings concerning length errors are produced by
vsnprintf
, and the only indication that the output may have been truncated
or is incomplete is a negative return value.
IMPLEMENTATION |
When invoked with a limit greater than
512 characters, the
vsnprintf
function
calls
malloc
to obtain a temporary spill
buffer equal in size to the limit specified. If insufficient storage is available,
vsnprintf
attempts to process the format specifications
with an internal 512-byte spill buffer. In this case, individual conversion
specifiers that produce more than 512 characters may fail, and
vsnprintf
processing can terminate prematurely.
EXAMPLE |
#include <stdlib.h> #include <lcio.h> #include <stdarg.h> static void format_msg(char *, size_t, char *, ...); #define NOTE 0 #define WARNING 1 #define MESSAGE_LEN 80 static const char *msgs[] = { "Msgno%04d This is message number zero", "Msgno%04d This message requires a %s" }; main() { char msgbuf(|84|); format_msg(msgbuf, MESSAGE_LEN, msgs[NOTE], NOTE); printf("The formatted message is: \"%s\" \n", msgbuf); format_msg(msgbuf, MESSAGE_LEN, msg[WARNING], WARNING, "a replacement string"); printf("The formatted message is: \"%s\" \n", msgbuf); return; } static void format_msg(char *buf, size_t limit, char *format,...) { va_list args; va_start(args, format), vsnprintf(buf, limit, format, args); va_end(args); }
RELATED FUNCTIONS |
snprintf
,
va_start
,
vsprintf
SEE ALSO |
Chapter Contents |
Previous |
Next |
Top of Page |
Copyright © 2001 by SAS Institute Inc., Cary, NC, USA. All rights reserved.