_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. len и count в байтах для _snprintf, расширенных символах для _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, and _sys_nerr.

Заметки

Функция _snprintf форматирует и сохраняет count или меньшее число символов в buffer и добавляет конечный символ null, если длина форматированной строки строго меньше, чем count символов. Каждый argument (при наличии) преобразуется и выводится согласно соответствующей спецификации формата в format. Формат состоит из обычных символов и имеет те же форму и функциональные возможности, что и аргумент format для printf. Если копирование производится между перекрывающимися строками, поведение не определено.

Примечание по безопасности
Убедитесь, что format не является строкой, определяемой пользователем.Поскольку эта функция не гарантирует конечное значение NULL, в частности, если возвращаемое значение — count, убедитесь, что далее следует код, добавляющий конечное значение NULL.Дополнительные сведения см. в разделе Как избежать переполнения буфера.

Убедитесь, что 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;
}