sscanf_s, _sscanf_s_l, swscanf_s, _swscanf_s_l

Artículo
06/09/2015

Lee datos con formato de una cadena. Estas versiones de sscanf, _sscanf_l, swscanf, _swscanf_l tienen mejoras de seguridad, como se describe en Características de seguridad de CRT.

int sscanf_s(
   const char *buffer,
   const char *format [,
   argument ] ...
);
int _sscanf_s_l(
   const char *buffer,
   const char *format,
   locale_t locale [,
   argument ] ...
);
int swscanf_s(
   const wchar_t *buffer,
   const wchar_t *format [,
   argument ] ...
);
int _swscanf_s_l(
   const wchar_t *buffer,
   const wchar_t *format,
   locale_t locale [,
   argument ] ...
);

Parámetros

buffer
Datos almacenados
format
Cadena de control de formato. Para obtener más información, vea Campos de especificación de formato: funciones scanf y wscanf.
argument
Argumentos opcionales
locale
Configuración regional que se va a usar

Valor devuelto

Cada una de estas funciones devuelve el número de campos que se convierten y asignan correctamente; el valor devuelto no incluye los campos que se leyeron pero no se asignaron. Un valor devuelto de 0 indica que no se ha asignado ningún campo. El valor devuelto es EOF en caso de error o si el final de la cadena se alcanza antes de la primera conversión.

Si buffer o format es un puntero NULL, se invoca el controlador de parámetros no válidos, 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 sscanf_s lee datos de buffer en la ubicación que proporcionada por cada argument. Los argumentos que están después de la cadena de formato especifican punteros a variables que tienen un tipo que se corresponde a un especificador de tipo en format. A diferencia de la versión menos segura sscanf, se requiere un parámetro de tamaño de búfer cuando se utilizan caracteres de campo de tipo c, C, s, S, o conjuntos de control de cadena que se incluyen en []. El tamaño de búfer en caracteres se debe proporcionar como un parámetro adicional inmediatamente después de cada parámetro de búfer que lo necesite. Por ejemplo, si está leyendo en una cadena, el tamaño de búfer para esa cadena se pasa como se indica a continuación:

wchar_t ws[10];

swscanf_s(in_str, L"%9s", ws, _countof(ws)); // buffer size is 10, width specification is 9

El tamaño de búfer incluye el valor nulo final. Se puede usar un campo de especificación del ancho para garantizar que el token se ajustará al búfer. Si no se usa ningún campo de especificación de ancho y la lectura de token es demasiado grande como para ajustarse al búfer, no se escribirá ningún valor en dicho búfer.

En el caso de los caracteres, un carácter individual puede leerse como se indica a continuación:

wchar_t wc;

swscanf_s(in_str, L"%c", &wc, 1);

En este ejemplo se lee un solo carácter de la cadena de entrada y se almacena en un búfer de caracteres anchos. Al leer varios caracteres para cadenas que no tienen un valor nulo final, se usan enteros sin signo como especificación del ancho y el tamaño de búfer.

char c[4];

sscanf_s(input, "%4c", &c, _countof(c)); // not null terminated

Para obtener más información, vea scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l y scanf (Caracteres de campo de tipo).

Nota

El parámetro de tamaño es del tipo unsigned, no size_t.

El argumento format controla la interpretación de los campos de entrada y tiene el mismo formato y función que el argumento format para la función scanf_s. Si la copia tiene lugar entre cadenas que se superponen, el comportamiento es indefinido.

swscanf_s es una versión con caracteres anchos de sscanf_s; los argumentos para swscanf_s son cadenas de caracteres anchos. sscanf_s no controla caracteres hexadecimales multibyte. swscanf_s no controla caracteres de "zona de compatibilidad" o hexadecimal de ancho completo de Unicode. De lo contrario, los objetos swscanf_s y sscanf_s se comportan de forma idéntica.

Las versiones de estas funciones con 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.

Asignaciones de rutina de texto genérico

Rutina TCHAR.H	_UNICODE y _MBCS no definidos	_MBCS definido	_UNICODE definido
_stscanf_s	sscanf_s	sscanf_s	swscanf_s
_stscanf_s_l	_sscanf_s_l	_sscanf_s_l	_swscanf_s_l

Requisitos

Rutina	Encabezado necesario
sscanf_s, _sscanf_s_l	<stdio.h>
swscanf_s, _swscanf_s_l	<stdio.h> o <wchar.h>

Para obtener información adicional de compatibilidad, vea Compatibilidad.

Ejemplo

// crt_sscanf_s.c
// This program uses sscanf_s to read data items
// from a string named tokenstring, then displays them.

#include <stdio.h>
#include <stdlib.h>

int main( void )
{
   char  tokenstring[] = "15 12 14...";
   char  s[81];
   char  c;
   int   i;
   float fp;

   // Input various data from tokenstring:
   // max 80 character string plus NULL terminator
   sscanf_s( tokenstring, "%s", s, _countof(s) );
   sscanf_s( tokenstring, "%c", &c, sizeof(char) );
   sscanf_s( tokenstring, "%d", &i );
   sscanf_s( tokenstring, "%f", &fp );

   // Output the data read
   printf_s( "String    = %s\n", s );
   printf_s( "Character = %c\n", c );
   printf_s( "Integer:  = %d\n", i );
   printf_s( "Real:     = %f\n", fp );
}