fscanf_s, _fscanf_s_l, fwscanf_s, _fwscanf_s_l

Artículo
07/24/2011

Read formatted data from a stream. These are versions of fscanf, _fscanf_l, fwscanf, _fwscanf_l with security enhancements as described in Security Features in the 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 ]... 
);

Parameters

stream
Pointer to FILE structure.
format
Format-control string.
argument
Optional arguments.
locale
The locale to use.

Return Value

Each of these functions returns the number of fields successfully converted and assigned; the return value does not include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. If an error occurs, or if the end of the file stream is reached before the first conversion, the return value is EOF for fscanf_s and fwscanf_s.

These functions validate their parameters. If stream is ian nvalid file pointer, or format is a null pointer, these functions invoke the invalid parameter handler, as described in Parameter Validation. If execution is allowed to continue, these functions return EOF and set errno to EINVAL.

Remarks

The fscanf_s function reads data from the current position of stream into the locations given by argument (if any). Each argument must be a pointer to a variable of a type that corresponds to a type specifier in format. format controls the interpretation of the input fields and has the same form and function as the format argument for scanf_s; see Format Specification Fields – scanf functions and wscanf Functions for a description of format*.* fwscanf_s is a wide-character version of fscanf_s; the format argument to fwscanf_s is a wide-character string. These functions behave identically if the stream is opened in ANSI mode. fscanf_s doesn't currently support input from a UNICODE stream.

The main difference between the secure functions (with the _s suffix) and the older functions is that the secure functions require the size in characters of each c, C, s, S and [ type field to be passed as an argument immediately following the variable. For more information, see scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l and scanf Width Specification.

Nota

The size parameter is of type unsigned, not size_t.

The versions of these functions with the _l suffix are identical except that they use the locale parameter passed in instead of the current thread locale.

Generic-Text Routine Mappings

TCHAR.H routine	_UNICODE & _MBCS not defined	_MBCS defined	_UNICODE defined
_ftscanf_s	fscanf_s	fscanf_s	fwscanf_s
_ftscanf_s_l	_fscanf_s_l	_fscanf_s_l	_fwscanf_s_l

Requirements

Function	Required header
fscanf_s, _fscanf_s_l	<stdio.h>
fwscanf_s, _fwscanf_s_l	<stdio.h> or <wchar.h>

For additional compatibility information, see Compatibility in the Introduction.

Example

// 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 );
   }
}

a-string
65000
3.141590
x

.NET Framework Equivalent

System::IO::StreamReader::ReadLine. See also Parse methods, such as System::Double::Parse.