wscanf, fwscanf, swscanf, wscanf_s, fwscanf_s, swscanf_s

 

C

Compiler-Unterstützung

Sprache

Header

Typunterstützung

Programm-Dienstprogramme

Unterstützung für variable Funktionsargumente

Fehlerbehandlung

Dynamische Speicherverwaltung

Bibliothek für Zeichenketten

Algorithmen

Numerik

Datums- und Zeitdienstprogramme

Ein-/Ausgabeunterstützung

Lokalisierungsunterstützung

Unterstützung für Nebenläufigkeit (C11)

Technische Spezifikationen

Symbolindex

 

Datei-Ein-/Ausgabe

Typen und Objekte
stdinstdoutstderr          FILE fpos_t
Funktionen Datei-Zugriff fopenfopen_s (C11) freopenfreopen_s (C11)   fwide (C95) setbuf setvbuf fclose fflush Unformatierte Ein-/Ausgabe fgetc fgets fputc fputs getchar getsgets_s (bis C11)(C11) putchar puts ungetc fgetwcgetwc (C95)(C95) fgetws (C95) fputwcputwc (C95)(C95) fputws (C95) getwchar (C95) putwchar (C95) ungetwc (C95) Formatierte Eingabe scanffscanfsscanfscanf_sfscanf_ssscanf_s (C11)(C11)(C11) wscanffwscanfswscanfwscanf_sfwscanf_sswscanf_s (C95)(C95)(C95)(C11)(C11)(C11) vscanfvfscanfvsscanfvscanf_svfscanf_svsscanf_s (C99)(C99)(C99)(C11)(C11)(C11) vwscanfvfwscanfvswscanfvwscanf_svfwscanf_svswscanf_s (C99)(C99)(C99)(C11)(C11)(C11)	Direkte Ein-/Ausgabe fread fwrite Formatierte Ausgabe printffprintfsprintfsnprintfprintf_sfprintf_ssprintf_ssnprintf_s (C99)(C11)(C11)(C11)(C11) wprintffwprintfswprintfwprintf_sfwprintf_sswprintf_ssnwprintf_s (C95)(C95)(C95)(C11)(C11)(C11)(C11)   vprintfvfprintfvsprintfvsnprintfvprintf_svfprintf_svsprintf_svsnprintf_s (C99)(C11)(C11)(C11)(C11) vwprintfvfwprintfvswprintfvwprintf_svfwprintf_svswprintf_svsnwprintf_s (C95)(C95)(C95)(C11)(C11)(C11)(C11) Dateipositionierung ftell fgetpos fseek fsetpos rewind Fehlerbehandlung clearerr feof ferror perror Operationen auf Dateien remove tmpfiletmpfile_s (C11) rename tmpnamtmpnam_s (C11)

 

Definiert in Header <wchar.h>
	(1)
int wscanf( const wchar_t *format, ... );			(seit C95) (bis C99)
int wscanf( const wchar_t *restrict format, ... );			(seit C99)
		(2)
int fwscanf( FILE *stream, const wchar_t *format, ... );				(seit C95) (bis C99)
int fwscanf( FILE *restrict stream,              const wchar_t *restrict format, ... );				(seit C99)
			(3)
int swscanf( const wchar_t *buffer, const wchar_t *format, ... );					(seit C95) (bis C99)
int swscanf( const wchar_t *restrict buffer,              const wchar_t *restrict format, ... );					(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 Orten.

1) Liest die Daten von stdin.

2) Liest die Daten aus dem Dateistream stream.

3) Liest die Daten aus dem nullterminierten Wide-String buffer. Das Erreichen des Endes des Strings ist äquivalent zum Erreichen der End-of-File-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, der 1 sein kann, wenn mit %lc in ein einzelnes Wide-Zeichen gelesen wird) und die folgenden Fehler zur Laufzeit erkannt werden und die aktuell installierte Constraint-Handler-Funktion aufrufen.

