Namespaces
Variants

scanf, fscanf, sscanf, scanf_s, fscanf_s, sscanf_s

From cppreference.net
< c ‎ | io
C
File input/output
Types and objects
Functions
File access
Unformatted input/output
Formatted input
scanf fscanf sscanf scanf_s fscanf_s sscanf_s
(C11) (C11) (C11)
(C95) (C95) (C95) (C11) (C11) (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 verschiedenen Quellen, interpretiert sie gemäß format und speichert die Ergebnisse an vorgegebenen Speicherorten.

1) liest die Daten von stdin
2) liest die Daten aus dem Dateistrom stream
3) liest die Daten aus der nullterminierten Zeichenkette buffer . Das Erreichen des Endes der Zeichenkette entspricht dem Erreichen der Dateiende-Bedingung für fscanf
4-6) Gleich wie (1-3) , außer dass % c , % s und % [ Konvertierungsspezifizierer jeweils zwei Argumente erwarten (den üblichen Zeiger und einen Wert vom Typ rsize_t , der die Größe des Empfangsarrays angibt, die 1 sein kann beim Lesen mit % c in ein einzelnes char) und außer dass die folgenden Fehler zur Laufzeit erkannt werden und die aktuell 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, das zweite ( rsize_t ) Argument überschreiten würden, das für jeden dieser Konvertierungsspezifizierer bereitgestellt wird
  • optional jeder andere erkennbare Fehler, wie unbekannter Konvertierungsspezifizierer
Wie bei allen grenzprüfenden Funktionen sind scanf_s , fscanf_s und sscanf_s nur garantiert verfügbar, wenn __STDC_LIB_EXT1__ durch die Implementierung definiert ist und wenn der Benutzer __STDC_WANT_LIB_EXT1__ auf die Integer-Konstante 1 setzt, bevor <stdio.h> eingebunden wird.

Inhaltsverzeichnis

Parameter

stream - Eingabedateistream zum Lesen
buffer - Zeiger auf einen nullterminierten Zeichenstring zum Lesen
format - Zeiger auf einen nullterminierten Zeichenstring, der die Eingabeart spezifiziert
... - Empfangende Argumente.


Die Format -Zeichenkette besteht aus

  • Nicht-Leerzeichen-Mehrbytezeichen außer % : Jedes solche Zeichen im Formatstring konsumiert genau ein identisches Zeichen aus dem Eingabestrom oder führt zum Fehlschlagen der Funktion, falls das nächste Zeichen im Strom nicht gleich ist.
  • Leerzeichenzeichen: Jedes einzelne Leerzeichenzeichen im Formatstring konsumiert alle verfügbaren aufeinanderfolgenden Leerzeichenzeichen aus der Eingabe (bestimmt wie durch wiederholten Aufruf von isspace ). Beachten Sie, dass es keinen Unterschied zwischen " \n " , " " , " \t \t " oder anderen Leerzeichen im Formatstring gibt.
  • Konvertierungsspezifikationen. Jede Konvertierungsspezifikation hat folgendes Format:
  • Einleitendes % Zeichen.
  • (optional) unterdrückendes Zuweisungszeichen * . Wenn diese Option vorhanden ist, weist die Funktion das Ergebnis der Konvertierung keinem empfangenden Argument zu.
  • (optional) Ganzzahl (größer als Null), die die maximale Feldbreite angibt, also die maximale Anzahl von Zeichen, die die Funktion bei der Durchführung der durch die aktuelle Konvertierungsspezifikation angegebenen Konvertierung verarbeiten 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 empfangenden Arguments angibt, also den eigentlichen Zieltyp. Dies beeinflusst die Konvertierungsgenauigkeit und Überlaufregeln. Der Standardzieltyp ist für jeden Konvertierungstyp unterschiedlich (siehe Tabelle unten).
  • Konvertierungsformat-Spezifizierer.

Die folgenden Formatbezeichner sind verfügbar:

Konvertierungsspezifizierer
Erklärung Erwarteter
Argumenttyp
Längenmodifikator→ hh h keine l ll j z t L
Nur verfügbar seit C99→ Ja Ja Ja Ja Ja
%
Entspricht dem Literal % .
N/A N/A N/A N/A N/A N/A N/A N/A N/A
c

Entspricht einem Zeichen oder einer Folge von Zeichen .

  • Bei Verwendung eines Breiten-Spezifizierers werden exakt Breite Zeichen gematcht (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 Folge von Nicht-Leerzeichen (einem String ).

  • Wenn ein Breitenbezeichner verwendet wird, entspricht es bis zu width oder bis zum ersten Leerzeichen, je nachdem, was zuerst auftritt.
  • Speichert immer ein Nullzeichen zusätzlich zu den übereinstimmenden Zeichen (daher muss das Argument-Array Platz für mindestens width+1 Zeichen haben).
[ set  ]

Stimmt mit einer nicht-leeren Zeichenfolge aus dem set von Zeichen überein.

  • Wenn das erste Zeichen des Sets ^ ist, werden alle Zeichen außerhalb des Sets gematcht.
  • Wenn das Set mit ] oder ^] beginnt, wird das ] -Zeichen ebenfalls in das Set aufgenommen.
  • Es ist implementierungsdefiniert, ob das Zeichen - an einer nicht-initialen Position im Scanset einen Bereich angeben kann, wie in [0-9] .
  • Wenn eine Breitenangabe verwendet wird, werden nur bis zu width Zeichen gematcht.
  • Speichert immer ein Nullzeichen zusätzlich zu den gematchten Zeichen (daher muss das Argument-Array Platz für mindestens width+1 Zeichen haben).
