C++ vsnprintf()

The vsnprint() function was introduced in C++ 11. Unlike vsprintf(), the maximum number of characters that can be written to the buffer is specified in vsnprintf().

vsnprintf() prototype

int vsnprintf( char* buffer, size_t buf_size, const char* format, va_list vlist );

The vsnprintf() function writes the string pointed to by format to a character string buffer. The maximum number of characters that can be written is buf_size. After the characters are written, a terminating null character is added. If buf_size is equal to zero, nothing is written and buffer may be a null pointer.

The string format may contain format specifiers starting with % which are replaced by the values of variables that are passed as a list vlist.

It is defined in <cstdio> header file.

vsnprintf() Parameters

• buffer: Pointer to a character string to write the result.
• buf_size: Maximum number of characters to write.
• format: Pointer to a null terminated string that is written to the file stream. It consists of characters along with optional format specifiers starting with %.

  The format specifiers are replaced by the values of respective variables that follows the format string.

  The format specifier has the following parts:

  • A leading % sign
  • Flags: Optional one or more flags that modifies the conversion behavior.
    • - : Left justify the result within the field. By default it is right justified.
    • + : The sign of the result is attached to the beginning of the value, even for positive results.
    • Space: If there is no sign, a space is attached to the beginning of the result.
    • # : An alternative form of the conversion is performed.
    • 0 : It is used for integer and floating point number. Leading zeros are used to pad the numbers instead of space.
  • Width: An optional * or integer value used to specify minimum width field.
  • Precision : An optional field consisting of a . followed by * or integer or nothing to specify the precision.
  • Length : An optional length modifier that specifies the size of the argument.
  • Specifier: A conversion format specifier. The available format specifiers are as follows:

    Format Specifier	Description
    %	Prints %
    c	Writes a single character
    s	Writes a character string
    d or i	Converts a signed integer to decimal representation
    o	Converts an unsigned integer to octal representation
    X or x	Converts an unsigned integer to hexadecimal representation
    u	Converts an unsigned integer to decimal representation
    F or f	Converts floating-point number to the decimal representation
    E or e	Converts floating-point number to the decimal exponent notation
    A or a	Converts floating-point number to the hexadecimal exponent
    G or g	Converts floating-point number to either decimal or decimal exponent notation
    n	Returns the number of characters written so far by this call to the function. The result is written to the value pointed to by the argument
    p	Writes an implementation defined character sequence defining a pointer.

    So the general format of format specifier is: %[flags][width][.precision][length]specifier

• vlist: A list of arguments containing the data to write.

vsnprintf() Return value

• If successful, the vsnprintf() function returns number of characters written.
• On failure it returns a negative value.
• When the length of the formatted string is greater than buf_size, it needs to be truncated. In such cases, the vsnprintf() function returns the total number of characters excluding the terminating null character which would have been written, if the buf_size limit was not imposed.

Example: How vsnprintf() function works

#include <cstdio>
#include <cstdarg>

void write(char* buf, int buf_size, const char *fmt, ...)
{
    va_list args;
    va_start(args, fmt);
    vsnprintf(buf, buf_size, fmt, args);
    va_end(args);
}

int main ()
{
    char buffer[100];
    char fname[20] = "Bjarne";
    char lname[20] = "Stroustrup";
    char lang[5] = "C++";

    write(buffer, 27, "%s was created by %s %s\n", lang, fname, lname);

    printf("%s", buffer);

    return 0;
}

When you run the program, the output will be:

C++ was created by Bjarne