_snprintf、_snprintf_l、_snwprintf、_snwprintf_l

项目
06/09/2015

将格式化的数据写入字符串。提供这些函数的更多安全版本；请参阅 _snprintf_s、_snprintf_s_l、_snwprintf_s、_snwprintf_s_l。

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

参数

buffer
输出的存储位置。
count
可存储的最多字符数。
format
窗体控件字符串。
argument
可选参数。
locale
要使用的区域设置。

有关详细信息，请参阅格式规范语法：printf 和 wprintf 函数。

返回值

将 len 设为格式化数据字符串的长度，不包括终止 null。对于 _snprintf，len 和 count 以字节为单位，而对于 _snwprintf 则以宽字符为单位。

如果 len < count，len 个字符将存储在 buffer 中，附加 null 终止符，并返回 len。

如果 len = count，len 个字符将存储在 buffer 中，不附加 null 终止符，并返回 len。

如果 len > count，count 个字符将存储在 buffer 中，不附加 null 终止符，并返回负值。

如果 buffer 为 null 指针，并且 count 为零，len 将返回为设置输出格式所需的字符数，不包括终止 null。若要使用相同的 argument 和 locale 参数进行成功调用，请分配至少容纳 len + 1 个字符的缓冲区。

如果 buffer 为 null 指针并且 count 不为零，或者 format 为 null 指针，则调用无效参数处理程序，如参数验证中所述。如果允许继续执行，则这些函数返回 -1 并将 errno 设置为 EINVAL。

有关这些和其他错误代码的信息，请参阅 errno、_doserrno、_sys_errlist 和 _sys_nerr。

备注

_snprintf 函数设置字符格式并在 buffer 中存储 count 个或更少字符，当格式化字符串的长度严格小于 count 个字符时，还会追加终止 null 字符。每个 argument（如果有）根据 format 中相应的格式规范进行转换和输出。该格式包括普通字符，其形式和函数与 printf 的 format 参数相同。如果在重叠的字符串之间发生复制，则此行为不确定。

安全说明
确保 format 不是用户定义的字符串。由于此函数不保证 null 终止，特别是返回值为 count 时，因此请确保在后面追加添加了 null 终止符的代码。有关详细信息，请参阅避免缓冲区溢出。

_snwprintf 是 _snprintf 的宽字符版本；_snwprintf 的指针参数是宽字符串。 _snwprintf 中对编码错误的检测可能与 _snprintf 中不同。 _snwprintf 就像 swprintf，将输出写入字符串，而非 FILE 类型的目标。

这些带有 _l 后缀的函数的版本相同，只不过它们使用传递的区域设置参数而不是当前线程区域设置。

在 C++ 中，这些函数具有模板重载，可调用更新、更安全的版本。有关详细信息，请参阅安全模板重载。

一般文本例程映射

Tchar.h 例程	未定义 _UNICODE 和 _MBCS	已定义 _MBCS	已定义 _UNICODE
_sntprintf	_snprintf	_snprintf	_snwprintf
_sntprintf_l	_snprintf_l	_snprintf_l	_snwprintf_l

要求

例程	必需的标头
_snprintf, _snprintf_l	<stdio.h>
_snwprintf, _snwprintf_l	<stdio.h> 或 <wchar.h>

有关更多兼容性信息，请参阅兼容性。

示例

// 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 nul! */
   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 nul because _snprintf doesn't necessarily (if the string 
       * fits without the terminal nul, 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;
}