sscanf_s, _sscanf_s_l, swscanf_s, _swscanf_s_l

Artikel
06/09/2015

Liest formatierte Daten aus einer Zeichenfolge. Diese Versionen von sscanf, _sscanf_l, swscanf, _swscanf_l enthalten Sicherheitserweiterungen wie unter Sicherheitsfunktionen in der CRT beschrieben.

int sscanf_s(
   const char *buffer,
   const char *format [,
   argument ] ...
);
int _sscanf_s_l(
   const char *buffer,
   const char *format,
   locale_t locale [,
   argument ] ...
);
int swscanf_s(
   const wchar_t *buffer,
   const wchar_t *format [,
   argument ] ...
);
int _swscanf_s_l(
   const wchar_t *buffer,
   const wchar_t *format,
   locale_t locale [,
   argument ] ...
);

Parameter

buffer
Gespeicherte Daten
format
Formatsteuerzeichenfolge. Weitere Informationen finden Sie unter Formatangabefelder: scanf- und wscanf-Funktionen.
argument
Optionale Argumente
locale
Das zu verwendende Gebietsschema

Rückgabewert

Jede dieser Funktionen gibt die Anzahl der Felder 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 bei einem Fehler oder beim Erreichen des Endes der Zeichenfolge vor der ersten Konvertierung lautet EOF.

Wenn buffer oder format ein NULL-Zeiger ist, wird, wie in Parametervalidierung beschrieben, der Handler für ungültige Parameter aufgerufen. Wenn die weitere Ausführung zugelassen wird, geben diese Funktionen "– 1" zurück und legen errno auf EINVAL fest.

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

Hinweise

Die sscanf_s-Funktion liest Daten aus buffer in den Speicherort, der durch das jeweilige argument angegeben wird. Die Argumente nach der Formatzeichenfolge geben Zeiger zu den Variablen an, die einen Typ haben, der einem Typspezifizierer in format entspricht. Im Gegensatz zu den weniger sicheren sscanf-Versionen ist bei der Verwendung der Typfeldzeichen c, C, s, S oder von in [] enthaltenen Zeichenfolgensteuerungssätzen ein Puffergrößenparameter erforderlich. Nach jedem Pufferparameter, der dies erfordert, muss die Puffergröße in Zeichen als zusätzlicher Parameter angegeben werden. Beim Einlesen einer Zeichenfolge wird beispielsweise die Puffergröße für diese Zeichenfolge wie folgt übergeben:

wchar_t ws[10];

swscanf_s(in_str, L"%9s", ws, _countof(ws)); // buffer size is 10, width specification is 9

Die Puffergröße enthält das abschließende NULL-Zeichen. Ein Feld für die Breitenangabe muss verwendet werden, 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.

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

wchar_t wc;

swscanf_s(in_str, L"%c", &wc, 1);

In diesem Beispiel wird ein einzelnes Zeichen aus der Eingabezeichenfolge gelesen und dann in einem Breitzeichenpuffer gespeichert. Wenn mehrere Zeichen für Zeichenfolgen gelesen werden, die nicht mit NULL abschließen, werden ganze Zahlen ohne Vorzeichen für die Breitenangabe und die Puffergröße verwendet.

char c[4];

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

Weitere Informationen finden Sie unter scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l und scanf-Typenfeldzeichen.

Hinweis

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

Das format-Argument steuert die Interpretation der Eingabefelder und hat die gleiche Form und Funktion wie das format-Argument für die scanf_s-Funktion. Wenn der Kopiervorgang zwischen Zeichenfolgen ausgeführt wird, die sich überschneiden, ist das Verhalten nicht definiert.

swscanf_s ist eine Breitzeichenversion von sscanf_s;. Die Argumente für swscanf_s sind Zeichenfolgen mit Breitzeichen. sscanf_s verarbeitet keine Multibyte-Hexadezimalzeichen. swscanf_s verarbeitet keine Unicode-Hexadezimalzeichen in voller Breite (Kompatibilitätszonenzeichen). Andernfalls verhalten sich swscanf_s und sscanf_s identisch.

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

Zuordnung generischer Textroutinen

TCHAR.H-Routine	_UNICODE & _MBCS nicht definiert	_MBCS definiert	_UNICODE definiert
_stscanf_s	sscanf_s	sscanf_s	swscanf_s
_stscanf_s_l	_sscanf_s_l	_sscanf_s_l	_swscanf_s_l

Anforderungen

Routine	Erforderlicher Header
sscanf_s, _sscanf_s_l	<stdio.h>
swscanf_s, _swscanf_s_l	<stdio.h> oder <wchar.h>

Zusätzliche Informationen zur Kompatibilität finden Sie unter Kompatibilität.

Beispiel

// crt_sscanf_s.c
// This program uses sscanf_s to read data items
// from a string named tokenstring, then displays them.

#include <stdio.h>
#include <stdlib.h>

int main( void )
{
   char  tokenstring[] = "15 12 14...";
   char  s[81];
   char  c;
   int   i;
   float fp;

   // Input various data from tokenstring:
   // max 80 character string plus NULL terminator
   sscanf_s( tokenstring, "%s", s, _countof(s) );
   sscanf_s( tokenstring, "%c", &c, sizeof(char) );
   sscanf_s( tokenstring, "%d", &i );
   sscanf_s( tokenstring, "%f", &fp );

   // Output the data read
   printf_s( "String    = %s\n", s );
   printf_s( "Character = %c\n", c );
   printf_s( "Integer:  = %d\n", i );
   printf_s( "Real:     = %f\n", fp );
}