String Format Function
int vsnprintf(char *buffer, size_t count, const char *format, va_list argptr);
int _vsnprintf(char *buffer, size_t count, const char *format, va_list argptr);
int vswprintf(wchar_t *buffer, size_t count, const wchar_t *format, va_list argptr);
int _vsnwprintf(wchar_t *buffer, size_t count, const wchar_t *format, va_list argptr);
int _vsntprintf(TCHAR *buffer, size_t count, const TCHAR *format, va_list argptr);
Internationalization (I18n) Function Overview
The _vsnprintf/vsnprintf function writes a maximum of count characters to buffer, under control of the format argument and the data pointed to by the argptr argument. A null character is placed at the end of the string.
The vswprintf function is unusual in that the ANSI version and the Windows version of vswprintf are actually different functions. This help page documents the ANSI vswprintf function, which is akin to the Windows _vsnwprintf function.
The Windows vswprintf function on the other hand is a wide version of vsprintf. If scanning a Windows code base and investigating the vswprintf function, this is the wrong help page. Please see Windows vswprintf instead.
On Windows platforms, the _vsnprintf function returns the number of bytes written. On error a negative value is returned.
On ANSI platforms, the vsnprintf function returns the number of characters written. Prior to GNU C Library 2.1, on error a negative value was returned. For GNU C Library 2.1 and later, the error return of the vsnprintf function was changed to be compliant with ISO C99 standards. Instead of a negative value return when count is too small, vsnprintf returns the number of bytes needed for a successful operation, excluding the null-terminating byte. It is up to the caller to check that this value is larger than the space allocated, allowing the function to be called again with a sufficient amount of storage space in buffer.
The Windows _vsnwprintf function and ANSI vswprintf function are the wide character versions of _vsnprintf/vsnprintf; their parameters are wide-character strings, and they return the number of wide characters written if successful. On error a negative value is returned.
_vsntprintf is the Windows-only Generic version of the function; with the _MBCS or _UNICODE compiler flags determining its mapping to either vsnprintf or _vsnwprintf.
I18n Issues
If scanning a Windows code base and investigating the vswprintf function, this is the wrong help page. Please see Windows vswprintf instead.
Use the appropriate version of the function as required for internationalization support, noting the following:
Prior to calling one of these functions, ensure that the current locale is set properly by calling setlocale, as string formatting is dependent on the LC_NUMERIC locale category.
See String Formatting in C and C++ for a discussion on locale-sensitive formatting in internationalized applications.
Special care must be taken with the count parameter. See Locale-Sensitive Length Functions for a complete discussion of the issues involved with functions that pass length parameters.
Recommended Replacements*
On Windows platforms, a more secure string function should be used.
These are shown as the first choices in the following table:
*If you're already using the recommended function, see I18n Issues for other reasons why Globalyzer is detecting the function.
String Format Functions
|