d

Passt auf eine dezimale Ganzzahl .

  • Das Zahlenformat entspricht dem von strtol mit dem Wert 10 für das base Argument.
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 *
N/A
i

Erkennt eine Ganzzahl .

  • Das Zahlenformat entspricht dem von strtol mit dem Wert ​ 0 ​ für das base Argument (die Basis wird durch die ersten eingelesenen Zeichen bestimmt).
u

Entspricht einer vorzeichenlosen Dezimalzahl .

  • Das Zahlenformat ist identisch mit dem von strtoul erwarteten Format mit dem Wert 10 für das base Argument.
o

Entspricht einer vorzeichenlosen Oktalzahl .

  • Das Zahlenformat ist identisch mit dem von strtoul erwarteten Format mit dem Wert 8 für das base Argument.
x
X

Entspricht einem vorzeichenlosen hexadezimalen Integer .

  • Das Zahlenformat ist identisch mit dem von strtoul erwarteten Format mit dem Wert 16 für das base Argument.
n

Gibt die Anzahl der bisher gelesenen Zeichen zurück.

  • Es wird keine Eingabe konsumiert. Erhöht nicht die Zuweisungsanzahl.
  • Wenn der Format-Spezifizierer den Zuweisungsunterdrückungsoperator definiert hat, ist das Verhalten undefiniert.
a (C99)
A (C99)
e
E
f
F (C99)
g
G

Erkennt eine Gleitkommazahl .

  • Das Zahlenformat entspricht dem von strtof erwarteten Format.
N/A N/A
float *
double *
N/A N/A N/A N/A
long double *
p

Entspricht der implementierungsdefinierten Zeichensequenz, die einen Zeiger definiert.

  • printf -Funktionsfamilie sollte dieselbe Sequenz unter Verwendung des %p -Formatbezeichners erzeugen.
N/A N/A
void **
N/A N/A N/A N/A N/A N/A
Hinweise

