fscanf_s, _fscanf_s_l, fwscanf_s, _fwscanf_s_l

Artykuł
06/09/2015

Odczyty sformatowanych danych ze strumienia.Te wersje fscanf, _fscanf_l, fwscanf, _fwscanf_l mają wzmocnienia zabezpieczeń, jak opisano w Funkcje zabezpieczeń w 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 ]... 
);

Parametry

stream
Wskaźnik na FILE strukturę.
format
Ciąg formantu formatu.
argument
Argumenty opcjonalne.
locale
Ustawienia regionalne do użycia.

Wartość zwracana

Każda z tych funkcji zwraca liczbę pól pomyślnie przekonwertowanych i przypisanych; zwracana wartość nie uwzględnia pól, które zostały odczytane, ale nie przypisane.Zwracana wartość wynosząca 0 wskazuje, że nie przydzielono żadnych pól.Jeśli wystąpi błąd lub osiągnięty zostanie koniec strumienia pliku przed dokonaniem pierwszej konwersji, zwracana wartość wynosi EOF dla fscanf_s i fwscanf_s.

Te funkcje sprawdzają poprawność swoich parametrów.Jeśli parametr stream jest nieprawidłowym wskaźnikiem pliku lub parametr format jest pustym wskaźnikiem, funkcje te wywołują nieprawidłowy program obsługi parametrów, zgodnie z opisem w temacie Sprawdzanie poprawności parametru.Jeśli wykonanie może być kontynuowane, te funkcje zwracają EOF i ustawiają errno na EINVAL.

Uwagi

Funkcja fscanf_s odczytuje dane z bieżącego położenia stream do lokalizacji, które zostały określone w argument (jeśli w ogóle).Każdy argument musi być wskaźnikiem do zmiennej o typie odpowiadającym specyfikatorowi typu w format.format steruje interpretacją pól wejściowych i ma tę samą postać oraz funkcję jak argument format dla funkcji scanf_s; aby uzyskać opis format, zobacz Pola specyfikacji formatu dla funkcji wscanf. fwscanf_s jest wersją fscanf_s dla znaków dwubajtowych; argument formatu dla fwscanf_s jest ciągiem znaków dwubajtowych.Funkcje te zachowują się identycznie, jeżeli strumień jest otwarty w trybie ANSI.fscanf_s obecnie nie obsługuje danych wejściowych ze strumienia UNICODE.

Główna różnica między funkcjami bardziej bezpiecznymi (które mają sufiks _s) a innymi wersjami polega na tym, że funkcje bardziej bezpieczne wymagają, aby rozmiar (jako liczba znaków) każdego typu pola c, C, s, S i [ został przekazany jako argument zaraz po zmiennej.Aby uzyskać więcej informacji, zobacz scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l i scanf — Specyfikacje szerokości.

[!UWAGA]

Parametr rozmiaru ma typ unsigned, nie size_t.

Funkcje w wersji z przyrostkiem _l są identyczne, z tą różnicą, że używają parametru ustawień regionalnych, który jest przekazywany zamiast ustawień regionalnych bieżącego wątku.

Rutynowe mapowania zwykłego tekstu

Procedura Tchar.h	_UNICODE & _MBCS nie zdefiniowano	_MBCS zdefiniowano	_UNICODE zdefiniowany
_ftscanf_s	fscanf_s	fscanf_s	fwscanf_s
_ftscanf_s_l	_fscanf_s_l	_fscanf_s_l	_fwscanf_s_l

Wymagania

Funkcja	Wymagany nagłówek
fscanf_s, _fscanf_s_l	<stdio.h>
fwscanf_s, _fwscanf_s_l	<stdio.h> lub <wchar.h>

Dodatkowe informacje o zgodności – zobacz: Zgodność.

Przykład

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