vscanf, vfscanf, vsscanf, vscanf_s, vfscanf_s, vsscanf_s

Deklariert im Header `<stdio.h>`
int vscanf( const char* restrict format, va_list vlist );	(1)	(seit C99)
int vfscanf( FILE* restrict stream, const char* restrict format, va_list vlist );	(2)	(seit C99)
int vsscanf( const char* restrict buffer, const char* restrict format, va_list vlist );	(3)	(seit C99)
int vscanf_s(const char* restrict format, va_list vlist);	(4)	(seit C11)
int vfscanf_s( FILE* restrict stream, const char* restrict format, va_list vlist);	(5)	(seit C11)
int vsscanf_s( const char* restrict buffer, const char* restrict format, va_list vlist);	(6)	(seit C11)

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

1) Liest die Daten von stdin

2) Liest die Daten aus einem Dateistrom stream

3) Liest die Daten aus einer nullterminierten Zeichenkette buffer. Das Erreichen des Endes der Zeichenkette ist gleichbedeutend mit dem Erreichen der Dateiendebedingung 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 empfangenden Arrays angibt, was 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:

jedes Argument 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 übersteigen, das für jeden dieser Konvertierungsspezifizierer bereitgestellt wurde
optional jeder andere erkennbare Fehler, wie z. B. ein unbekannter Konvertierungsspezifizierer

Wie bei allen bereichsgeprüften Funktionen sind vscanf_s, vfscanf_s und vsscanf_s nur garantiert verfügbar, wenn __STDC_LIB_EXT1__ von der Implementierung definiert ist und der Benutzer __STDC_WANT_LIB_EXT1__ auf die ganzzahlige Konstante 1 setzt, bevor <stdio.h> eingebunden wird.

Parameter

stream	-	Eingabe-Dateistrom, 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 werden soll
vlist	-	Variable Argumentliste, die die empfangenden Argumente enthält.

Der format-String besteht aus

Nicht-Leerzeichen-Multibyte-Zeichen außer %: Jedes solche Zeichen im Formatstring 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 im Formatstring verbraucht alle verfügbaren aufeinanderfolgenden Leerzeichen aus der Eingabe (ermittelt, als ob isspace in einer Schleife aufgerufen würde). Beachten Sie, dass es keinen Unterschied zwischen "\n", " ", "\t\t" oder anderen Leerzeichen im Formatstring gibt.
Konvertierungsspezifikationen. Jede Konvertierungsspezifikation hat das folgende Format:

Einführendes %-Zeichen.