Für jeden Konvertierungsspezifizierer außer n wird die längste Folge von Eingabezeichen, die keine spezifizierte Feldbreite überschreitet und die entweder genau dem entspricht, was der Konvertierungsspezifizierer erwartet, oder ein Präfix einer solchen Sequenz ist, aus dem Strom gelesen. Das erste Zeichen nach dieser gelesenen Sequenz bleibt ungelesen. Wenn die gelesene Sequenz die Länge null hat oder nicht wie oben spezifiziert konvertiert werden kann, tritt ein Übereinstimmungsfehler auf, es sei denn, Dateiende, ein Kodierungsfehler oder ein Lesefehler verhinderten die Eingabe aus dem Strom, in welchem Fall es sich um einen Eingabefehler handelt.

Alle Konvertierungsspezifizierer außer [ , c und n lesen und verwerfen alle führenden Leerzeichen (bestimmt wie durch Aufruf von isspace ), bevor sie versuchen, die Eingabe zu parsen. Diese gelesenen Zeichen zählen nicht zur spezifizierten maximalen Feldbreite.

Die Konvertierungsspezifizierer lc , ls und l [ führen eine Multibyte-zu-Breitzeichen-Konvertierung durch, als ob sie mbrtowc mit einem mbstate_t -Objekt aufrufen würden, das vor der Konvertierung des ersten Zeichens auf null initialisiert wurde.

Die Konvertierungsspezifizierer s und [ speichern immer den Nullterminator zusätzlich zu den übereinstimmenden Zeichen. Die Größe des Zielarrays muss mindestens um eins größer sein als die spezifizierte Feldbreite. Die Verwendung von % s oder % [ ohne Angabe der Zielarraygröße ist genauso unsicher wie gets .

Die korrekten Konvertierungsspezifikationen für die Festbreiten-Ganzzahltypen ( int8_t usw.) sind im Header <inttypes.h> definiert (obwohl SCNdMAX , SCNuMAX usw. synonym mit % jd , % ju usw. ist).

Es gibt einen Sequenzpunkt nach der Aktion jedes Konvertierungsspezifizierers; dies ermöglicht das Speichern mehrerer Felder in derselben "Senken"-Variable.

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) gelesen, was zu einem Übereinstimmungsfehler führt (die gelesene Sequenz kann nicht in eine Gleitkommazahl konvertiert werden), wobei "r" übrig bleibt. Einige bestehende Implementierungen befolgen diese Regel nicht und rollen zurück, um nur "100" zu lesen, 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 (was null sein kann, falls ein Übereinstimmungsfehler auftrat, bevor das erste empfangende Argument zugewiesen wurde), oder EOF falls ein Eingabefehler auftritt, bevor das erste empfangende Argument zugewiesen wurde.
4-6) Gleich wie (1-3) , außer dass EOF auch zurückgegeben wird, falls eine Runtime Constraint-Verletzung auftritt.

Komplexität

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

Hinweise

Da die meisten Konvertierungsspezifizierer zunächst allen aufeinanderfolgenden Leerraum verarbeiten, Code wie 

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

wird zwei Ganzzahlen lesen, die in verschiedenen Zeilen eingegeben werden (das zweite % d verarbeitet den von der ersten Eingabe übrig gebliebenen Zeilenumbruch) oder in derselben Zeile, getrennt durch Leerzeichen oder Tabs (das zweite % d verarbeitet die Leerzeichen oder Tabs).

The conversion specifiers that do not consume leading whitespace, such as % c , can be made to do so by using a whitespace character in the format string: 
scanf("%d", &a);
scanf(" %c", &c); // alle aufeinanderfolgenden Leerzeichen nach %d verarbeiten, dann ein Zeichen lesen

Beispiel

Diesen Code ausführen 
#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 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

(C99) (C99) (C99) (C11) (C11) (C11)
Liest formatierten Input von stdin , einem Dateistrom oder einem Puffer
unter Verwendung einer variablen Argumentenliste
(Funktion)
Liest eine Zeichenkette von einem Dateistrom
(Funktion)
(C99) (C11) (C11) (C11) (C11)
Schreibt formatierten Output nach stdout , einem Dateistrom oder einem Puffer
(Funktion)
C++-Dokumentation für scanf , fscanf , sscanf