fscanf_s, _fscanf_s_l, fwscanf_s, _fwscanf_s_l

Artículo
06/09/2015

Lee datos con formato de un flujo. Estas versiones de fscanf, _fscanf_l, fwscanf, _fwscanf_l tienen mejoras de seguridad, como se describe en Características de seguridad de CRT.

int fscanf_s( 
   FILE *stream,
   const char *format [,
   argument ]... 
);
int _fscanf_s_l( 
   FILE *stream,
   const char *format,
   locale_t locale [,
   argument ]... 
);
int fwscanf_s( 
   FILE *stream,
   const wchar_t *format [,
   argument ]... 
);
int _fwscanf_s_l( 
   FILE *stream,
   const wchar_t *format,
   locale_t locale [,
   argument ]... 
);

Parámetros

stream
Puntero a la estructura FILE.
format
Cadena de control de formato.
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. Si se produce un error, o si se llega al final del flujo de archivo antes de la primera conversión, el valor devuelto es EOF para fscanf_s y fwscanf_s.

Estas funciones validan sus parámetros. Si stream es un puntero de archivo no válido o format es un puntero nulo, estas funciones invocan el controlador de parámetros no válidos, como se describe en Validación de parámetros. Si la ejecución puede continuar, estas funciones devuelven EOF y establecen errno en EINVAL.

Comentarios

La función fscanf_s lee datos de la posición actual de stream en las ubicaciones que proporcionaargument (de haberlas). Cada argument debe ser un puntero a una variable de un tipo que se corresponda con un especificador de tipo en format. format controla la interpretación de los campos de entrada y tiene el mismo formato y función que el argumento de format para scanf_s. Vea Campos de especificación de formato: funciones scanf y wscanf para obtener una descripción de format. fwscanf_s es una versión con caracteres anchos de fscanf_s; el argumento de formato para fwscanf_s es una cadena de caracteres anchos. Estas funciones se comportan igual si el flujo se abre en modo ANSI. fscanf_s no admite actualmente la entrada desde un flujo UNICODE.

La diferencia principal entre las funciones más seguras (que tienen el sufijo _s) y las demás versiones es que las funciones más seguras requieren el tamaño en caracteres de cada c, C, s, S y el campo de tipo [ que se va a pasar como argumento inmediatamente después de la variable. Para obtener más información, vea scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l y scanf (Especificación de ancho).

Nota

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

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
_ftscanf_s	fscanf_s	fscanf_s	fwscanf_s
_ftscanf_s_l	_fscanf_s_l	_fscanf_s_l	_fwscanf_s_l

Requisitos

Función	Encabezado necesario
fscanf_s, _fscanf_s_l	<stdio.h>
fwscanf_s, _fwscanf_s_l	<stdio.h> o <wchar.h>

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

Ejemplo

// crt_fscanf_s.c
// This program writes formatted
// data to a file. It then uses fscanf to
// read the various data back from the file.
 
#include <stdio.h>
#include <stdlib.h>

FILE *stream;

int main( void )
{
   long l;
   float fp;
   char s[81];
   char c;

   errno_t err = fopen_s( &stream, "fscanf.out", "w+" );
   if( err )
      printf_s( "The file fscanf.out was not opened\n" );
   else
   {
      fprintf_s( stream, "%s %ld %f%c", "a-string", 
               65000, 3.14159, 'x' );
      // Set pointer to beginning of file:
      fseek( stream, 0L, SEEK_SET );

      // Read data back from file:
      fscanf_s( stream, "%s", s, _countof(s) );
      fscanf_s( stream, "%ld", &l );

      fscanf_s( stream, "%f", &fp );
      fscanf_s( stream, "%c", &c, 1 );

      // Output data read:
      printf( "%s\n", s );
      printf( "%ld\n", l );
      printf( "%f\n", fp );
      printf( "%c\n", c );

      fclose( stream );
   }
}