_snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l

Artículo
02/19/2013

Escribe dio formato datos en una cadena.Éstas son versiones de _snprintf, _snprintf_l, _snwprintf, _snwprintf_l con mejoras de seguridad como se describe en Características de seguridad en 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 la Formato-CONTROL.
argument
argumentos opcionales.
locale
la configuración regional a utilizar.

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 nulo.

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 no válido de parámetro, estas funciones establecen buffer en una cadena vacía, establecen errno a ERANGE, y devuelven -1.

Si buffer o format es un puntero de NULL , o si count es menor o igual que cero, se invoca el controlador no válido del parámetro.Si la ejecución puede continuar, este errno establecido funciones a EINVAL y retorno -1.

Para obtener información sobre éstos 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 aparece entre cadenas superpuestas, 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 caracteres.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 de _l son idénticas salvo que utilizan el parámetro locale pasado en lugar de la configuración regional del subproceso actual.

En C++, mediante estas funciones es simplificado con sobrecargas de plantilla; las sobrecargas pueden deducir la longitud de búfer automáticamente (que elimina la necesidad de especificar un argumento de tamaño) y automáticamente pueden reemplazar anterior, funciones de no con sus más recientes, seguros homólogos.Para obtener más información, vea Sobrecargas de plantilla de seguridad.

Asignaciones de la rutina de texto genérico

rutina de Tchar.h	_UNICODE y _MBCS no definido	_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();
}