snprintf、_snprintf、_snprintf_l、_snwprintf、_snwprintf_lsnprintf, _snprintf, _snprintf_l, _snwprintf, _snwprintf_l

将格式化的数据写入字符串。Writes formatted data to a string. 提供这些函数的更多安全版本,请参阅 _snprintf_s、_snprintf_s_l、_snwprintf_s、_snwprintf_s_lMore secure versions of these functions are available; see _snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l.

语法Syntax

int snprintf(
   char *buffer,
   size_t count,
   const char *format [,
   argument] ...
);
int _snprintf(
   char *buffer,
   size_t count,
   const char *format [,
   argument] ...
);
int _snprintf_l(
   char *buffer,
   size_t count,
   const char *format,
   locale_t locale [,
   argument] ...
);
int _snwprintf(
   wchar_t *buffer,
   size_t count,
   const wchar_t *format [,
   argument] ...
);
int _snwprintf_l(
   wchar_t *buffer,
   size_t count,
   const wchar_t *format,
   locale_t locale [,
   argument] ...
);
template <size_t size>
int _snprintf(
   char (&buffer)[size],
   size_t count,
   const char *format [,
   argument] ...
); // C++ only
template <size_t size>
int _snprintf_l(
   char (&buffer)[size],
   size_t count,
   const char *format,
   locale_t locale [,
   argument] ...
); // C++ only
template <size_t size>
int _snwprintf(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format [,
   argument] ...
); // C++ only
template <size_t size>
int _snwprintf_l(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format,
   locale_t locale [,
   argument] ...
); // C++ only

参数Parameters

bufferbuffer
输出的存储位置。Storage location for the output.

countcount
可存储的最多字符数。Maximum number of characters to store.

formatformat
窗体控件字符串。Format-control string.

自变量argument
可选参数。Optional arguments.

localelocale
要使用的区域设置。The locale to use.

有关详细信息,请参阅格式规范语法:printf 和 wprintf 函数For more information, see Format Specification Syntax: printf and wprintf Functions.

返回值Return Value

len为不包括终止 null 的格式化的数据字符串的长度。Let len be the length of the formatted data string, not including the terminating null. 同时len计数以字节为单位的snprintf_snprintf,宽字符为 _snwprintf.Both len and count are in bytes for snprintf and _snprintf, wide characters for _snwprintf.

对于所有函数,如果len < 计数len个字符存储在缓冲区,附加 null 终止符,和len返回。For all functions, if len < count, len characters are stored in buffer, a null-terminator is appended, and len is returned.

Snprintf函数截断输出时len大于或等于计数,通过将放置在一个 null 终止符buffer[count-1]The snprintf function truncates the output when len is greater than or equal to count, by placing a null-terminator at buffer[count-1]. 返回的值为len,已经是输出如果的字符数计数是否足够大。The value returned is len, the number of characters that would have been output if count was large enough. Snprintf函数返回一个负值,如果发生编码错误。The snprintf function returns a negative value if an encoding error occurs.

所有函数以外snprintf,如果len = 计数len个字符存储在缓冲区,不附加任何 null 终止符,和len返回。For all functions other than snprintf, if len = count, len characters are stored in buffer, no null-terminator is appended, and len is returned. 如果len > 计数计数个字符存储在缓冲区,任何 null 终止符不追加,因此负返回值。If len > count, count characters are stored in buffer, no null-terminator is appended, and a negative value is returned.

如果缓冲区是 null 指针和计数为零, len返回为所需以格式化输出,不包括终止 null 的字符数。If buffer is a null pointer and count is zero, len is returned as the count of characters required to format the output, not including the terminating null. 若要进行成功调用具有相同参数区域设置参数,分配至少容纳缓冲区len + 1 个字符。To make a successful call with the same argument and locale parameters, allocate a buffer holding at least len + 1 characters.

如果缓冲区是 null 指针和计数不为零,或者如果格式是 null 指针,则调用无效参数处理程序,如中所述参数验证If buffer is a null pointer and count is nonzero, or if format is a null pointer, the invalid parameter handler is invoked, as described in Parameter Validation. 如果允许执行继续,则这些函数将返回-1 并设置errnoEINVALIf execution is allowed to continue, these functions return -1 and set errno to EINVAL.

