_snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l

 

Publicado: octubre de 2016

Para obtener la documentación más reciente de Visual Studio 2017 RC, consulte Documentación de Visual Studio 2017 RC.

Escribe datos con formato en una cadena. Estas son versiones de snprintf, _snprintf, _snprintf_l, _snwprintf, _snwprintf_l con 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 del resultado.

sizeOfBuffer
El tamaño de la ubicación de almacenamiento para la salida. El tamaño de bytes de _snprintf_s o tamaño en words para _snwprintf_s.

Count
Número máximo de caracteres que se va a almacenar, o _TRUNCATE.

format
Cadena de control de formato.

argument
Argumentos opcionales.

locale
Configuración regional que se va a usar.

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

Si supera el almacenamiento necesario para almacenar los datos y un valor null de terminación sizeOfBuffer, se invoca el controlador de parámetros no válidos, como se describe en validación del parámetro. 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, consulte _doserrno, errno, _sys_errlist y _sys_nerr.

El _snprintf_s almacenes y formatos de la función count o menos caracteres en buffer y anexa un carácter nulo. Cada argumento (si existe) se convierte y sale según la especificación de formato correspondiente en format. El formato es coherente con el printf familia 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, a continuación, _snprintf_s escrituras como gran parte de la cadena como caben en buffer y dejan espacio para un carácter nulo. Si la cadena completa (con valor nulo final) cabe en buffer, a continuación, _snprintf_s devuelve el número de caracteres escrito (sin incluir el carácter null); en caso contrario, _snprintf_s devuelve -1 para indicar que el truncamiento se produjo.

System_CAPS_ICON_important.jpg Importante

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. La detección de errores de codificación en _snwprintf_s puede diferir de la de _snprintf_s. _snwprintf_s, como swprintf_s, escribe el resultado en una cadena en lugar de a un destino de tipo FILE.

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 el requisito 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, consulta Secure Template Overloads.

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
RutinaEncabezado necesario
_snprintf_s, _snprintf_s_l<stdio.h>
_snwprintf_s, _snwprintf_s_l<stdio.h> o <wchar.h>

Para obtener más información sobre compatibilidad, vea Compatibility en la introducción.

// 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, size_t count )  
{  
   char dest[10];  
  
   printf( "\n" );  
  
   if ( count == _TRUNCATE )  
      printf( "%zd-byte buffer; truncation semantics\n",  
               _countof(dest) );  
   else  
      printf( "count = %zd; %zd-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();  
}  

  
count = 8; 10-byte buffer  
    new contents of dest: '<<<121>>'  
  
count = 9; 10-byte buffer  
    new contents of dest: '<<<121>>>'  
  
count = 10; 10-byte buffer  
    new contents of dest: '<<<121>>>'  
  
Destination buffer too small:  
  
count = 10; 10-byte buffer  
Invalid parameter handler invoked: ("Buffer too small", 0)  
    new contents of dest: ''  
  
Truncation examples:  
  
10-byte buffer; truncation semantics  
    new contents of dest: '<<<1221>>'  
    truncation did occur  
  
10-byte buffer; truncation semantics  
    new contents of dest: '<<<121>>>'  
    truncation did not occur  
  
Secure template overload example:  
Invalid parameter handler invoked: ("Buffer too small", 0)  
    new contents of dest: ''  

No es aplicable. Para llamar a la función estándar de C, use PInvoke. Para obtener más información, vea Ejemplos de invocación de plataforma.

E/S de secuencia
sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l
fprintf, _fprintf_l, fwprintf, _fwprintf_l
printf, _printf_l, wprintf, _wprintf_l
scanf, _scanf_l, wscanf, _wscanf_l
sscanf, _sscanf_l, swscanf, _swscanf_l
vprintf (funciones)

Mostrar: