_snprintf, _snprintf_l, _snwprintf, _snwprintf_l

Artículo
06/09/2015

Escribe datos con formato en una cadena. Hay disponibles versiones más seguras de estas funciones; vea _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

Parámetros

buffer
Ubicación de almacenamiento del resultado.
count
Número máximo de caracteres que se pueden almacenar.
format
Cadena de control de formato.
argument
Argumentos opcionales.
locale
Configuración regional que se va a usar.

Para obtener más información, vea Sintaxis de especificación de formato: Funciones printf y wprintf.

Valor devuelto

Deje que len sea la longitud de la cadena de datos con formato, sin incluir el carácter null final. len y count se miden en bytes para _snprintf y en caracteres anchos para _snwprintf.

Si len < count, se almacenan len caracteres en buffer, se anexa un terminador null y se devuelve len.

Si len = count, se almacenan len caracteres en buffer, no se anexa ningún terminador null y se devuelve len.

Si len > count, se almacenan count caracteres en buffer, no se anexa ningún terminador null y se devuelve un valor negativo.

Si buffer es un puntero null y count es cero, se devuelve len como el número de caracteres necesarios para dar formato al resultado, sin incluir el carácter null final. Para realizar una llamada correcta con los mismos parámetros argument y locale, asigne un búfer que contenga al menos len + 1 caracteres.

Si buffer es un puntero null y count es distinto de cero, o si format es un puntero null, se invoca el controlador de parámetros no válidos, como se describe en Validación de parámetros. Si la ejecución puede continuar, estas funciones devuelven -1 y establecen errno en EINVAL.

Para obtener más información sobre estos y otros códigos de error, vea errno, _doserrno, _sys_errlist y _sys_nerr.

Comentarios

La función _snprintf da formato y almacena count o menos caracteres en buffer, y anexa un carácter null final si la longitud de la cadena con formato es estrictamente menor que count caracteres. Cada argument (si existe) se convierte y se muestra según la especificación de formato correspondiente de format. El formato consta de caracteres ordinarios y tiene el mismo formato y función que el argumento format para printf. Si la copia tiene lugar entre cadenas que se superponen, el comportamiento es indefinido.

Nota sobre la seguridad
Asegúrese de que format no es una cadena definida por el usuario.Puesto que esta función no garantiza la finalización en NULL, en concreto cuando el valor devuelto es count, hay que asegurarse de que seguida de código que agrega el terminador null.Para obtener más información, vea Evitar saturaciones del búfer.

_snwprintf es una versión con caracteres anchos de _snprintf; los argumentos de puntero a _snwprintf son cadenas de carácter ancho. La detección de errores de codificación en _snwprintf puede diferir de la de _snprintf. _snwprintf, como swprintf, escribe el resultado en una cadena en lugar de hacerlo en un destino de tipo FILE.

Las versiones de estas funciones que tienen el sufijo _l son idénticas salvo que usan el parámetro de configuración regional que se pasa en lugar de la configuración regional del subproceso actual.

En C++, estas funciones tienen sobrecargas de plantilla que invocan sus homólogos más seguros y más recientes. Para obtener más información, vea Sobrecargas de plantilla seguras.

Asignaciones de rutina de texto genérico

Rutina Tchar.h	_UNICODE y _MBCS no definidos	_MBCS definido	_UNICODE definido
_sntprintf	_snprintf	_snprintf	_snwprintf
_sntprintf_l	_snprintf_l	_snprintf_l	_snwprintf_l

Requisitos

Rutina	Encabezado necesario
_snprintf, _snprintf_l	<stdio.h>
_snwprintf, _snwprintf_l	<stdio.h> o <wchar.h>

Para obtener más información de compatibilidad, vea Compatibilidad.

Ejemplo

// 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;
}