vsnprintf - Formatted output to a string

Definition

#include <stdarg.h> #include <stdio.h> int vnsprintf(char *s, size_t n, const char *format, va_list arg); vsnprintf is similar to the snprintf function. In contrast to snprintf, vsnprintf enables arguments to be output whose number and data types are not known at compilation time. vsnprintf is used within functions to which the caller can pass a different format string and different arguments for output each time. The formal parameter list of the function definition provides for a format string format and a variable argument list ", ..." for this purpose. vsnprintf successively steps through an argument list arg using internal va_arg calls and writes the arguments according to format string format to string s. The variable argument list arg must be initialized with the va_start macro before vsprintf is called. vsnprintf only outputs up to the buffer limit specified by the n parameter. This prevents buffer overrun.

Parameters  char *s

Pointer to the result string. vsprintf terminates the string with the null byte (\0). The maximum length of the output is therefore n-1.

size_t n

Length of the area reserved for the result string. n may not be greater than INT_MAX. When n = 0, no output takes place.

const char *format

Format string as described under printf with ANSI functionality (cf. printf).

The only difference is the way in which the control characters for white space (\n, \t, etc.) are handled: vsprintf enters the value of the control character into the result string. It is only during output to text files that the control characters are converted to their appropriate effect depending on the type of text file (see section “White space” (Basic terms)).

va_list arg

Pointer to the variable argument list initialized with va_start.

Returnwert   < 0		n > INT_MAX or output error. It was possible to edit the output completely. The return value specifies the length of the output without the terminating NULL character. It was not possible to edit the output completely. The return value specifies the length of the output without the terminating NULL character which a complete output would require.
	= 0 .. n-1 > n

Notes     vsnprintf always starts with the first argument in the variable argument list. It is possible

to start output from any particular argument by issuing the appropriate number of va_arg calls before calling the vsprintf function. Each va_arg call advances the position in the argument list by one argument.

vsnprintf does not call the va_end macro. Since vsnprintf uses the va_arg macro, the value of arg is undefined on return.

The behavior is undefined if memory areas overlap.

See also      vfprintf, vprintf , vsprintf