wscanf, fwscanf, swscanf, wscanf_s, fwscanf_s, swscanf_s

Definiert in Header `<wchar.h>`
int wscanf( const wchar_t* format, ... );	(1)	(seit C95) (bis C99)
int wscanf( const wchar_t* restrict format, ... );	(1)		(seit C99)
int fwscanf( FILE* stream, const wchar_t* format, ... );	(2)	(seit C95) (bis C99)
int fwscanf( FILE* restrict stream, const wchar_t* restrict format, ... );	(2)		(seit C99)
int swscanf( const wchar_t* buffer, const wchar_t* format, ... );	(3)	(seit C95) (bis C99)
int swscanf( const wchar_t* restrict buffer, const wchar_t* restrict format, ... );	(3)		(seit C99)
int wscanf_s( const wchar_t* restrict format, ...);	(4)	(seit C11)
int fwscanf_s( FILE* restrict stream, const wchar_t* restrict format, ...);	(5)	(seit C11)
int swscanf_s( const wchar_t* restrict s, const wchar_t* restrict format, ...);	(6)	(seit C11)

Liest Daten aus einer Vielzahl von Quellen, interpretiert sie gemäß format und speichert die Ergebnisse an den angegebenen Stellen.

1) Liest die Daten aus stdin.

2) Liest die Daten aus dem Dateistrom stream.

3) Liest die Daten aus der nullterminierten breiten Zeichenkette buffer. Das Erreichen des Endes der Zeichenkette ist gleichbedeutend mit dem Erreichen der Dateiende-Bedingung für fwscanf