(optional) Zuweisungsunterdrückungszeichen *. Wenn diese Option vorhanden ist, weist die Funktion das Ergebnis der Konvertierung keinem empfangenden Argument 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 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).

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 verfügbar seit C99→		Ja				Ja	Ja	Ja	Ja
`%`	Entspricht einem literalen `%`.	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 Breiten-Spezifizierer 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 dem Array kein Nullzeichen 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 Breiten-Spezifizierer verwendet wird, werden maximal width Zeichen oder bis zum ersten Leerzeichen gefunden, je nachdem, was zuerst eintritt. Speichert immer ein Nullzeichen zusätzlich zu den gefundenen Zeichen (daher muss das Argument-Array 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, dann wird das `]`-Zeichen ebenfalls in die Menge eingeschlossen. Es ist implementationsdefiniert, ob das Zeichen `-` an nicht-initialer Position im Suchbereich (scanset) einen Bereich angeben kann, wie in `[0-9]`. Wenn ein Breiten-Spezifizierer verwendet wird, werden nur bis zu width Zeichen gefunden. Speichert immer ein Nullzeichen zusätzlich zu den gefundenen Zeichen (daher muss das Argument-Array Platz für mindestens width+1 Zeichen haben).
`d`	Entspricht einer dezimalen Ganzzahl. 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är-Ganzzahl. Das Format der Zahl ist das gleiche wie von strtoul mit dem Wert `2` für das `base`-Argument erwartet.
`i`	Entspricht einer Ganzzahl. 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 dezimalen Ganzzahl. Das Format der Zahl ist das gleiche wie von strtoul mit dem Wert `10` für das `base`-Argument erwartet.
`o`	Entspricht einer vorzeichenlosen oktalen Ganzzahl. 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 hexadezimalen Ganzzahl. 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 nicht die Zuweisungsanzahl. Wenn der Spezifizierer einen zuweisungsunterdrückenden Operator 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 Zeichenfolge, die einen Zeiger definiert. `printf` Die Familie der Funktionen sollte dieselbe Sequenz unter Verwendung des `%p`-Format-Spezifizierers erzeugen.	N/V	N/V	`void**`	N/V	N/V	N/V	N/V	N/V	N/V
Hinweise
Für jeden Konvertierungsspezifizierer außer `n` wird die längste Folge von Eingabezeichen, die keine angegebene Feldbreite überschreitet und entweder genau das ist, was der Konvertierungsspezifizierer 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 wie oben angegeben nicht konvertiert werden kann, tritt ein Übereinstimmungsfehler auf, es sei denn, das Dateiende, ein Kodierungsfehler oder ein Lesefehler hat die Eingabe vom Strom verhindert, in diesem Fall handelt es sich um einen Eingabefehler. Mit Ausnahme des `%`-Spezifizierers wird das Eingabeelement (oder für `%n` die Anzahl der Eingabezeichen) zuerst 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 (ermittelt, als ob isspace aufgerufen würde), bevor sie versuchen, die Eingabe zu parsen. Diese verbrauchten Zeichen zählen nicht zur angegebenen maximalen Feldbreite. Die Konvertierungsspezifizierer `lc`, `ls` und `l[` führen eine Multibyte-zu-Breitzeichen-Konvertierung durch, als ob mbrtowc mit einem mbstate_t-Objekt aufgerufen würde, das vor der Konvertierung des ersten Zeichens auf Null initialisiert wurde. Die Konvertierungsspezifizierer `s` und `[` speichern immer den Null-Terminator 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 mit fester Breite (int8_t, usw.) sind im Header `<inttypes.h>` definiert (obwohl `SCNdMAX`, `SCNuMAX`, usw. synonym mit `%jd`, `%ju`, usw. sind). 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. beim 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 einen Rückzieher, 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 empfangenden Argumente oder EOF, wenn ein Lesefehler auftritt, bevor das erste empfangende Argument zugewiesen wurde.

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

Hinweise

Alle diese Funktionen rufen va_arg mindestens einmal auf; der Wert von arg ist nach der Rückgabe unbestimmt. Diese Funktionen rufen va_end nicht auf; dies muss vom Aufrufer erledigt werden.

Beispiel

Diesen Code ausführen

#include <stdarg.h>
#include <stdbool.h>
#include <stdio.h>

bool checked_sscanf(int count, const char* buf, const char* fmt, ...)
{
    va_list ap;
    va_start(ap, fmt);
    int rc = vsscanf(buf, fmt, ap);
    va_end(ap);
    return rc == count;
}

int main(void)
{
    int n, m;

    printf("Parsing '1 2'...");
    if (checked_sscanf(2, "1 2", "%d %d", &n, &m))
        puts("success");
    else
        puts("failure");

    printf("Parsing '1 a'...");
    if (checked_sscanf(2, "1 a", "%d %d", &n, &m))
        puts("success");
    else
        puts("failure");
}

Ausgabe:

Parsing '1 2'...success
Parsing '1 a'...failure

Referenzen

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

7.21.6.9 Die Funktion vfscanf (S. TBD)

7.21.6.11 Die Funktion vscanf (S. TBD)

7.21.6.14 Die Funktion vsscanf (S. TBD)

K.3.5.3.9 Die Funktion vfscanf_s (S. TBD)

K.3.5.3.11 Die Funktion vscanf_s (S. TBD)

K.3.5.3.14 Die Funktion vsscanf_s (S. TBD)

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

7.21.6.9 Die Funktion vfscanf (S. TBD)

7.21.6.11 Die Funktion vscanf (S. TBD)

7.21.6.14 Die Funktion vsscanf (S. TBD)

K.3.5.3.9 Die Funktion vfscanf_s (S. TBD)

K.3.5.3.11 Die Funktion vscanf_s (S. TBD)

K.3.5.3.14 Die Funktion vsscanf_s (S. TBD)

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

7.21.6.9 Die Funktion vfscanf (S. 327)

7.21.6.11 Die Funktion vscanf (S. 328)

7.21.6.14 Die Funktion vsscanf (S. 330)

K.3.5.3.9 Die Funktion vfscanf_s (S. 597-598)

K.3.5.3.11 Die Funktion vscanf_s (S. 599)

K.3.5.3.14 Die Funktion vsscanf_s (S. 602)

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

7.19.6.9 Die Funktion vfscanf (S. 293)

7.19.6.11 Die Funktion vscanf (S. 294)

7.19.6.14 Die Funktion vsscanf (S. 295)

Siehe auch

scanffscanfsscanfscanf_sfscanf_ssscanf_s (C11)(C11)(C11)	liest formatierte Eingabe von stdin, einem Dateistrom oder einem Puffer (Funktion)
vprintfvfprintfvsprintfvsnprintfvprintf_svfprintf_svsprintf_svsnprintf_s (C99)(C11)(C11)(C11)(C11)	gibt formatierte Ausgabe auf stdout, einem Dateistrom oder einem Puffer unter Verwendung einer variablen Argumentliste aus (Funktion)
C++-Dokumentation für vscanf, vfscanf, vsscanf

Compiler-Unterstützung
Sprache
Header
Typunterstützung
Programm-Hilfsmittel
Unterstützung variadischer Funktionen
Fehlerbehandlung
Dynamische Speicherverwaltung
Zeichenketten-Bibliothek
Algorithmen
Numerik
Datums- und Zeitfunktionen
Ein-/Ausgabe-Unterstützung
Lokalisierungs-Unterstützung
Nebenläufigkeits-Unterstützung (C11)
Technische Spezifikationen
Symbol-Index

de.cppreference.net

Namespaces

Variants