scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l

Artikel
03/12/2013

Lesen formatierte Daten im Standardeingabestream.Diese sind Versionen von scanf, _scanf_l, wscanf, _wscanf_l mit Sicherheitserweiterungen, wie in Sicherheitsfeatures im 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 Gebietsschema zu verwenden.

Rückgabewert

Gibt die Anzahl der erfolgreich konvertierten und zugewiesenen Feldern zurück; der Rückgabewert umfasst keine Felder, die gelesen wurden, jedoch nicht zugewiesen.Ein Rückgabewert 0 gibt an, dass keine Felder zugewiesen wurden.Der Rückgabewert ist EOF für einen Fehler oder, wenn das Dateiendezeichen oder das abschließendes Zeichen im ersten Versuch ein Zeichen festgestellt wird.Wenn format ein NULL Zeiger ist, ist der ungültige Parameterhandler aufgerufen, wie in Parametervalidierung beschrieben.Wenn die Ausführung zulässig ist, um fortzufahren, geben scanf_s und wscanf_sEOF und Menge errno zu EINVAL zurück.

Weitere Informationen über diese und andere Fehlercodes, finden Sie unter _doserrno, errno, _sys_errlist und _sys_nerr.

Hinweise

Die scanf_s-Funktion liest Daten im Standardeingabestream stdin und schreibt die Daten in den Speicherort, der für argument angegeben ist.Jedes argument muss ein Zeiger auf eine Variable eines Typs handeln, der zu einem Typspezifizierer in format entspricht.Wenn das Kopieren zwischen Zeichenfolgen stattfindet, die sich überschneiden, wird das Verhalten nicht definiert.

wscanf_s ist eine Breitzeichen-Version von scanf_s; format das Argument an wscanf_s ist eine Zeichenfolge mit Breitzeichen.wscanf_s und scanf_s verhalten sich identisch identisch, wenn der Stream in ANSI-Modus geöffnet ist.scanf_s nicht unterstützt Eingaben von einem UNICODE-Stream.

Die Versionen dieser Funktionen mit dem _l Suffix sind identisch, allerdings verwenden den Gebietsschemaparameter in, der anstelle des aktuellen Threadgebietsschemas übergeben wird.

Anders als scanf und wscanf benötigen scanf_s und wscanf_s die Puffergröße, für alle Eingabeparameter des Typs c, C, s, S oder [ angegeben werden.Die Puffergröße in Zeichen wird als zusätzlichen Parameter direkt nach dem Zeiger auf den Puffer oder Variable übergeben.Wenn Sie beispielsweise eine Zeichenfolge, die Puffergröße für diese Zeichenfolge übergeben wird, lautet wie folgt:

char s[10];

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

Die Puffergröße umfasst das endgültige NULL-Zeichen.Ein Breitenangabenfeld verwendet werden, um sicherzustellen, dass das Token, das gelesen wird, der Puffer aufnehmen kann.Wenn kein Breitenangabenfeld verwendet wird und das Scheinlesen zu groß ist, in den Puffer passt, wird nichts zu diesem Puffer geschrieben.

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

Im folgenden Beispiel wird gezeigt, dass der Puffergrößenparameter die maximale Anzahl von Zeichen beschreibt, nicht Bytes dar.Im Aufruf von wscanf_s, entspricht die Zeichenbreite, die vom Puffertyp angegeben ist, nicht die Zeichenbreite ab, die vom Formatbezeichner angegeben wird.

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

Der S Formatbezeichners gibt die Verwendung der Zeichenbreite an, die "gegenüberliegenden" der Standardbreite ist, die von der Funktion unterstützt wird.Die Zeichenbreite ist Einzelbyte-, aber die Funktionsstützdoppelbytezeichen.Dieses Beispiel liest in eine Zeichenfolge mit bis zu 9 Zeichen einzel-Byte-weiten und in einem Double-Byte-weiten Zeichenpuffer ein.Die Zeichen werden als behandelt, Einzelbytewerte die ersten beiden Zeichen werden in ws[0], die beiden zweiten sind in ws[1], usw. gespeichert.

Bei der Zeichen liest Sie potenziell ein einzelnes Zeichen, wie folgt:

char c;

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

Als beendet das Lesen von mehreren Zeichen für NULL Zeichenfolgen, werden ganze Zahlen als 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 generische 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 Formatangaben-Felder - scanf Funktionen 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 nicht in Windows Store-App unterstützt.Die Standardstreamhandles, die mit der Konsole, stdin, stdout und stderr zugeordnet werden, müssen umgeleitet werden, bevor sie C-Laufzeitfunktionen in Windows Store-App verwenden können.So zusätzlicher Kompatibilitätsinformation finden Sie unter Kompatibilität in der Einführung.

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