scanf, fscanf, sscanf, scanf_s, fscanf_s, sscanf_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 <stdio.h>
	(1)
int scanf( const char          *format, ... );			(bis C99)
int scanf( const char *restrict format, ... );			(seit C99)
		(2)
int fscanf( FILE          *stream, const char          *format, ... );				(bis C99)
int fscanf( FILE *restrict stream, const char *restrict format, ... );				(seit C99)
			(3)
int sscanf( const char          *buffer, const char          *format, ... );					(bis C99)
int sscanf( const char *restrict buffer, const char *restrict format, ... );					(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 einer Vielzahl von Quellen, interpretiert sie gemäß format und speichert die Ergebnisse an gegebenen Speicherorten.

1) liest Daten aus stdin

2) liest Daten aus dem Dateistream stream

3) liest Daten aus dem nullterminierten Zeichenstring buffer. Das Erreichen des Endes des Strings ist äquivalent zum Erreichen der End-of-File-Bedingung für fscanf.

4-6) Wie (1-3), außer dass die Konversionsspezifizierer %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, was 1 sein kann, wenn mit %c in ein einzelnes Zeichen gelesen wird) und außer dass 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, plus das abschließende Nullzeichen, das zweite Argument (rsize_t), das für jeden dieser Konversionsspezifizierer bereitgestellt wurde, überschreitet.
• Optional, jeder andere erkennbare Fehler, wie z.B. ein unbekannter Konvertierungsspezifizierer.

Wie bei allen bounds-geprüften Funktionen sind scanf_s, fscanf_s und sscanf_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 <stdio.h> auf die Ganzzahlkonstante 1 setzt.

Parameter

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

Der Formatstring besteht aus

• Nicht-Whitespace-Multibyte-Zeichen außer %: Jedes solche Zeichen in der Formatzeichenkette verbraucht genau ein identisches Zeichen aus dem Eingabestrom oder führt zum Fehlschlagen der Funktion, wenn das nächste Zeichen im Strom nicht übereinstimmt.
• Whitespace-Zeichen: Jedes einzelne Whitespace-Zeichen in der Formatzeichenkette verbraucht alle aufeinanderfolgenden verfügbaren Whitespace-Zeichen aus der Eingabe (ermittelt, als ob isspace in einer Schleife aufgerufen worden wäre). Beachten Sie, dass es keinen Unterschied zwischen "\n", " ", "\t\t" oder anderem Whitespace 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 Breitenangabe verwendet wird, werden genau Breite 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, wie es von strtol mit dem Wert 10 für das Argument base 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, wie es von strtol mit dem Wert ​0​ für das Argument base erwartet wird (die Basis wird durch die ersten gelesenen Zeichen bestimmt).
u	Entspricht einer vorzeichenlosen Dezimalganzzahl. Das Format der Zahl ist dasselbe, wie es von strtoul mit dem Wert 10 für das Argument base erwartet wird.
o	Entspricht einer vorzeichenlosen Oktalganzzahl. Das Format der Zahl ist dasselbe, wie es von strtoul mit dem Wert 8 für das Argument base erwartet wird.
x X	Entspricht einer vorzeichenlosen Hexadezimalganzzahl. Das Format der Zahl ist dasselbe, wie es von strtoul mit dem Wert 16 für das Argument base 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, wie es von strtof 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 Konversionsspezifizierer außer [, c und n verbrauchen und verwerfen alle aufeinanderfolgenden Whitespace-Zeichen (ermittelt, als ob isspace aufgerufen worden wäre), bevor versucht wird, die Eingabe zu parsen. Diese verbrauchten Zeichen zählen nicht zur angegebenen maximalen Feldbreite. Die Konversionsspezifizierer lc, ls und l[ führen eine Multibyte-zu-Wide-Character-Konvertierung durch, als ob mbrtowc mit einem mbstate_t-Objekt, das vor der Konvertierung des ersten Zeichens auf Null initialisiert wurde, aufgerufen worden wäre. 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 Gleitkommawerts, der mit einem Exponenten ohne Ziffern endet, z. B. beim Parsen von "100er" mit dem Konversionsspezifizierer %f, wird die Sequenz "100e" (der längste Präfix einer möglicherweise gültigen Gleitkommazahl) verbraucht, was zu einem Abgleichfehler führt (die verbrauchte Sequenz kann nicht in eine Gleitkommazahl 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.

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

Rückgabewert

1-3) Anzahl der erfolgreich zugewiesenen Empfängerargumente (die null sein kann, falls ein Abgleichfehler auftrat, bevor das erste Empfängerargument zugewiesen wurde), oder EOF, wenn ein Eingabefehler 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.

Komplexität

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

Hinweise

Da die meisten Konversionsspezifizierer zuerst alle aufeinanderfolgenden Whitespace-Zeichen verbrauchen, liest Code wie

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

zwei ganze Zahlen ein, die in verschiedenen Zeilen eingegeben werden (der zweite %d verbraucht den von der ersten übrig gebliebenen Zeilenumbruch) oder in derselben Zeile, getrennt durch Leerzeichen oder Tabs (der zweite %d verbraucht die Leerzeichen oder Tabs).

Die Konversionsspezifizierer, die keine führenden Whitespace-Zeichen verbrauchen, wie z. B. %c, können dazu gebracht werden, dies zu tun, indem ein Whitespace-Zeichen in der Formatzeichenkette verwendet wird.

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

Beispiel

Führen Sie diesen Code aus

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
#include <stddef.h>
#include <locale.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

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

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

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

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

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

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

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

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

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

• 7.21.6.4 Die Funktion scanf (S. 325)

• 7.21.6.7 Die Funktion sscanf (S. 326)

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

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

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

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

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

• 7.19.6.4 Die Funktion scanf (S. 290)

• 7.19.6.7 Die Funktion sscanf (S. 291)

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

• 4.9.6.2 Die Funktion fscanf

• 4.9.6.4 Die Funktion scanf

• 4.9.6.6 Die Funktion sscanf

Siehe auch

vscanfvfscanfvsscanfvscanf_svfscanf_svsscanf_s (C99)(C99)(C99)(C11)(C11)(C11)	liest formatierte Eingaben aus stdin, einem Dateistream oder einem Puffer mit variabler Argumentenliste (Funktion)
fgets	liest einen Zeichenstring aus einem Dateistream (Funktion)
printffprintfsprintfsnprintfprintf_sfprintf_ssprintf_ssnprintf_s (C99)(C11)(C11)(C11)(C11)	gibt formatierte Ausgaben nach stdout, an einen Dateistream oder in einen Puffer aus (Funktion)
C++-Dokumentation für scanf, fscanf, sscanf