_snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l

Artículo
06/09/2015

Escribe dio formato datos en una cadena. Estas versiones de _snprintf, _snprintf_l, _snwprintf, _snwprintf_l tienen mejoras de seguridad, como se describe en Características de seguridad de CRT.

int _snprintf_s(
   char *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const char *format [,
   argument] ... 
);
int _snprintf_s_l(
   char *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const char *format,
   locale_t locale [,
   argument] ... 
);
int _snwprintf_s(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const wchar_t *format [,
   argument] ... 
);
int _snwprintf_s_l(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const wchar_t *format,
   locale_t locale [,
   argument] ... 
);
template <size_t size>
int _snprintf_s(
   char (&buffer)[size],
   size_t count,
   const char *format [,
   argument] ... 
); // C++ only
template <size_t size>
int _snwprintf_s(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format [,
   argument] ... 
); // C++ only

Parámetros

buffer
Ubicación de almacenamiento para el resultado.
sizeOfBuffer
El tamaño de la ubicación de almacenamiento para el resultado. Tamaño en bytes para _snprintf_s o tamaño en words para _snwprintf_s.
Count
Número máximo de caracteres a almacenar, o _TRUNCATE.
format
Cadena de control de formato.
argument
Argumentos opcionales.
locale
Configuración regional que se va a usar.

Valor devuelto

_snprintf_s devuelve el número de caracteres almacenado en buffer, sin contar el carácter null de terminación. _snwprintf_s devuelve el número de caracteres anchos almacenados en buffer, sin contar el carácter ancho final null.

Si el almacenamiento necesario almacenar los datos y un carácter null final supera sizeOfBuffer, se invoca el controlador no válido de parámetro, tal y como se describe en Validación de parámetros. Si la ejecución continúa después del controlador de parámetros no válidos, estas funciones establecen buffer en una cadena vacía, establecen errno en ERANGE y devuelven -1.

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

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

Comentarios

La función de _snprintf_s da formato y almacena count o menos caracteres en buffer y anexa un carácter null final. Cada argumento (si existe) se convierte y salida según la especificación correspondiente de formato en format. El formato es coherente con la familia de printf de funciones; vea Sintaxis de especificación de formato: Funciones printf y wprintf. Si la copia tiene lugar entre cadenas que se superponen, el comportamiento es indefinido.

Si count es _TRUNCATE, después _snprintf_s escribe tanto de la cadena que caben en buffer mientras deja el sitio para un carácter null final. Si la cadena completa (con finalizar null) se ajusta en buffer, después _snprintf_s devuelve el número de caracteres tipo (sin incluir la null final); si no, _snprintf_s devuelve -1 para indicar que el truncamiento se produjo.

Nota sobre la seguridad
Asegúrese de que format no es una cadena definida por el usuario.

_snwprintf_s es una versión con caracteres anchos de _snprintf_s; los argumentos de puntero a _snwprintf_s son cadenas de carácter ancho. Detección de errores de codificación en _snwprintf_s podría diferir de que en _snprintf_s. _snwprintf_s, como swprintf_s, salida de escribe en una cadena y no a un destino de FILEescrito.

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

En C++, el uso de estas funciones se simplifica con las sobrecargas de plantilla; las sobrecargas pueden realizar una inferencia automáticamente de la longitud de búfer (lo que elimina la necesidad de especificar un argumento de tamaño) y pueden reemplazar automáticamente funciones anteriores no seguras con sus homólogos seguros 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_s	_snprintf_s	_snprintf_s	_snwprintf_s
_sntprintf_s_l	_snprintf_s_l	_snprintf_s_l	_snwprintf_s_l

Requisitos

Rutina	Encabezado necesario
_snprintf_s, _snprintf_s_l	<stdio.h>
_snwprintf_s, _snwprintf_s_l	<stdio.h> o <wchar.h>

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

Ejemplo

// crt_snprintf_s.cpp
// compile with: /MTd

// These #defines enable secure template overloads
// (see last part of Examples() below)
#define _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES 1 
#define _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT 1

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <crtdbg.h>  // For _CrtSetReportMode
#include <errno.h>

// This example uses a 10-byte destination buffer.

int snprintf_s_tester( const char * fmt, int x, int count )
{
   char dest[10];

   printf( "\n" );

   if ( count == _TRUNCATE )
      printf( "%d-byte buffer; truncation semantics\n",
               _countof(dest) );
   else
      printf( "count = %d; %d-byte buffer\n",
               count, _countof(dest) );

   int ret = _snprintf_s( dest, _countof(dest), count, fmt, x );

   printf( "    new contents of dest: '%s'\n", dest );

   return ret;
}


void Examples()
{
   // formatted output string is 9 characters long: "<<<123>>>"
   snprintf_s_tester( "<<<%d>>>", 121, 8 );
   snprintf_s_tester( "<<<%d>>>", 121, 9 );
   snprintf_s_tester( "<<<%d>>>", 121, 10 );

   printf( "\nDestination buffer too small:\n" );

   snprintf_s_tester( "<<<%d>>>", 1221, 10 );

   printf( "\nTruncation examples:\n" );

   int ret = snprintf_s_tester( "<<<%d>>>", 1221, _TRUNCATE );
   printf( "    truncation %s occur\n", ret == -1 ? "did"
                                                  : "did not" );

   ret = snprintf_s_tester( "<<<%d>>>", 121, _TRUNCATE );
   printf( "    truncation %s occur\n", ret == -1 ? "did"
                                                  : "did not" );
   printf( "\nSecure template overload example:\n" );

   char dest[10];
   _snprintf( dest, 10, "<<<%d>>>", 12321 );
   // With secure template overloads enabled (see #defines
   // at top of file), the preceding line is replaced by
   //    _snprintf_s( dest, _countof(dest), 10, "<<<%d>>>", 12345 );
   // Instead of causing a buffer overrun, _snprintf_s invokes
   // the invalid parameter handler.
   // If secure template overloads were disabled, _snprintf would
   // write 10 characters and overrun the dest buffer.
   printf( "    new contents of dest: '%s'\n", dest );
}

void myInvalidParameterHandler(
   const wchar_t* expression,
   const wchar_t* function, 
   const wchar_t* file, 
   unsigned int line, 
   uintptr_t pReserved)
{
   wprintf(L"Invalid parameter handler invoked: %s\n", expression);
}

int main( void )
{
   _invalid_parameter_handler oldHandler, newHandler;

   newHandler = myInvalidParameterHandler;
   oldHandler = _set_invalid_parameter_handler(newHandler);
   // Disable the message box for assertions.
   _CrtSetReportMode(_CRT_ASSERT, 0);

   Examples();
}