scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l

Artikel
06/09/2015

Liest formatierte Daten aus dem Standardeingabestream. Diese Versionen von scanf, _scanf_l, wscanf, _wscanf_l enthalten Sicherheitserweiterungen wie unter Sicherheitsfunktionen in der CRT beschrieben.

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]... 
);

Parameter

format
Formatsteuerzeichenfolge.
argument
Optionale Argumente.
locale
Das zu verwendende Gebietsschema.

Rückgabewert

Gibt die Anzahl von Feldern zurück, die erfolgreich konvertiert und zugewiesen wurden; der Rückgabewert umfasst keine Felder, die gelesen, aber nicht zugewiesen wurden. Ein Rückgabewert von 0 gibt an, dass keine Felder zugewiesen wurden. Der Rückgabewert ist im Fall eines Fehlers EOF. Dies gilt auch, wenn das Dateiendezeichen oder das Zeichenfolgeendezeichen beim ersten Versuch, das Zeichen zu lesen, erkannt wird. Wenn format ein NULL-Zeiger ist, wird der Handler für ungültige Parameter aufgerufen, wie in Parametervalidierung beschrieben. Wenn die weitere Ausführung zugelassen wird, geben scanf_s und wscanf_s den Wert EOF zurück und setzen errno auf EINVAL.

Informationen zu diesen und anderen Fehlercodes finden Sie unter errno, _doserrno, _sys_errlist und _sys_nerr.

Hinweise

Die scanf_s-Funktion liest Daten aus dem Standardeingabestream stdin und schreibt die Daten in den Speicherort, der von argument angegeben wird. Jedes argument muss ein Zeiger auf einen Variablentyp sein, der einem Typspezifizierer im format entspricht. Wenn der Kopiervorgang zwischen Zeichenfolgen ausgeführt wird, die sich überschneiden, ist das Verhalten nicht definiert.

wscanf_s ist eine Breitzeichenversion von scanf_s. Das format-Argument für wscanf_s ist eine Breitzeichenfolge. wscanf_s und scanf_s verhalten sich identisch, wenn der Stream in ANSI-Modus geöffnet ist. scanf_s unterstützt derzeit nicht die Eingabe aus einem UNICODE-Stream.

Die Versionen dieser Funktionen mit dem _l-Suffix sind beinahe identisch, verwenden jedoch den Gebietsschemaparameter, der anstelle des aktuellen Threadgebietsschemas übergeben wurde.

Anders als scanf und wscanf erfordern scanf_s und wscanf_s eine Angabe der Puffergröße für alle Eingabeparameter vom Typ c, C, s und S oder Zeichenfolgensätze, die in [] enthalten sind. Die Puffergröße in Zeichen wird als zusätzlicher Parameter direkt nach dem Zeiger auf den Puffer oder die Variable übergeben. Beim Lesen einer Zeichenfolge wird beispielsweise die Puffergröße für diese Zeichenfolge wie folgt übergeben:

char s[10];

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

Die Puffergröße enthält das abschließende NULL-Zeichen. Sie können ein Feld für die Breitenangabe verwenden, um sicherzustellen, dass das eingelesene Token in den Puffer passt. Wenn kein Feld für die Breiteangabe verwendet wird und das eingelesen Token zu groß für den Puffer ist, wird nichts in diesen Puffer geschrieben.

Hinweis

Der Größenparameter ist vom Typ unsigned und nicht vom Typ size_t.

Im folgenden Beispiel wird gezeigt, dass der Puffergrößenparameter die maximale Anzahl von Zeichen, aber nicht von Bytes beschreibt. Im Aufruf von wscanf_s, stimmt die Zeichenbreite, die von dem Puffertyp angegeben ist, nicht mit der Zeichenbreite überein, die im Formatbezeichner angegeben ist.

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

Der Formatbezeichner S gibt die Verwendung der Zeichenbreite an, die zu der von der Funktion unterstützten Standardbreite einen "Gegensatz" darstellt. Die Zeichen sind ein Byte breit, aber die Funktion unterstützt Doppelbytezeichen. In diesem Beispiel wird eine Zeichenfolge bis maximal 9 Einzelbytezeichen eingelesen und an einen Puffer für Doppelbytezeichen übergeben. Die Zeichen werden als Einzelbytewerte behandelt; die ersten zwei Zeichen werden in ws[0] gespeichert, die zweiten zwei Zeichen in ws[1] usw.

Im Fall von Zeichen wird ein einzelnes Zeichen wie folgt gelesen:

char c;

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

Wenn mehrere Zeichen für Zeichenfolgen gelesen werden, die nicht mit NULL abschließen, werden ganze Zahlen für die Breitenangabe und die Puffergröße verwendet.

char c[4];

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

Weitere Informationen finden Sie unter scanf-Breitenangabe.

Zuordnung generischer Textroutinen

TCHAR.H-Routine	_UNICODE & _MBCS nicht definiert	_MBCS definiert	_UNICODE definiert
_tscanf_s	scanf_s	scanf_s	wscanf_s
_tscanf_s_l	_scanf_s_l	_scanf_s_l	_wscanf_s_l

Weitere Informationen finden Sie unter Formatangabefelder: scanf- und wscanf-Funktionen.

Anforderungen

Routine	Erforderlicher Header
scanf_s, _scanf_s_l	<stdio.h>
wscanf_s, _wscanf_s_l	<stdio.h> oder <wchar.h>

Die Konsole wird in Windows Store-Apps nicht unterstützt. Die mit der Konsole verknüpften Standardstreamhandles, stdin, stdout und stderr, müssen umgeleitet werden, bevor sie von C-Laufzeitfunktionen in Windows Store-Apps verwendet werden können. Zusätzliche Informationen zur Kompatibilität finden Sie unter Kompatibilität.

Beispiel

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

Dieses Programm generiert bei dieser Eingabe die folgende Ausgabe:

71 98.6 h z Byte characters

36 92.3 y n Wide characters