scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l

Artykuł
06/09/2015

Odczytuje sformatowane dane ze standardowego strumienia wejściowego.Te wersje scanf, _scanf_l, wscanf, _wscanf_l mają wzmocnienia zabezpieczeń, jak opisano w Funkcje zabezpieczeń w 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]... 
);

Parametry

format
Ciąg kontrolki formatu.
argument
Argumenty opcjonalne.
locale
Ustawienia regionalne do użycia.

Wartość zwracana

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 przypisano żadnych pól.Wartością zwracaną jest EOF dla błędu lub w przypadku napotkania znaku końca pliku lub znaku końca ciągu przy pierwszej próbie odczytania znaku.Jeśli format jest wskaźnikiem NULL, wywoływany jest nieprawidłowy parametr uchwytu, zgodnie z opisem w Sprawdzanie poprawności parametru.Jeśli wykonanie może być kontynuowane, scanf_s i wscanf_s zwracają EOF i ustawiają errno na EINVAL

Aby uzyskać informacje o tych i innych kodach błędów, zobacz errno, _doserrno, _sys_errlist, and _sys_nerr.

Uwagi

Funkcja scanf_s odczytuje dane ze standardowego strumienia wejściowego stdin i zapisuje dane w lokalizacji podanej przez argument.Każdy argument musi być wskaźnikiem do zmiennej o typie odpowiadającym specyfikatorowi typu w format.Jeśli kopiowanie odbywa się między nakładającymi się ciągami, zachowanie jest niezdefiniowane.

wscanf_s to wersja znaku dwubajtowego scanf_s; argument format do wscanf_s to ciąg znaku dwubajtowego.wscanf_s i scanf_s zachowują się identycznie, jeżeli strumień jest otwarty w trybie ANSI.scanf_s obecnie nie obsługuje danych wejściowych ze strumienia UNICODE.

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.

W przeciwieństwie do scanf i wscanf, scanf_s i wscanf_s wymagają określenia rozmiaru buforu dla wszystkich parametrów wejściowych typu c, C, s, S lub zestawów kontroli ciągów, które są ujęte w [].Rozmiar buforu w znakach jest przekazywany jako dodatkowy parametr natychmiast po wskaźniku do buforu lub zmiennej.Na przykład, podczas czytania ciągu znaków, rozmiar buforu dla tego ciągu jest przekazywany w następujący sposób:

char s[10];

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

Rozmiar buforu obejmuje kończącą wartość null.Pole określania szerokości można wykorzystać do zapewnienia, że token, który jest wczytywany zmieści się w buforze.Jeśli nie jest używane pole specyfikacji szerokości, a odczyt tokenu jest zbyt duży, aby zmieścić się w buforze, nic nie jest zapisywane do tego buforu.

[!UWAGA]

Parametr rozmiaru ma typ unsigned, nie size_t.

Poniższy przykład pokazuje, że parametr rozmiaru buforu opisuje maksymalną liczbę znaków, nie bajtów.W wywołaniu wscanf_s, szerokość znaków, która jest wskazywana przez typ buforu nie pasuje do szerokości znaków, które są wskazywane przez specyfikator formatu.

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

Specyfikatora formatu S oznacza użycie szerokości znaków, która jest "przeciwna" domyślnej szerokości, która jest obsługiwana przez funkcję.Szerokość znaków jest jednobajtowa, ale funkcja obsługuje znaki dwubajtowe.W tym przykładzie odczytywany jest ciąg maksymalnie 9 znaków o szerokości jednego bajta i umieszczany w buforze znaków o szerokości dwóch bajtów.Znaki są traktowane jako wartości jednobajtowe; dwa pierwsze znaki są przechowywane w ws[0], drugie dwa są przechowywane w ws[1], i tak dalej.

W przypadku znaków pojedynczy znak może wyglądać następująco:

char c;

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

Po przeczytaniu wielu znaków dla ciągów niezakończonych znakiem null, liczby całkowite są używane jako specyfikacja szerokości i rozmiaru buforu.

char c[4];

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

Aby uzyskać więcej informacji, zobacz scanf — Specyfikacje szerokości.

Rutynowe mapowania zwykłego tekstu

Procedura Tchar.h	_UNICODE & _MBCS nie zdefiniowano	_MBCS zdefiniowano	_UNICODE zdefiniowany
_tscanf_s	scanf_s	scanf_s	wscanf_s
_tscanf_s_l	_scanf_s_l	_scanf_s_l	_wscanf_s_l

Aby uzyskać więcej informacji, zobacz Pola specyfikacji formatu dla funkcji wscanf.

Wymagania

Procedura	Wymagany nagłówek
scanf_s, _scanf_s_l	<stdio.h>
wscanf_s, _wscanf_s_l	<stdio.h> lub <wchar.h>

Konsola nie jest obsługiwana w aplikacjach Windows Store.Standardowe uchwyty strumienia powiązane z konsolą—stdin, stdout, i stderr—muszą zostać przekierowane zanim będą wykorzystane przez funkcje środowiska uruchomieniowego C w aplikacjach Windows Store.Dodatkowe informacje o zgodności – zobacz: Zgodność.

Przykład

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

Dla tego wejścia ten program generuje następujące wyniki:

71 98.6 h z Byte characters

36 92.3 y n Wide characters