• Einer der Zeigerargumente ist ein Nullzeiger.
• format, stream oder buffer ist ein Nullzeiger.
• Die Anzahl der Zeichen, die von %c, %s oder %[ geschrieben würden, zuzüglich des abschließenden Nullzeichens, würde das zweite (rsize_t) Argument überschreiten, das für jeden dieser Konvertierungsspezifizierer bereitgestellt wird.
• Optional, jeder andere erkennbare Fehler, wie z.B. ein unbekannter Konvertierungsspezifizierer.

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

Parameter

stream	-	Eingabedateistream, aus dem gelesen werden soll.
buffer	-	Zeiger auf einen nullterminierten Wide-String, aus dem gelesen werden soll.
format	-	Zeiger auf einen nullterminierten Wide-String, der angibt, wie die Eingabe gelesen werden soll.
...	-	empfangende Argumente.

Der Formatstring besteht aus

• Nicht-Leerzeichen-Wide-Zeichen 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 übereinstimmt.
• Leerzeichen: Jedes einzelne Leerzeichen in der Formatzeichenkette verbraucht alle aufeinanderfolgenden Leerzeichen aus der Eingabe (ermittelt, 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:

• Einführendes % Zeichen.

• (optional) Zuweisungsunterdrückendes Zeichen *. Wenn diese Option vorhanden ist, weist die Funktion das Ergebnis der Konvertierung keinem Empfängerargument zu.

• (optional) Ganze Zahl (größer als Null), die die maximale Feldbreite angibt, d.h. die maximale Anzahl von Zeichen, die die Funktion bei der Konvertierung gemäß der aktuellen Konvertierungsspezifikation verbrauchen darf. Beachten Sie, dass %s und %[ zu Pufferüberläufen führen können, wenn die Breite nicht angegeben ist.

• (optional) Längenmodifikator, der die Größe des Empfängerarguments angibt, d.h. den tatsächlichen Zieltyp. Dies wirkt sich auf die Genauigkeit der Konvertierung und die Überlaufregeln aus. Der Standard-Zieltyp ist für jeden Konvertierungstyp unterschiedlich (siehe Tabelle unten).

• Ein Konversionsformat-Spezifizierer.

Die folgenden Format-Spezifizierer sind verfügbar:

Konversion Spezifizierer	Erklärung	Erwartet Argumenttyp
Längenmodifikator →		hh	h	keine	l	ll	j	z	t	L
Nur verfügbar seit C99 →		Ja				Ja	Ja	Ja	Ja
%	Entspricht dem literalen %.	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A
c	Entspricht einem Zeichen oder einer Sequenz von Zeichen. Wenn ein Breiten-Spezifizierer verwendet wird, werden genau Breite Wide-Zeichen abgeglichen (das Argument muss ein Zeiger auf ein Array mit ausreichend Platz sein). Im Gegensatz zu %s und %[ wird kein Nullzeichen an das Array angehängt.	N/A	N/A	char*	wchar_t*	N/A	N/A	N/A	N/A	N/A
s	Entspricht einer Sequenz von Nicht-Whitespace-Zeichen (einem String). Wenn ein Breiten-Spezifizierer verwendet wird, werden bis zu Breite oder bis zum ersten Whitespace-Zeichen abgeglichen, je nachdem, was zuerst eintritt. Speichert immer ein Nullzeichen zusätzlich zu den abgeglichenen Zeichen (daher muss das Argumentarray Platz für mindestens Breite+1 Zeichen haben).
[set ]	Entspricht einer nicht-leeren Sequenz von Zeichen aus set von Zeichen. Wenn das erste Zeichen des Sets ^ ist, werden alle Zeichen, die nicht im Set enthalten sind, abgeglichen. Wenn das Set mit ] oder ^] beginnt, wird das Zeichen ] ebenfalls in das Set aufgenommen. Es ist implementierungsabhängig, ob das Zeichen - in nicht-initialer Position im Scanset einen Bereich angibt, wie in [0-9]. Wenn ein Breiten-Spezifizierer verwendet wird, werden nur bis zu Breite abgeglichen. Speichert immer ein Nullzeichen zusätzlich zu den abgeglichenen Zeichen (daher muss das Argumentarray Platz für mindestens Breite+1 Zeichen haben).
d	Entspricht einer Dezimalganzzahl. Das Format der Zahl ist dasselbe, das von wcstol mit dem Wert 10 für das base-Argument erwartet wird.	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*	N/A
i	Entspricht einer Ganzzahl. Das Format der Zahl ist dasselbe, das von wcstol mit dem Wert ​0​ für das base-Argument erwartet wird (die Basis wird durch die ersten geparsten Zeichen bestimmt).
u	Entspricht einer vorzeichenlosen Dezimalganzzahl. Das Format der Zahl ist dasselbe, das von wcstoul mit dem Wert 10 für das base-Argument erwartet wird.
o	Entspricht einer vorzeichenlosen Oktalganzzahl. Das Format der Zahl ist dasselbe, das von wcstoul mit dem Wert 8 für das base-Argument erwartet wird.
x X	Entspricht einer vorzeichenlosen Hexadezimalganzzahl. Das Format der Zahl ist dasselbe, das von wcstoul mit dem Wert 16 für das base-Argument erwartet wird.
n	Gibt die bisher gelesene Anzahl von Zeichen zurück. Es werden keine Eingaben verbraucht. Erhöht die Zählung der Zuweisungen nicht. Wenn der Spezifizierer den Operator zur Unterdrückung von Zuweisungen aufweist, ist das Verhalten undefiniert.
a (C99) A (C99) e E f F (C99) g G	Entspricht einer Gleitkommazahl. Das Format der Zahl ist dasselbe, das von wcstof erwartet wird.	N/A	N/A	float*	double*	N/A	N/A	N/A	N/A	long double*
p	Entspricht einer implementierungsdefinierten Zeichensequenz, die einen Zeiger definiert. Die `printf`-Funktionsfamilie sollte mit dem Format-Spezifizierer `%p` die gleiche Sequenz erzeugen.	N/A	N/A	void**	N/A	N/A	N/A	N/A	N/A	N/A
Anmerkungen
Für jeden Konvertierungsspezifizierer außer n ist die längste Sequenz von Eingabezeichen, die keine vorgegebene Feldbreite überschreitet und entweder genau dem entspricht, was der Konvertierungsspezifizierer erwartet, oder ein Präfix einer Sequenz ist, die er erwarten würde, das, was aus dem Strom verbraucht wird. Das erste Zeichen, falls vorhanden, nach dieser verbrauchten Sequenz bleibt ungelesen. Wenn die verbrauchte Sequenz die Länge Null hat oder wenn die verbrauchte Sequenz nicht wie oben spezifiziert konvertiert werden kann, tritt ein Abgleichfehler auf, es sei denn, das Ende der Datei, ein Kodierungsfehler oder ein Lesefehler hat die Eingabe aus dem Strom verhindert, in welchem Fall es ein Eingabefehler ist. Alle Konvertierungsspezifizierer außer [, c und n verbrauchen und verwerfen alle führenden Leerzeichen (ermittelt, als ob durch Aufruf von iswspace), bevor versucht wird, 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 Wide-to-Multibyte-Zeichenkonvertierung durch, als ob wcrtomb mit einem mbstate_t-Objekt, das vor der Konvertierung des ersten Zeichens auf Null initialisiert wurde, aufgerufen würde. Die Konvertierungsspezifizierer s und [ speichern immer den Nullterminator zusätzlich zu den abgeglichenen Zeichen. Die Größe des Zielarrays muss mindestens 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 Konvertierungsspezifizierer für die Integer-Typen mit fester Breite (int8_t, etc.) sind in der Headerdatei <inttypes.h> definiert (obwohl SCNdMAX, SCNuMAX, etc. synonym mit %jd, %ju, etc. sind). Es gibt einen Sequenzpunkt nach der Ausführung jedes Konvertierungsspezifizierers; dies erlaubt das Speichern mehrerer Felder in derselben "Senken"-Variablen. Beim Parsen eines unvollständigen Fließkommawertes, der mit dem Exponenten ohne Ziffern endet, wie z. B. beim Parsen von "100er" mit dem Konvertierungsspezifizierer %f, wird die Sequenz "100e" (der längste Präfix einer möglicherweise gültigen Fließkommazahl) verbraucht, was zu einem Übereinstimmungsfehler führt (die verbrauchte Sequenz kann nicht in eine Fließkommazahl konvertiert werden), wobei "r" übrig bleibt. Einige bestehende Implementierungen folgen dieser Regel nicht und rollen zurück, um nur "100" zu verbrauchen und lassen "er" übrig, z. B. glibc bug 1765. Wenn eine Konversionsspezifikation ungültig ist, ist das Verhalten undefiniert.

Rückgabewert

1-3) Anzahl der erfolgreich zugewiesenen Empfängerargumente oder EOF, wenn ein Lesefehler auftritt, bevor das erste Empfängerargument zugewiesen wurde.

4-6) Identisch mit (1-3), außer dass EOF auch zurückgegeben wird, wenn eine Laufzeit-Constraint-Verletzung vorliegt.

Beispiel

Führen Sie diesen Code aus

#include <stdio.h>
#include <wchar.h>
#include <string.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

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

• 7.29.2.2 The fwscanf function (S. 410-416)

• 7.29.2.4 The swscanf function (S. 417)

• 7.29.2.12 The wscanf function (S. 421)

• K.3.9.1.2 The fwscanf_s function (S. 628-629)

• K.3.9.1.5 The swscanf_s function (S. 631)

• K.3.9.1.14 The wscanf_s function (S. 638)

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

• 7.24.2.2 The fwscanf function (S. 356-362)

• 7.24.2.4 The swscanf function (S. 362)

• 7.24.2.12 The wscanf function (S. 366-367)

Siehe auch

vwscanfvfwscanfvswscanfvwscanf_svfwscanf_svswscanf_s (C99)(C99)(C99)(C11)(C11)(C11)	liest formatierte Wide-Character-Eingaben von stdin, einem Dateistrom oder einem Puffer mit variabler Argumentenliste (Funktion)
C++ Dokumentation für wscanf, fwscanf, swscanf