_snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l

  • Artículo

Escribe datos con formato en una cadena. Estas funciones son versiones de , , , , , con_snwprintf_lmejoras de seguridad descritas en Características de seguridad de CRT. _snwprintf_snprintf_l_snprintfsnprintf

Sintaxis

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
Tamaño de la ubicación de almacenamiento para la salida. Tamaño en bytes para las funciones que toman chary palabras para las que toman wchar_t.

count
Número máximo de caracteres que se van a escribir. Para las funciones que toman wchar_t, es el número máximo de caracteres anchos que se van a escribir. O _TRUNCATE.

format
Cadena de control de formato.

argument
Argumentos opcionales.

locale
Configuración regional que se va a usar.

Valor devuelto

Número de caracteres escritos, no incluido el terminador NULL. Se devuelve un valor negativo si se produce un error de salida. Consulte Resumen del comportamiento para obtener más información.

Comentarios

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

Resumen del comportamiento

Para la tabla siguiente:

-Deje len que sea el tamaño de los datos con formato. Si la función toma un char búfer, el tamaño está en bytes. Si la función toma un wchar_t búfer, el tamaño especifica el número de palabras de 16 bits.

  • Los caracteres hacen referencia a char caracteres para funciones que toman un char búfer y a wchar_t caracteres para las funciones que toman un wchar_t búfer.
  • Para obtener más información sobre el controlador de parámetros no válidos, vea Validación de parámetros.
Condición Comportamiento Valor devuelto errno Invoca el controlador de parámetros no válidos
Correcto Escribe los caracteres en el búfer mediante la cadena de formato especificada. Número de caracteres escritos, no incluido el terminador NULL. N/D No
Error de codificación durante el formato Si el especificador sde cadena de procesamiento , So Z, se detiene el procesamiento de la especificación de formato. -1 EILSEQ (42) No
Error de codificación durante el formato Si el especificador c de caracteres de procesamiento o C, se omite el carácter no válido. El número de caracteres escritos no se incrementa para el carácter omitido, ni es ningún dato escrito para él. El procesamiento de la especificación de formato continúa después de omitir el especificador con el error de codificación. Número de caracteres escritos, no incluido el terminador NULL. EILSEQ (42) No
buffer == NULL y sizeOfBuffer == 0 y count == 0 No se escriben datos. 0 N/D No
buffer == NULLy o sizeOfBuffer != 0count != 0 Si la ejecución continúa después de que se ejecute el controlador de parámetros no válidos, establece errno y devuelve un valor negativo. -1 EINVAL (22) Sí
buffer != NULL y sizeOfBuffer == 0 No se escriben datos. -1 EINVAL (22) Sí
count == 0 NULL Se coloca al principio del búfer. -1 N/D No
count < 0 No seguro: el valor se trata como sin firmar, lo que probablemente crea un valor grande que da lugar a sobrescribir la memoria que sigue al búfer. Número de caracteres escritos, no incluido el terminador NULL. N/D No
count < sizeOfBuffer y len <= count Todos los datos se escriben y se anexa una terminación NULL . El número de caracteres que se han escrito. N/D No
count < sizeOfBuffer y len > count Los primeros count caracteres se escriben y se anexa una terminación NULL . -1 N/D No
count >= sizeOfBuffer y len < sizeOfBuffer Todos los datos se escriben NULLcon una terminación . El número de caracteres que se han escrito. N/D No
count >= sizeOfBuffer y len >= sizeOfBuffer y count != _TRUNCATE Si la ejecución continúa después de que se ejecute el controlador de parámetros no válidos, establece , establece errnobuffer[0] == NULLy devuelve un valor negativo. -1 ERANGE (34) Sí
count == _TRUNCATE y len >= sizeOfBuffer Escribe la mayor parte de la cadena como se ajusta a buffer y termina NULL. -1 N/D No
count == _TRUNCATE y len < sizeOfBuffer Escribe toda la cadena en buffer con una terminación NULL. Número de caracteres escritos, no incluido el terminador NULL. N/D No
format == NULL No se escriben datos. Si la ejecución continúa después de que se ejecute el controlador de parámetros no válidos, establece errno y devuelve un valor negativo. -1 EINVAL (22) Sí

Para información sobre estos y otros códigos de error, consulte _doserrno, errno_sys_errlist y _sys_nerr.

Importante

Asegúrese de que format no es una cadena definida por el usuario.

A partir de Windows 10 versión 2004 (compilación 19041), la familia de funciones printf imprime números de punto flotante que se pueden representar con exactitud según las reglas de redondeo de IEEE 754. En versiones anteriores de Windows, los números de punto flotante que se pueden representar de forma exacta y terminan en "5" siempre se redondean al alza. IEEE 754 indica que deben redondearse al dígito par más próximo (también conocido como "redondeo bancario"). Por ejemplo, tanto printf("%1.0f", 1.5) como printf("%1.0f", 2.5) deben redondearse a 2. Anteriormente, 1,5 se redondearía a 2 y 2,5 a 3. Este cambio solo afecta a los números que se pueden representar de forma exacta. Por ejemplo, 2,35 (que, cuando se representa en memoria, está más cerca de 2,35000000000000008) se sigue redondeando hasta 2,4. El redondeo realizado por estas funciones ahora también respeta el modo de redondeo de punto flotante que fesetround establece. Anteriormente, el redondeo siempre elegía el comportamiento FE_TONEAREST. Este cambio solo afecta a los programas compilados con Visual Studio 2019 versión 16.2 y posteriores. Para usar el comportamiento de redondeo de punto flotante heredado, establezca un vínculo con "legacy_stdio_float_rounding.obj".

_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 hacerlo en 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, consulte Sobrecargas de plantillas seguras.

Asignaciones de rutinas 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

Routine 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 sobre compatibilidad, consulte Compatibilidad.

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, 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: ''

Consulte también

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
Funciones vprintf