.4-6) Wie (1-3), außer dass die Konvertierungsspezifizierer %c, %s und %[ jeweils zwei Argumente erwarten (den üblichen Zeiger und einen Wert vom Typ rsize_t, der die Größe des empfangenden Arrays angibt, welcher 1 sein kann, wenn mit einem %lc in ein einzelnes breites Zeichen gelesen wird) und dass die folgenden Fehler zur Laufzeit erkannt werden und die derzeit installierte Constraint-Handler-Funktion aufrufen:

jedes der Zeiger-Argumente ist ein Nullzeiger
format, stream oder buffer ist ein Nullzeiger
die Anzahl der Zeichen, die durch %c, %s oder %[ geschrieben würden, plus das abschließende Nullzeichen, würde das zweite (rsize_t) Argument für jeden dieser Konvertierungsspezifizierer überschreiten
optional jeder andere erkennbare Fehler, wie unbekannter Konvertierungsspezifizierer

Wie alle grenzgeprüften Funktionen sind wscanf_s, fwscanf_s und swscanf_s nur garantiert verfügbar, wenn __STDC_LIB_EXT1__ von der Implementierung definiert ist und der Benutzer __STDC_WANT_LIB_EXT1__ vor dem Einbinden von 1 auf die ganzzahlige Konstante < setzt.>wchar.h

Parameter

stream	-	Eingabedateistrom, von dem gelesen wird
buffer	-	Zeiger auf eine nullterminierte breite Zeichenkette, aus der gelesen wird
format	-	Zeiger auf eine nullterminierte breite Zeichenkette, die angibt, wie die Eingabe gelesen wird
...	-	Empfangsargumente.

Die format-Zeichenkette besteht aus

Nicht-Leerzeichen-Breitzeichen außer %: Jedes solche Zeichen in der Formatzeichenkette verbraucht genau ein identisches Zeichen aus dem Eingabestrom oder führt dazu, dass die Funktion fehlschlägt, wenn das nächste Zeichen im Strom nicht gleich ist.
Leerzeichen: Jedes einzelne Leerzeichen in der Formatzeichenkette verbraucht alle verfügbaren aufeinanderfolgenden Leerzeichen aus der Eingabe (bestimmt, als ob durch Aufruf von iswspace in einer Schleife). Beachten Sie, dass es keinen Unterschied zwischen "\n", " ", "\t\t" oder anderen Leerzeichen in der Formatzeichenkette gibt.
Konvertierungsspezifikationen. Jede Konvertierungsspezifikation hat das folgende Format:

Einleitendes %-Zeichen.

(optional) Zuweisungsunterdrückungszeichen *. Wenn diese Option vorhanden ist, weist die Funktion das Ergebnis der Konvertierung keinem Empfangsargument zu.

(optional) Ganzzahl (größer als Null), die die maximale Feldbreite angibt, d.h. die maximale Anzahl von Zeichen, die die Funktion bei der durch die aktuelle Konvertierungsspezifikation angegebenen Konvertierung verbrauchen darf. Beachten Sie, dass %s und %[ zu einem Pufferüberlauf führen können, wenn die Breite nicht angegeben wird.

(optional) Längenmodifikator, der die Größe des Empfangsarguments angibt, d.h. den tatsächlichen Zieltyp. Dies beeinflusst die Konvertierungsgenauigkeit und Überlaufregeln. Der Standard-Zieltyp ist für jeden Konvertierungstyp unterschiedlich (siehe Tabelle unten).

Konvertierungsformat-Spezifizierer.

Die folgenden Format-Spezifizierer sind verfügbar:

Konvertierungs spezifizierer	Erklärung	Erwarteter Argumenttyp
Längenmodifikator→		`hh`	`h`	keiner	`l`	`ll`	`j`	`z`	`t`	`L`
Nur seit C99 verfügbar→		Ja				Ja	Ja	Ja	Ja
`%`	Entspricht dem Literal `%`.	Entfällt	Entfällt	Entfällt	Entfällt	Entfällt	Entfällt	Entfällt	Entfällt	Entfällt
`c`	Entspricht einem Zeichen oder einer Folge von Zeichen. Wenn ein Breitenspezifizierer verwendet wird, entspricht dies genau width breiten Zeichen (das Argument muss ein Zeiger auf ein Array mit ausreichend Platz sein). Im Gegensatz zu %s und %[, wird das Nullzeichen nicht an das Array angehängt.	Entfällt	Entfällt	`char*`	`wchar_t*`	Entfällt	Entfällt	Entfällt	Entfällt	Entfällt
`s`	Entspricht einer Folge von Nicht-Leerzeichen (einem String). Wenn ein Breitenspezifizierer verwendet wird, werden bis zu width oder bis zum ersten Leerzeichen, je nachdem, was zuerst auftritt, gematcht. Speichert immer ein Nullzeichen zusätzlich zu den gematchten Zeichen (daher muss das Argumentarray Platz für mindestens width+1 Zeichen haben).
`[`set `]`	Entspricht einer nicht leeren Zeichenfolge aus der Zeichenmenge set. Wenn das erste Zeichen der Menge `^` ist, werden alle Zeichen, die nicht in der Menge sind, gematcht. Wenn die Menge mit `]` oder `^]` beginnt, wird das Zeichen `]` ebenfalls in die Menge aufgenommen. Es ist implementierungsdefiniert, ob das Zeichen `-` an nicht-initialer Position im Scanset einen Bereich angeben kann, wie in `[0-9]`. Wenn ein Breitenspezifizierer verwendet wird, werden nur bis zu width gematcht. Speichert immer ein Nullzeichen zusätzlich zu den gematchten Zeichen (daher muss das Argumentarray Platz für mindestens width+1 Zeichen haben).
`d`	Entspricht einer Dezimalzahl. Das Format der Zahl ist dasselbe wie von wcstol mit dem Wert `10` für das `base`-Argument erwartet.	`signed char` oder `unsigned char`	`signed short` oder `unsigned short`	`signed int` oder `unsigned int`	`signed long` oder `unsigned long`	`signed long long` oder `unsigned long long`	`intmax_t` oder `uintmax_t`	`size_t*`	`ptrdiff_t*`	Entfällt
`b` (C23)	Entspricht einer vorzeichenlosen Binärzahl. Das Format der Zahl ist dasselbe wie von wcstoul mit dem Wert `2` für das `base`-Argument erwartet.
`i`	Entspricht einer Ganzzahl. Das Format der Zahl ist dasselbe wie von wcstol mit dem Wert `0` für das `base`-Argument erwartet (Basis wird durch die ersten geparsten Zeichen bestimmt).
`u`	Entspricht einer vorzeichenlosen Dezimalzahl. Das Format der Zahl ist dasselbe wie von wcstoul mit dem Wert `10` für das `base`-Argument erwartet.
`o`	Entspricht einer vorzeichenlosen Oktalzahl. Das Format der Zahl ist dasselbe wie von wcstoul mit dem Wert `8` für das `base`-Argument erwartet.
`x` `X`	Entspricht einer vorzeichenlosen Hexadezimalzahl. Das Format der Zahl ist dasselbe wie von wcstoul mit dem Wert `16` für das `base`-Argument erwartet.
`n`	Gibt die Anzahl der bisher gelesenen Zeichen zurück. Es wird keine Eingabe verbraucht. Erhöht die Zuweisungsanzahl nicht. Wenn der Spezifizierer einen Zuweisungsunterdrückungsoperator hat, ist das Verhalten undefiniert.
`a` (C99) `A` (C99) `e` `E` `f` `F` (C99) `g` `G`	Entspricht einer Gleitkommazahl. Das Format der Zahl ist dasselbe wie von wcstof erwartet.	Entfällt	Entfällt	`float*`	`double*`	Entfällt	Entfällt	Entfällt	Entfällt	`long double*`
`p`	Entspricht einer implementierungsdefinierten Zeichensequenz, die einen Zeiger definiert. `printf` Die Familie der Funktionen sollte dieselbe Sequenz unter Verwendung des `%p`-Format-Spezifizierers erzeugen.	Entfällt	Entfällt	`void**`	Entfällt	Entfällt	Entfällt	Entfällt	Entfällt	Entfällt
Anmerkungen
Für jeden Konvertierungsspezifizierer außer `n` ist die längste Folge von Eingabezeichen, die keine angegebene Feldbreite überschreitet und die entweder genau das ist, was der Konvertierungsspezifizierer erwartet, oder ein Präfix einer Folge, die er erwarten würde, das, was vom Strom verbraucht wird. Das erste Zeichen, falls vorhanden, nach dieser verbrauchten Folge bleibt ungelesen. Wenn die verbrauchte Folge die Länge Null hat oder wenn die verbrauchte Folge nicht wie oben angegeben konvertiert werden kann, tritt ein Fehler bei der Übereinstimmung auf, es sei denn, das Dateiende, ein Kodierungsfehler oder ein Lesefehler hat die Eingabe vom Strom verhindert. In diesem Fall liegt ein Eingabefehler vor. Außer für den `%`-Spezifizierer wird das Eingabeelement (oder für `%n` die Anzahl der Eingabezeichen) zunächst in einen für den Konvertierungsspezifizierer geeigneten Typ konvertiert. Sofern die Zuweisung nicht mit `*` unterdrückt wurde, wird das Ergebnis der Konvertierung in das Objekt geschrieben, auf das das nächste noch nicht beschriebene Argument zeigt. Wenn dieses Objekt keinen geeigneten Typ hat oder wenn das Ergebnis der Konvertierung nicht im Objekt dargestellt werden kann, ist das Verhalten undefiniert. Alle Konvertierungsspezifizierer außer `[`, `c` und `n` verbrauchen und verwerfen alle führenden Leerzeichen (bestimmt, als ob durch Aufruf von iswspace) bevor sie versuchen, die Eingabe zu parsen. Diese verbrauchten Zeichen zählen nicht zur angegebenen maximalen Feldbreite. Wenn der Längenspezifizierer `l` nicht verwendet wird, führen die Konvertierungsspezifizierer `c`, `s` und `[` eine Breit-zu-Mehrbyte-Zeichenkonvertierung durch, als ob durch Aufruf von wcrtomb mit einem mbstate_t-Objekt, das vor der Konvertierung des ersten Zeichens auf Null initialisiert wurde. Die Konvertierungsspezifizierer `s` und `[` speichern immer den Nullterminator zusätzlich zu den gematchten Zeichen. Die Größe des Zielarrays muss mindestens um eins größer sein als die angegebene Feldbreite. Die Verwendung von `%s` oder `%[` ohne Angabe der Zielarraygröße ist genauso unsicher wie gets. Die korrekten Konvertierungsspezifikationen für die Ganzzahltypen mit fester Breite (int8_t, usw.) sind im Header `<inttypes.h>` definiert (obwohl `SCNdMAX`, `SCNuMAX`, usw. gleichbedeutend mit `%jd`, `%ju`, usw. sind). Es gibt einen Sequenzpunkt nach der Aktion jedes Konvertierungsspezifizierers; dies erlaubt das Speichern mehrerer Felder in derselben "Senken"-Variablen. Beim Parsen eines unvollständigen Gleitkommawerts, der im Exponenten ohne Ziffern endet, wie z.B. das Parsen von `"100er"` mit dem Konvertierungsspezifizierer `%f` wird die Sequenz `"100e"` (das längste Präfix einer möglicherweise gültigen Gleitkommazahl) verbraucht, was zu einem Übereinstimmungsfehler führt (die verbrauchte Sequenz kann nicht in eine Gleitkommazahl konvertiert werden), wobei `"r"` übrig bleibt. Einige vorhandene Implementierungen folgen dieser Regel nicht und machen rückgängig, um nur `"100"` zu verbrauchen, wobei `"er"` übrig bleibt, z.B. glibc Bug 1765. Wenn eine Konvertierungsspezifikation ungültig ist, ist das Verhalten undefiniert.

Rückgabewert

1-3) Anzahl der erfolgreich zugewiesenen Empfangsargumente oder EOF, wenn ein Lesefehler auftritt, bevor das erste Empfangsargument zugewiesen wurde.

4-6) Wie (1-3), außer dass EOF auch zurückgegeben wird, wenn eine Laufzeit-Einschränkungsverletzung vorliegt.

Beispiel

Diesen Code ausführen

#include <stdio.h>
#include <string.h>
#include <wchar.h>

#define NUM_VARS   3
#define ERR_READ   2
#define ERR_WRITE  3

int main(void)
{
    wchar_t state[64];
    wchar_t capital[64];
    unsigned int population = 0;
    int elevation = 0;
    int age = 0;
    float pi = 0;

#if INTERACTIVE_MODE
    wprintf(L"Enter state, age, and pi value: ");
    if (wscanf(L"%ls%d%f", state, &age, &pi) != NUM_VARS)
    {
        fprintf(stderr, "Error reading input.\n");
        return ERR_READ;
    }
#else
    wchar_t* input = L"California 170 3.141592";
    if (swscanf(input, L"%ls%d%f", state, &age, &pi) != NUM_VARS)
    {
        fprintf(stderr, "Error reading input.\n");
        return ERR_READ;
    }
#endif
    wprintf(L"State: %ls\nAge  : %d years\nPi   : %.5f\n\n", state, age, pi);

    FILE* fp = tmpfile();
    if (fp)
    {
        // write some data to temp file
        if (!fwprintf(fp, L"Mississippi Jackson 420000 807"))
        {
            fprintf(stderr, "Error writing to file.\n");
            fclose(fp);
            return ERR_WRITE;
        }
        // rewind file pointer
        rewind(fp);

        // read data into variables
        fwscanf(fp, L"%ls%ls%u%d", state, capital, &population, &elevation);
        wprintf(L"State  : %ls\nCapital: %ls\nJackson population (in 2020): %u\n"
                L"Highest elevation: %dft\n",
                state, capital, population, elevation);
        fclose(fp);
    }
}

Mögliche Ausgabe:

State: California
Age  : 170 years
Pi   : 3.14159

State  : Mississippi
Capital: Jackson
Jackson population (in 2020): 420000
Highest elevation: 807ft

Referenzen

C23-Standard (ISO/IEC 9899:2024):

7.29.2.2 Die fwscanf-Funktion (p: TBD)

7.29.2.4 Die swscanf-Funktion (p: TBD)

7.29.2.12 Die wscanf-Funktion (p: TBD)

K.3.9.1.2 Die fwscanf_s-Funktion (p: TBD)

K.3.9.1.5 Die swscanf_s-Funktion (p: TBD)

K.3.9.1.14 Die wscanf_s-Funktion (p: TBD)

C17-Standard (ISO/IEC 9899:2018):

7.29.2.2 Die fwscanf-Funktion (p: TBD)

7.29.2.4 Die swscanf-Funktion (p: TBD)

7.29.2.12 Die wscanf-Funktion (p: TBD)

K.3.9.1.2 Die fwscanf_s-Funktion (p: TBD)

K.3.9.1.5 Die swscanf_s-Funktion (p: TBD)

K.3.9.1.14 Die wscanf_s-Funktion (p: TBD)

C11-Standard (ISO/IEC 9899:2011):

7.29.2.2 Die fwscanf-Funktion (p: 410-416)

7.29.2.4 Die swscanf-Funktion (p: 417)

7.29.2.12 Die wscanf-Funktion (p: 421)

K.3.9.1.2 Die fwscanf_s-Funktion (p: 628-629)

K.3.9.1.5 Die swscanf_s-Funktion (p: 631)

K.3.9.1.14 Die wscanf_s-Funktion (p: 638)

C99-Standard (ISO/IEC 9899:1999):

7.24.2.2 Die fwscanf-Funktion (p: 356-362)

7.24.2.4 Die swscanf-Funktion (p: 362)

7.24.2.12 Die wscanf-Funktion (p: 366-367)

Siehe auch

vwscanfvfwscanfvswscanfvwscanf_svfwscanf_svswscanf_s (C99)(C99)(C99)(C11)(C11)(C11)	liest formatierte breite Zeicheneingabe von stdin, einem Dateistrom oder einem Puffer unter Verwendung einer variablen Argumentliste (Funktion)
C++-Dokumentation für wscanf, fwscanf, swscanf

Compilerunterstützung
Sprache
Header
Typunterstützung
Programmhilfsprogramme
Unterstützung variadischer Funktionen
Fehlerbehandlung
Dynamische Speicherverwaltung
Stringbibliothek
Algorithmen
Numerik
Datum und Zeit Hilfsprogramme
Ein-/Ausgabeunterstützung
Lokalisierungsunterstützung
Nebenläufigkeitsunterstützung (C11)
Technische Spezifikationen
Symbolindex

de.cppreference.net

Namespaces

Variants