scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l

Lee datos con formato del flujo de entrada estándar. Estas versiones de scanf, _scanf_l, wscanf, _wscanf_l tienen mejoras de seguridad, como se describe en Características de seguridad de CRT.

Sintaxis

int scanf_s(
   const char *format [,
   argument]...
);
int _scanf_s_l(
   const char *format,
   _locale_t locale [,
   argument]...
);
int wscanf_s(
   const wchar_t *format [,
   argument]...
);
int _wscanf_s_l(
   const wchar_t *format,
   _locale_t locale [,
   argument]...
);

Parámetros

format
Cadena de control de formato.

argument
Argumentos opcionales.

locale
Configuración regional que se va a usar.

Valor devuelto

Devuelve el número de campos que se han convertido y asignado correctamente. El valor devuelto no incluye los campos que se han leído pero no se han asignado. Un valor devuelto de 0 indica que no se ha asignado ningún campo. El valor devuelto es EOF para un error o si se encuentra el carácter final del archivo o el carácter de fin de cadena en el primer intento de leer un carácter. Si format es un NULL puntero, se invoca el controlador de parámetros no válidos, como se describe en Validación de parámetros. Si la ejecución puede continuar, scanf_s y wscanf_s devuelven EOF y establecen errno en EINVAL.

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

Comentarios

La función scanf_s lee datos del flujo de entrada estándar stdin y los escribe en argument. Cada argument debe ser un puntero a un tipo de variable que se corresponda con el especificador de tipo en format. Si la copia tiene lugar entre cadenas que se superponen, el comportamiento es indefinido.

wscanf_s es una versión con caracteres anchos de scanf_s; el argumento format para wscanf_s es una cadena de caracteres anchos. wscanf_s y scanf_s se comportan exactamente igual si el flujo se abre en modo ANSI. scanf_s no admite actualmente la entrada desde un flujo UNICODE.

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

A diferencia de scanf y wscanf, scanf_s y wscanf_s requieren que especifique tamaños de búfer para algunos parámetros. Especifique los tamaños de todos los parámetros c, C, s, S, o del conjunto de controles de cadena []. El tamaño del búfer en caracteres se pasa como otro parámetro. Inmediatamente sigue el puntero al búfer o variable. Por ejemplo, si está leyendo una cadena, el tamaño de búfer para esa cadena se pasa de la siguiente manera:

char s[10];
scanf_s("%9s", s, (unsigned)_countof(s)); // buffer size is 10, width specification is 9

El tamaño de búfer incluye el valor null final. Puede usar un campo de especificación de ancho para garantizar que el token que se lee se ajusta al búfer. Cuando un token es demasiado grande para ajustarse, no se escribe nada en el búfer a menos que haya una especificación de ancho.

Nota:

El parámetro de tamaño es del tipo unsigned, no size_t. Use una conversión estática para convertir un valor size_t en unsigned para las configuraciones de compilación de 64 bits.

El parámetro de tamaño de búfer describe el número máximo de caracteres, no de bytes. En este ejemplo, el ancho del tipo de búfer no coincide con el ancho del especificador de formato.

wchar_t ws[10];
wscanf_s(L"%9S", ws, (unsigned)_countof(ws));

El especificador de formato S significa el uso del ancho de carácter que es “opuesto” al ancho predeterminado que admite la función. El ancho de carácter es de un solo byte, pero la función admite caracteres de doble byte. En este ejemplo se lee una cadena de hasta 9 caracteres con ancho de un solo byte y los coloca en un búfer de caracteres con ancho de doble byte. Los caracteres se tratan como valores de un solo byte; los primeros dos caracteres se almacenan en ws[0], los siguientes dos se almacenan en ws[1], y así sucesivamente.

En este ejemplo se lee un único carácter:

char c;
scanf_s("%c", &c, 1);

Cuando se leen varios caracteres para cadenas que no tienen un valor null final, se usan enteros para la especificación del ancho y el tamaño de búfer.

char c[4];
scanf_s("%4c", c, (unsigned)_countof(c)); // not null terminated

Para obtener más información, vea Especificación de ancho de scanf.

Asignaciones de rutinas de texto genérico

Rutina TCHAR.H	_UNICODE y _MBCS no definidos	_MBCS definido	_UNICODE definido
_tscanf_s	scanf_s	scanf_s	wscanf_s
_tscanf_s_l	_scanf_s_l	_scanf_s_l	_wscanf_s_l

Para obtener más información, vea Formato de campos de especificación: scanf y wscanf funciones.

Requisitos

Routine	Encabezado necesario
scanf_s, _scanf_s_l	<stdio.h>
wscanf_s, _wscanf_s_l	<stdio.h> o <wchar.h>

La consola no se admite en las aplicaciones de la Plataforma universal de Windows (UWP). Se deben redirigir los identificadores estándar de flujo stdin, stdout y stderr, antes de que las funciones en tiempo de ejecución de C puedan usarlos en aplicaciones para UWP. Para obtener más información sobre compatibilidad, consulte Compatibilidad.

Ejemplo

// crt_scanf_s.c
// This program uses the scanf_s and wscanf_s functions
// to read formatted input.

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

int main( void )
{
   int      i,
            result;
   float    fp;
   char     c,
            s[80];
   wchar_t  wc,
            ws[80];

   result = scanf_s( "%d %f %c %C %s %S", &i, &fp, &c, 1,
                     &wc, 1, s, (unsigned)_countof(s), ws, (unsigned)_countof(ws) );
   printf( "The number of fields input is %d\n", result );
   printf( "The contents are: %d %f %c %C %s %S\n", i, fp, c,
           wc, s, ws);
   result = wscanf_s( L"%d %f %hc %lc %S %ls", &i, &fp, &c, 2,
                      &wc, 1, s, (unsigned)_countof(s), ws, (unsigned)_countof(ws) );
   wprintf( L"The number of fields input is %d\n", result );
   wprintf( L"The contents are: %d %f %C %c %hs %s\n", i, fp,
            c, wc, s, ws);
}

Este programa produce el siguiente resultado cuando se especifica esta entrada:

71 98.6 h z Byte characters
36 92.3 y n Wide characters

The number of fields input is 6
The contents are: 71 98.599998 h z Byte characters
The number of fields input is 6
The contents are: 36 92.300003 y n Wide characters

Consulte también

Compatibilidad con matemáticas y punto flotante
E/S de secuencia
Configuración regional
fscanf, _fscanf_l, fwscanf, _fwscanf_l
printf, _printf_l, wprintf, _wprintf_l
sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l
sscanf, _sscanf_l, swscanf, _swscanf_l