有关这些及其他错误代码的信息,请参阅 errno、_doserrno、_sys_errlist 和 _sys_nerrFor information about these and other error codes, see errno, _doserrno, _sys_errlist, and _sys_nerr.

备注Remarks

Snprintf函数和 _snprintf系列的函数的格式和存储计数或更少字符中的缓冲区The snprintf function and the _snprintf family of functions format and store count or fewer characters in buffer. Snprintf函数始终存储终止 null 字符,如有必要截断输出。The snprintf function always stores a terminating null character, truncating the output if necessary. _Snprintf系列函数才附加终止 null 字符,当格式化的字符串的长度严格小于计数字符。The _snprintf family of functions only appends a terminating null character if the formatted string length is strictly less than count characters. 每个参数(如果有) 转换和输出中的相应格式规范根据格式Each argument (if any) is converted and is output according to the corresponding format specification in format. 该格式包括普通字符,其形式和函数与相同格式参数printfThe format consists of ordinary characters and has the same form and function as the format argument for printf. 如果在重叠的字符串之间发生复制,则此行为不确定。If copying occurs between strings that overlap, the behavior is undefined.

重要

确保 format 不是用户定义的字符串。Ensure that format is not a user-defined string. 因为 _snprintf函数不保证 null 终止,特别是,当返回的值是计数-确保,在其后追加用于添加 null 终止符的代码。Because the _snprintf functions do not guarantee null termination—in particular, when the return value is count—make sure that they are followed by code that adds the null terminator. 有关详细信息,请参阅 避免缓冲区溢出For more information, see Avoiding Buffer Overruns.

从 Visual Studio 2015 和 Windows 10 中的 UCRT 开始snprintf不再等同于 _snprintfBeginning with the UCRT in Visual Studio 2015 and Windows 10, snprintf is no longer identical to _snprintf. Snprintf函数行为现在是符合 C99 标准。The snprintf function behavior is now C99 standard compliant.

_snwprintf是宽字符版本的 _snprintf; 的指针参数 _snwprintf是宽字符字符串。_snwprintf is a wide-character version of _snprintf; the pointer arguments to _snwprintf are wide-character strings. 编码错误检测 _snwprintf可能会与不同,在 _snprintfDetection of encoding errors in _snwprintf might differ from that in _snprintf. _snwprintf,就像swprintf,将输出写入字符串,而不是类型的目标文件_snwprintf, just like swprintf, writes output to a string instead of a destination of type FILE.

这些函数具有的版本 _l后缀是相同,只不过它们使用传递而不是当前线程区域设置的区域设置参数。The versions of these functions that have the _l suffix are identical except that they use the locale parameter passed in instead of the current thread locale.

在 C++ 中,这些函数具有模板重载,可调用更新、更安全的版本。In C++, these functions have template overloads that invoke their newer, more secure counterparts. 有关详细信息,请参阅 Secure Template OverloadsFor more information, see Secure Template Overloads.

一般文本例程映射Generic-Text Routine Mappings

Tchar.h 例程Tchar.h routine 未定义 _UNICODE 和 _MBCS_UNICODE and _MBCS not defined 已定义 _MBCS_MBCS defined 已定义 _UNICODE_UNICODE defined
_sntprintf_sntprintf _snprintf_snprintf _snprintf_snprintf _snwprintf_snwprintf
_sntprintf_l_sntprintf_l _snprintf_l_snprintf_l _snprintf_l_snprintf_l _snwprintf_l_snwprintf_l

要求Requirements

例程Routine 必需的标头Required header
snprintf_snprintf_snprintf_lsnprintf, _snprintf, _snprintf_l <stdio.h><stdio.h>
_snwprintf_snwprintf_l_snwprintf, _snwprintf_l <stdio.h> 或 <wchar.h><stdio.h> or <wchar.h>

有关更多兼容性信息,请参阅 兼容性For more compatibility information, see Compatibility.

