scanf, fscanf, sscanf, scanf_s, fscanf_s, sscanf_s

Definiert in Header `<stdio.h>`
int scanf( const char* format, ... );	(1)	(bis C99)
int scanf( const char* restrict format, ... );	(1)		(seit C99)
int fscanf( FILE* stream, const char* format, ... );	(2)	(bis C99)
int fscanf( FILE* restrict stream, const char* restrict format, ... );	(2)		(seit C99)
int sscanf( const char* buffer, const char* format, ... );	(3)	(bis C99)
int sscanf( const char* restrict buffer, const char* restrict format, ... );	(3)		(seit C99)
int scanf_s(const char* restrict format, ...);	(4)	(seit C11)
int fscanf_s(FILE* restrict stream, const char* restrict format, ...);	(5)	(seit C11)
int sscanf_s(const char* restrict buffer, const char* restrict format, ...);	(6)	(seit C11)

Liest Daten aus verschiedenen Quellen, interpretiert sie gemäß format und speichert die Ergebnisse an den angegebenen Speicherorten.

1) liest die Daten von stdin

2) liest die Daten aus dem Dateistrom stream

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

4-6) Wie (1-3), außer dass die Konvertierungsspezifikationen %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, welches 1 sein kann, wenn mit %c in ein einzelnes char gelesen wird) und außer dass die folgenden Fehler zur Laufzeit erkannt werden und die derzeit installierte Constraint-Handler-Funktion aufrufen:

eines der Argumente vom Zeigertyp 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 überschreiten, das für jede dieser Konvertierungsspezifikationen bereitgestellt wurde
optional jeder andere erkennbare Fehler, wie z.B. eine unbekannte Konvertierungsspezifikation

Wie bei allen grenzgeprüften Funktionen sind scanf_s, fscanf_s und sscanf_s nur garantiert verfügbar, wenn __STDC_LIB_EXT1__ durch die Implementierung definiert ist und der Benutzer __STDC_WANT_LIB_EXT1__ auf die ganzzahlige Konstante 1 setzt, bevor er <stdio.h> einbindet.

Parameter

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

Die format-Zeichenkette besteht aus

Nicht-Leerzeichen-Mehrbyte-Zeichen mit Ausnahme von %: 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 isspace in einer Schleife aufgerufen würde). 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) unterdrückendes Zuweisungszeichen *. Wenn diese Option vorhanden ist, weist die Funktion das Ergebnis der Konvertierung keinem empfangenden Argument zu.

(optional) eine ganze Zahl (größer als Null), die die maximale Feldbreite angibt, d.h. die maximale Anzahl von Zeichen, die die Funktion bei der Durchführung 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 ist.

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

Konvertierungs-Formatbezeichner.

Die folgenden Formatbezeichner sind verfügbar:

