scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l

Artículo
04/10/2013

Datos con formato lectura de la secuencia de entrada estándar.Éstas son versiones de scanf, _scanf_l, wscanf, _wscanf_l con mejoras de seguridad como se describe en Características de seguridad en CRT.

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
La configuración regional a utilizar.

Valor devuelto

Devuelve el número de campos convierten y asignados correctamente; el valor devuelto no incluye los campos que se leyeron pero no asignados.Devuelve un valor de 0 indica que no se asignó ningún campos.El valor devuelto es EOF para un error o si se encuentra el carácter de fin de archivo o el carácter de la FIN-de- cadena en el primer intento de leer un carácter.Si format es un puntero de NULL, 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 puede continuar, scanf_s y wscanf_s devuelven EOF y errno determinado a EINVAL.

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 scanf_s lee datos de la secuencia de entrada estándar stdin y escribe los datos en la ubicación especificada por argument.Cada argument debe ser un puntero a una variable de un tipo que se corresponda con un especificador de tipo en format.Si la copia tiene lugar entre cadenas superpuestas, el comportamiento es indefinido.

wscanf_s es una versión con caracteres anchos de scanf_s; el argumento de format a wscanf_s es una cadena de caracteres.wscanf_s y scanf_s se comportan exactamente igual idénticamente si la secuencia se abre en el modo de ANSI.scanf_s no admite actualmente la entrada de una secuencia de UNICODE.

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.

A diferencia de scanf y de wscanf, scanf_s y wscanf_s requieren el tamaño de búfer especificar para todos los parámetros de entrada de c con tipo, de C, de s, de S, o de [.El tamaño de búfer en caracteres se pasa como un parámetro adicional inmediatamente después del puntero al búfer o la variable.Por ejemplo, si lee una cadena, el tamaño de búfer para esa cadena se pasa como sigue:

char s[10];

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

El tamaño de búfer incluye la null final.Un campo de la especificación de ancho se puede utilizar para asegurarse de que el símbolo leído en cabrá en el búfer.Si no se utiliza ningún campo de la especificación de ancho, y la lectura de símbolos es demasiado grande caber en el búfer, no se escribirá nada en ese búfer.

[!NOTA]

El parámetro size es de unsigned tipo, no size_t.

El ejemplo siguiente se muestra que el parámetro de tamaño de búfer describe el número máximo de caracteres, no en bytes.En la llamada a wscanf_s, el ancho de caracteres que se indica mediante el tipo de búfer no coincide con el ancho de caracteres que se indica mediante el especificador de formato.

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

El especificador de formato de S indica el uso de ancho de carácter que se “opuesta” width predeterminado admitido por la función.El ancho de carácter es solo- byte, pero la función admite caracteres de doble byte.Este ejemplo lee una cadena de hasta 9 caracteres solo-byte- anchos y los coloca en un búfer doble-byte- ancho de caracteres.Los caracteres se tratan como valores de solo- byte; los primeros dos caracteres se almacenan en ws[0], los segundos dos se almacenan en ws[1], etc.

En el caso de los caracteres, se puede leer un carácter individual como sigue:

char c;

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

Al leer los caracteres para varias cadenas finalizadas no nulas, los enteros se utilizan como la especificación del ancho y el tamaño de búfer.

char c[4];

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

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

Asignaciones de la rutina de Genérico- texto

Rutina de 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 Campos de la especificación de formato — scanf funciona y el wscanf funciona.

Requisitos

Rutina	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 Tienda Windows.Los identificadores estándar de la secuencia asociados a la consola, stdin, stdout, y stderr, deben redirigir antes de que las funciones en tiempo de ejecución de C pueden utilizarlos en las aplicaciones de Tienda Windows.Para obtener información adicional de compatibilidad, vea Compatibilidad en la Introducción.

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, _countof(s), ws, _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, _countof(s), ws, _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);
}