diff --git a/docs/c-runtime-library/reference/vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md b/docs/c-runtime-library/reference/vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md index 04d081cb6d..fae5f98253 100644 --- a/docs/c-runtime-library/reference/vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md +++ b/docs/c-runtime-library/reference/vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md @@ -19,173 +19,173 @@ author: "corob-msft" ms.author: "corob" manager: "ghogen" ms.workload: ["cplusplus"] ---- -# vsprintf, _vsprintf_l, vswprintf, _vswprintf_l, __vswprintf_l -Write formatted output using a pointer to a list of arguments. More secure versions of these functions are available; see [vsprintf_s, _vsprintf_s_l, vswprintf_s, _vswprintf_s_l](../../c-runtime-library/reference/vsprintf-s-vsprintf-s-l-vswprintf-s-vswprintf-s-l.md). - -## Syntax - -``` -int vsprintf( - char *buffer, - const char *format, - va_list argptr -); -int _vsprintf_l( - char *buffer, - const char *format, - locale_t locale, - va_list argptr -); -int vswprintf( - wchar_t *buffer, - size_t count, - const wchar_t *format, - va_list argptr -); -int _vswprintf_l( - wchar_t *buffer, - size_t count, - const wchar_t *format, - locale_t locale, - va_list argptr -); -int __vswprintf_l( - wchar_t *buffer, - const wchar_t *format, - locale_t locale, - va_list argptr -); -template -int vsprintf( - char (&buffer)[size], - const char *format, - va_list argptr -); // C++ only -template -int _vsprintf_l( - char (&buffer)[size], - const char *format, - locale_t locale, - va_list argptr -); // C++ only -template -int vswprintf( - wchar_t (&buffer)[size], - const wchar_t *format, - va_list argptr -); // C++ only -template -int _vswprintf_l( - wchar_t (&buffer)[size], - const wchar_t *format, - locale_t locale, - va_list argptr -); // C++ only -``` - -#### Parameters - `buffer` - Storage location for output. - - `count` - Maximum number of characters to store, in the `UNICODE` version of this function. - - `format` - Format specification. - - `argptr` - Pointer to list of arguments. - - `locale` - The locale to use. - -## Return Value - `vsprintf` and `vswprintf` return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. If `buffer` or `format` is a null pointer, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set `errno` to `EINVAL`. - - For information on these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). - -## Remarks - Each of these functions takes a pointer to an argument list, and then formats and writes the given data to the memory pointed to by `buffer`. - - The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current thread locale. - -> [!IMPORTANT] -> Using `vsprintf`, here is no way to limit the number of characters written, which means that code using this function is susceptible to buffer overruns. Use [_vsnprintf](../../c-runtime-library/reference/vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md) instead, or call [_vscprintf](../../c-runtime-library/reference/vscprintf-vscprintf-l-vscwprintf-vscwprintf-l.md) to determine how large a buffer is needed. Also, ensure that `format` is not a user-defined string. For more information, see [Avoiding Buffer Overruns](http://msdn.microsoft.com/library/windows/desktop/ms717795). - - `vswprintf` conforms to the ISO C Standard, which requires the second parameter, `count`, of type `size_t`. To force the old nonstandard behavior, define `_CRT_NON_CONFORMING_SWPRINTFS.` The old behavior may not be in a future version, so code should be changed to use the new conformant behavior. - - In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). - -### Generic-Text Routine Mappings - -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|`_vstprintf`|`vsprintf`|`vsprintf`|`vswprintf`| -|`_vstprintf_l`|`_vsprintf_l`|`_vsprintf_l`|`_vswprintf_l`| - -## Requirements - -|Routine|Required header|Optional headers| -|-------------|---------------------|----------------------| -|`vsprintf`, `_vsprintf_l`|\ and \|\*| -|`vswprintf`, `_vswprintf_l`|\ or \, and \|\*| - - \* Required for UNIX V compatibility. - - For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md) in the Introduction. - -## Example - -``` -// crt_vsprintf.c -// compile with: /W3 -// This program uses vsprintf to write to a buffer. -// The size of the buffer is determined by _vscprintf. - -#include -#include -#include - -void test( char * format, ... ) -{ - va_list args; - int len; - char *buffer; - - // retrieve the variable arguments - va_start( args, format ); - - len = _vscprintf( format, args ) // _vscprintf doesn't count - + 1; // terminating '\0' - - buffer = (char*)malloc( len * sizeof(char) ); - - vsprintf( buffer, format, args ); // C4996 - // Note: vsprintf is deprecated; consider using vsprintf_s instead - puts( buffer ); - - free( buffer ); - va_end( args ); -} - -int main( void ) -{ - test( "%d %c %d", 123, '<', 456 ); - test( "%s", "This is a string" ); -} -``` - -```Output -123 < 456 -This is a string -``` - -## See Also - [Stream I/O](../../c-runtime-library/stream-i-o.md) - [vprintf Functions](../../c-runtime-library/vprintf-functions.md) - [Format Specification Syntax: printf and wprintf Functions](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md) - [fprintf, _fprintf_l, fwprintf, _fwprintf_l](../../c-runtime-library/reference/fprintf-fprintf-l-fwprintf-fwprintf-l.md) - [printf, _printf_l, wprintf, _wprintf_l](../../c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md) - [sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](../../c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md) - [va_arg, va_copy, va_end, va_start](../../c-runtime-library/reference/va-arg-va-copy-va-end-va-start.md) \ No newline at end of file +--- +# vsprintf, _vsprintf_l, vswprintf, _vswprintf_l, __vswprintf_l +Write formatted output using a pointer to a list of arguments. More secure versions of these functions are available; see [vsprintf_s, _vsprintf_s_l, vswprintf_s, _vswprintf_s_l](../../c-runtime-library/reference/vsprintf-s-vsprintf-s-l-vswprintf-s-vswprintf-s-l.md). + +## Syntax + +``` +int vsprintf( + char *buffer, + const char *format, + va_list argptr +); +int _vsprintf_l( + char *buffer, + const char *format, + locale_t locale, + va_list argptr +); +int vswprintf( + wchar_t *buffer, + size_t count, + const wchar_t *format, + va_list argptr +); +int _vswprintf_l( + wchar_t *buffer, + size_t count, + const wchar_t *format, + locale_t locale, + va_list argptr +); +int __vswprintf_l( + wchar_t *buffer, + const wchar_t *format, + locale_t locale, + va_list argptr +); +template +int vsprintf( + char (&buffer)[size], + const char *format, + va_list argptr +); // C++ only +template +int _vsprintf_l( + char (&buffer)[size], + const char *format, + locale_t locale, + va_list argptr +); // C++ only +template +int vswprintf( + wchar_t (&buffer)[size], + const wchar_t *format, + va_list argptr +); // C++ only +template +int _vswprintf_l( + wchar_t (&buffer)[size], + const wchar_t *format, + locale_t locale, + va_list argptr +); // C++ only +``` + +#### Parameters + `buffer` + Storage location for output. + + `count` + Maximum number of characters to store, in the `UNICODE` version of this function. + + `format` + Format specification. + + `argptr` + Pointer to list of arguments. + + `locale` + The locale to use. + +## Return Value + `vsprintf` and `vswprintf` return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. If `buffer` or `format` is a null pointer, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set `errno` to `EINVAL`. + + For information on these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). + +## Remarks + Each of these functions takes a pointer to an argument list, and then formats and writes the given data to the memory pointed to by `buffer`. + + The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current thread locale. + +> [!IMPORTANT] +> Using `vsprintf`, there is no way to limit the number of characters written, which means that code using this function is susceptible to buffer overruns. Use [_vsnprintf](../../c-runtime-library/reference/vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md) instead, or call [_vscprintf](../../c-runtime-library/reference/vscprintf-vscprintf-l-vscwprintf-vscwprintf-l.md) to determine how large a buffer is needed. Also, ensure that `format` is not a user-defined string. For more information, see [Avoiding Buffer Overruns](http://msdn.microsoft.com/library/windows/desktop/ms717795). + + `vswprintf` conforms to the ISO C Standard, which requires the second parameter, `count`, of type `size_t`. To force the old nonstandard behavior, define `_CRT_NON_CONFORMING_SWPRINTFS.` The old behavior may not be in a future version, so code should be changed to use the new conformant behavior. + + In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). + +### Generic-Text Routine Mappings + +|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| +|---------------------|------------------------------------|--------------------|-----------------------| +|`_vstprintf`|`vsprintf`|`vsprintf`|`vswprintf`| +|`_vstprintf_l`|`_vsprintf_l`|`_vsprintf_l`|`_vswprintf_l`| + +## Requirements + +|Routine|Required header|Optional headers| +|-------------|---------------------|----------------------| +|`vsprintf`, `_vsprintf_l`|\ and \|\*| +|`vswprintf`, `_vswprintf_l`|\ or \, and \|\*| + + \* Required for UNIX V compatibility. + + For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md) in the Introduction. + +## Example + +``` +// crt_vsprintf.c +// compile with: /W3 +// This program uses vsprintf to write to a buffer. +// The size of the buffer is determined by _vscprintf. + +#include +#include +#include + +void test( char * format, ... ) +{ + va_list args; + int len; + char *buffer; + + // retrieve the variable arguments + va_start( args, format ); + + len = _vscprintf( format, args ) // _vscprintf doesn't count + + 1; // terminating '\0' + + buffer = (char*)malloc( len * sizeof(char) ); + + vsprintf( buffer, format, args ); // C4996 + // Note: vsprintf is deprecated; consider using vsprintf_s instead + puts( buffer ); + + free( buffer ); + va_end( args ); +} + +int main( void ) +{ + test( "%d %c %d", 123, '<', 456 ); + test( "%s", "This is a string" ); +} +``` + +```Output +123 < 456 +This is a string +``` + +## See Also + [Stream I/O](../../c-runtime-library/stream-i-o.md) + [vprintf Functions](../../c-runtime-library/vprintf-functions.md) + [Format Specification Syntax: printf and wprintf Functions](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md) + [fprintf, _fprintf_l, fwprintf, _fwprintf_l](../../c-runtime-library/reference/fprintf-fprintf-l-fwprintf-fwprintf-l.md) + [printf, _printf_l, wprintf, _wprintf_l](../../c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md) + [sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](../../c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md) + [va_arg, va_copy, va_end, va_start](../../c-runtime-library/reference/va-arg-va-copy-va-end-va-start.md)