示例Example

// crt_snprintf.c
// compile with: /W3
#include <stdio.h>
#include <stdlib.h>

#if !defined(__cplusplus)
typedef int bool;
const bool true = 1;
const bool false = 0;
#endif

#define FAIL 0 // change to 1 and see what happens

int main(void)
{
   char buffer[200];
   const static char s[] = "computer"
#if FAIL
"computercomputercomputercomputercomputercomputercomputercomputer"
"computercomputercomputercomputercomputercomputercomputercomputer"
"computercomputercomputercomputercomputercomputercomputercomputer"
"computercomputercomputercomputercomputercomputercomputercomputer"
#endif
   ;
   const char c = 'l';
   const int i = 35;
#if FAIL
   const double fp = 1e300; // doesn't fit in the buffer
#else
   const double fp = 1.7320534;
#endif
   /* !subtract one to prevent "squeezing out" the terminal null! */
   const int bufferSize = sizeof(buffer)/sizeof(buffer[0]) - 1;
   int bufferUsed = 0;
   int bufferLeft = bufferSize - bufferUsed;
   bool bSuccess = true;
   buffer[0] = 0;

   /* Format and print various data: */

   if (bufferLeft > 0)
   {
      int perElementBufferUsed = _snprintf(&buffer[bufferUsed],
      bufferLeft, "   String: %s\n", s ); // C4996
      // Note: _snprintf is deprecated; consider _snprintf_s instead
      if (bSuccess = (perElementBufferUsed >= 0))
      {
         bufferUsed += perElementBufferUsed;
         bufferLeft -= perElementBufferUsed;
         if (bufferLeft > 0)
         {
            int perElementBufferUsed = _snprintf(&buffer[bufferUsed],
            bufferLeft, "   Character: %c\n", c ); // C4996
            if (bSuccess = (perElementBufferUsed >= 0))
            {
               bufferUsed += perElementBufferUsed;
               bufferLeft -= perElementBufferUsed;
               if (bufferLeft > 0)
               {
                  int perElementBufferUsed = _snprintf(&buffer
                  [bufferUsed], bufferLeft, "   Integer: %d\n", i ); // C4996
                  if (bSuccess = (perElementBufferUsed >= 0))
                  {
                     bufferUsed += perElementBufferUsed;
                     bufferLeft -= perElementBufferUsed;
                     if (bufferLeft > 0)
                     {
                        int perElementBufferUsed = _snprintf(&buffer
                        [bufferUsed], bufferLeft, "   Real: %f\n", fp ); // C4996
                        if (bSuccess = (perElementBufferUsed >= 0))
                        {
                           bufferUsed += perElementBufferUsed;
                        }
                     }
                  }
               }
            }
         }
      }
   }

   if (!bSuccess)
   {
      printf("%s\n", "failure");
   }
   else
   {
      /* !store null because _snprintf doesn't necessarily (if the string
       * fits without the terminal null, but not with it)!
       * bufferUsed might be as large as bufferSize, which normally is
       * like going one element beyond a buffer, but in this case
       * subtracted one from bufferSize, so we're ok.
       */
      buffer[bufferUsed] = 0;
      printf( "Output:\n%s\ncharacter count = %d\n", buffer, bufferUsed );
   }
   return EXIT_SUCCESS;
}
Output:
   String: computer
   Character: l
   Integer: 35
   Real: 1.732053

character count = 69

请参阅See also

流 I/OStream I/O
sprintf、_sprintf_l、swprintf、_swprintf_l、__swprintf_lsprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l
fprintf、_fprintf_l、fwprintf、_fwprintf_lfprintf, _fprintf_l, fwprintf, _fwprintf_l
printf、_printf_l、wprintf、_wprintf_lprintf, _printf_l, wprintf, _wprintf_l
scanf、_scanf_l、wscanf、_wscanf_lscanf, _scanf_l, wscanf, _wscanf_l
sscanf、_sscanf_l、swscanf、_swscanf_lsscanf, _sscanf_l, swscanf, _swscanf_l
vprintf 函数vprintf Functions