Konvertierungs bezeichner	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 literalem `%`.	N/V	N/V	N/V	N/V	N/V	N/V	N/V	N/V	N/V
`c`	Entspricht einem Zeichen oder einer Folge von Zeichen. Wenn ein Breitenbezeichner verwendet wird, werden genau width Zeichen gefunden (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.	N/V	N/V	`char*`	`wchar_t*`	N/V	N/V	N/V	N/V	N/V
`s`	Entspricht einer Folge von Nicht-Leerzeichen (einem String). Wenn ein Breitenbezeichner verwendet wird, werden maximal width Zeichen oder bis zum ersten Leerzeichen gefunden, je nachdem, was zuerst eintritt. Speichert immer zusätzlich zu den gefundenen Zeichen ein Nullzeichen (daher muss das Argumentarray Platz für mindestens width+1 Zeichen haben).
`[`set `]`	Entspricht einer nicht-leeren Folge von Zeichen aus der set von Zeichen. Wenn das erste Zeichen der Menge `^` ist, werden alle Zeichen, die nicht in der Menge sind, gefunden. Wenn die Menge mit `]` oder `^]` beginnt, wird das `]`-Zeichen ebenfalls in die Menge aufgenommen. Es ist implementationsdefiniert, ob das Zeichen `-` an nicht-initialer Position im Scanset einen Bereich angeben kann, wie in `[0-9]`. Wenn ein Breitenbezeichner verwendet wird, werden nur bis zu width Zeichen gefunden. Speichert immer zusätzlich zu den gefundenen Zeichen ein Nullzeichen (daher muss das Argumentarray Platz für mindestens width+1 Zeichen haben).
`d`	Entspricht einer Dezimalzahl. Das Format der Zahl ist das gleiche wie von strtol 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*`	N/V
`b` (C23)	Entspricht einer vorzeichenlosen Binärzahl. Das Format der Zahl ist das gleiche wie von strtoul mit dem Wert `2` für das `base`-Argument erwartet.
`i`	Entspricht einer ganzen Zahl. Das Format der Zahl ist das gleiche wie von strtol mit dem Wert `0` für das `base`-Argument erwartet (die Basis wird durch die ersten geparsten Zeichen bestimmt).
`u`	Entspricht einer vorzeichenlosen Dezimalzahl. Das Format der Zahl ist das gleiche wie von strtoul mit dem Wert `10` für das `base`-Argument erwartet.
`o`	Entspricht einer vorzeichenlosen Oktalzahl. Das Format der Zahl ist das gleiche wie von strtoul mit dem Wert `8` für das `base`-Argument erwartet.
`x` `X`	Entspricht einer vorzeichenlosen Hexadezimalzahl. Das Format der Zahl ist das gleiche wie von strtoul 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 Bezeichner den Zuweisungsunterdrückungsoperator definiert hat, ist das Verhalten undefiniert.
`a` (C99) `A` (C99) `e` `E` `f` `F` (C99) `g` `G`	Entspricht einer Gleitkommazahl. Das Format der Zahl ist das gleiche wie von strtof erwartet.	N/V	N/V	`float*`	`double*`	N/V	N/V	N/V	N/V	`long double*`
`p`	Entspricht einer implementationsdefinierten Zeichensequenz, die einen Zeiger definiert. `printf`-Familienfunktionen sollten dieselbe Sequenz mit dem `%p`-Formatbezeichner erzeugen.	N/V	N/V	`void**`	N/V	N/V	N/V	N/V	N/V	N/V
Anmerkungen
Für jeden Konvertierungsbezeichner außer `n` wird die längste Folge von Eingabezeichen, die keine angegebene Feldbreite überschreitet und entweder genau das ist, was der Konvertierungsbezeichner erwartet, oder ein Präfix einer Folge ist, die er erwarten würde, vom Strom verbraucht. 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 Übereinstimmungsfehler auf, es sei denn, Dateiende, ein Kodierungsfehler oder ein Lesefehler hat die Eingabe vom Strom verhindert, in diesem Fall liegt ein Eingabefehler vor. Mit Ausnahme des `%`-Bezeichners wird das Eingabeelement (oder für `%n` die Anzahl der Eingabezeichen) zunächst in einen für den Konvertierungsbezeichner 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 Konvertierungsbezeichner außer `[`, `c` und `n` verbrauchen und verwerfen alle führenden Leerzeichen (bestimmt, als ob isspace aufgerufen würde), bevor sie versuchen, die Eingabe zu parsen. Diese verbrauchten Zeichen zählen nicht zur angegebenen maximalen Feldbreite. Die Konvertierungsbezeichner `lc`, `ls` und `l[` führen eine Mehrbyte-zu-Breitzeichen-Konvertierung durch, als ob mbrtowc mit einem auf Null initialisierten mbstate_t-Objekt aufgerufen würde, bevor das erste Zeichen konvertiert wird. Die Konvertierungsbezeichner `s` und `[` speichern immer den Nullterminator zusätzlich zu den gefundenen 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 fester Breite (int8_t, usw.) sind im Header `<inttypes.h>` definiert (obwohl `SCNdMAX`, `SCNuMAX`, usw. gleichbedeutend mit `%jd`, `%ju`, usw. sind). Nach der Aktion jedes Konvertierungsbezeichners gibt es einen Sequenzpunkt; dies erlaubt das Speichern mehrerer Felder in derselben „Senken“-Variablen. Wenn ein unvollständiger Gleitkommawert geparst wird, der im Exponenten ohne Ziffern endet, wie z.B. das Parsen von `"100er"` mit dem Konvertierungsbezeichner `%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 kehren zurück, um nur `"100"` zu verbrauchen, wobei `"er"` übrig bleibt, z.B. glibc Bug 1765. Wenn eine Konvertierungsspezifikation ungültig ist, ist das Verhalten undefiniert.

Wenn eine Konvertierungsspezifikation ungültig ist, ist das Verhalten undefiniert.

Rückgabewert

1-3) Anzahl der erfolgreich zugewiesenen empfangenden Argumente (die Null sein kann, falls ein Übereinstimmungsfehler aufgetreten ist, bevor das erste empfangende Argument zugewiesen wurde), oder EOF, falls ein Eingabefehler auftritt, bevor das erste empfangende Argument zugewiesen wurde.

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

Komplexität

Nicht garantiert. Insbesondere sind einige Implementierungen von sscanf $O(N)$ , wobei N = strlen(buffer) [1].

Anmerkungen

Da die meisten Konvertierungsbezeichner zuerst alle aufeinanderfolgenden Leerzeichen verbrauchen, wird Code wie

scanf("%d", &a);
scanf("%d", &b);

zwei ganze Zahlen lesen, die in verschiedenen Zeilen eingegeben werden (das zweite %d wird den von der ersten übriggelassenen Zeilenumbruch verbrauchen) oder in derselben Zeile, getrennt durch Leerzeichen oder Tabulatoren (das zweite %d wird die Leerzeichen oder Tabulatoren verbrauchen).

Die Konvertierungsbezeichner, die keine führenden Leerzeichen verbrauchen, wie z.B. %c, können dazu gebracht werden, indem ein Leerzeichen in der Formatzeichenkette verwendet wird:

scanf("%d", &a);
scanf(" %c", &c); // consume all consecutive whitespace after %d, then read a char

Beispiel

Diesen Code ausführen

#define __STDC_WANT_LIB_EXT1__ 1
#include <locale.h>
#include <stddef.h>
#include <stdio.h>

int main(void)
{
    int i, j;
    float x, y;
    char str1[10], str2[4];
    wchar_t warr[2];
    setlocale(LC_ALL, "en_US.utf8");

    char input[] = "25 54.32E-1 Thompson 56789 0123 56ß水";
    /* parse as follows:
       %d: an integer
       %f: a floating-point value
       %9s: a string of at most 9 non-whitespace characters
       %2d: two-digit integer (digits 5 and 6)
       %f:  a floating-point value (digits 7, 8, 9)
       %*d: an integer which isn't stored anywhere
       ' ': all consecutive whitespace
       %3[0-9]: a string of at most 3 decimal digits (digits 5 and 6)
       %2lc: two wide characters, using multibyte to wide conversion  */
    int ret = sscanf(input, "%d%f%9s%2d%f%*d %3[0-9]%2lc",
                     &i, &x, str1, &j, &y, str2, warr);

    printf("Converted %d fields:\n"
           "i = %d\n"
           "x = %f\n"
           "str1 = %s\n"
           "j = %d\n"
           "y = %f\n"
           "str2 = %s\n"
           "warr[0] = U+%x\n"
           "warr[1] = U+%x\n",
           ret, i, x, str1, j, y, str2, warr[0], warr[1]);

#ifdef __STDC_LIB_EXT1__
    int n = sscanf_s(input, "%d%f%s", &i, &x, str1, (rsize_t)sizeof str1);
    // writes 25 to i, 5.432 to x, the 9 bytes "Thompson\0" to str1, and 3 to n.
#endif
}

Mögliche Ausgabe:

Converted 7 fields:
i = 25
x = 5.432000
str1 = Thompson
j = 56
y = 789.000000
str2 = 56
warr[0] = U+df
warr[1] = U+6c34

Referenzen

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

7.21.6.2 Die fscanf-Funktion (S. TBD)

7.21.6.4 Die scanf-Funktion (S. TBD)

7.21.6.7 Die sscanf-Funktion (S. TBD)

K.3.5.3.2 Die fscanf_s-Funktion (S. TBD)

K.3.5.3.4 Die scanf_s-Funktion (S. TBD)

K.3.5.3.7 Die sscanf_s-Funktion (S. TBD)

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

7.21.6.2 Die fscanf-Funktion (S. 231-236)

7.21.6.4 Die scanf-Funktion (S. 236-237)

7.21.6.7 Die sscanf-Funktion (S. 238-239)

K.3.5.3.2 Die fscanf_s-Funktion (S. 430-431)

K.3.5.3.4 Die scanf_s-Funktion (S. 432)

K.3.5.3.7 Die sscanf_s-Funktion (S. 433)

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

7.21.6.2 Die fscanf-Funktion (S. 317-324)

7.21.6.4 Die scanf-Funktion (S. 325)

7.21.6.7 Die sscanf-Funktion (S. 326)

K.3.5.3.2 Die fscanf_s-Funktion (S. 592-593)

K.3.5.3.4 Die scanf_s-Funktion (S. 594)

K.3.5.3.7 Die sscanf_s-Funktion (S. 596)

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

7.19.6.2 Die fscanf-Funktion (S. 282-289)

7.19.6.4 Die scanf-Funktion (S. 290)

7.19.6.7 Die sscanf-Funktion (S. 291)

C89/C90-Standard (ISO/IEC 9899:1990):

4.9.6.2 Die fscanf-Funktion

4.9.6.4 Die scanf-Funktion

4.9.6.6 Die sscanf-Funktion

Siehe auch

vscanfvfscanfvsscanfvscanf_svfscanf_svsscanf_s (C99)(C99)(C99)(C11)(C11)(C11)	liest formatierte Eingabe von stdin, einem Dateistrom oder einem Puffer unter Verwendung einer variablen Argumentliste (Funktion)
fgets	holt eine Zeichenkette aus einem Dateistrom (Funktion)
printffprintfsprintfsnprintfprintf_sfprintf_ssprintf_ssnprintf_s (C99)(C11)(C11)(C11)(C11)	gibt formatierte Ausgabe auf stdout, einen Dateistrom oder einen Puffer aus (Funktion)
C++-Dokumentation für scanf, fscanf, sscanf

Compilerunterstützung
Sprache
Header
Typunterstützung
Programmhilfsmittel
Funktionen mit variabler Argumentanzahl
Fehlerbehandlung
Dynamische Speicherverwaltung
Zeichenkettenbibliothek
Algorithmen
Numerik
Datums- und Zeitfunktionen
Ein‑/Ausgabeunterstützung
Lokalisierungsunterstützung
Nebenläufigkeitsunterstützung (C11)
Technische Spezifikationen
Symbolindex

de.cppreference.net

Namespaces

Variants