Namensräume
Varianten
Aktionen

vscanf, vfscanf, vsscanf, vscanf_s, vfscanf_s, vsscanf_s

Von cppreference.com
< c‎ | io
 
C
 
Datei-Ein-/Ausgabe
Typen und Objekte
        
Funktionen
Datei-Zugriff
(C11)
(C11)  
(C95)
Unformatierte Ein-/Ausgabe
(C95)(C95)
(C95)
(C95)(C95)
(C95)
(C95)
(C95)
(C95)

Formatierte Eingabe
vscanfvfscanfvsscanfvscanf_svfscanf_svsscanf_s
(C99)(C99)(C99)(C11)(C11)(C11)
(C99)(C99)(C99)(C11)(C11)(C11)  
Direkte Ein-/Ausgabe
Formatierte Ausgabe
Dateipositionierung
Fehlerbehandlung
Operationen auf Dateien
 
Definiert in 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 verschiedenen Quellen, interpretiert sie gemäß format und speichert die Ergebnisse in Speicherorten, die durch vlist definiert sind.

1) Liest die Daten aus stdin
2) Liest die Daten aus dem Dateistream stream
3) Liest die Daten aus der nullterminierten Zeichenkette buffer. Das Erreichen des Endes der Zeichenkette ist gleichbedeutend mit dem Erreichen der End-of-File-Bedingung für fscanf.
4-6) Ähnlich wie (1-3), mit der Ausnahme, 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, was 1 sein kann, wenn mit %c in ein einzelnes Zeichen gelesen wird) und mit der Ausnahme, dass die folgenden Fehler zur Laufzeit erkannt werden und die derzeit 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 terminierende Nullzeichen, würde das zweite (rsize_t) Argument für jeden dieser Konvertierungsspezifizierer überschreiten.
  • Optional, jeder andere erkennbare Fehler, wie z.B. ein unbekannter Konvertierungsspezifizierer.
Wie bei allen grenzgeprüften Funktionen sind vscanf_s, vfscanf_s und vsscanf_s nur dann garantiert verfügbar, wenn __STDC_LIB_EXT1__ von der Implementierung definiert wird und wenn der Benutzer __STDC_WANT_LIB_EXT1__ auf die Ganzzahlkonstante 1 setzt, bevor <stdio.h> eingebunden wird.

Inhalt

[edit] 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
vlist - Variablenargumentenliste, die die Empfängerargumente enthält.


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 (bestimmt, als ob durch Aufruf von isspace in einer Schleife). Beachten Sie, dass es keinen Unterschied zwischen "\n", " ", "\t\t" oder anderen Whitespace-Zeichen 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 erwartet von strtol mit dem Wert 10 für das Argument base.
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

Entspricht einer Ganzzahl.

  • Das Format der Zahl ist dasselbe wie erwartet von strtol mit dem Wert ​0​ für das Argument base (die Basis wird durch die ersten gelesenen Zeichen bestimmt).
u

Entspricht einer vorzeichenlosen Dezimalganzzahl.

  • Das Format der Zahl ist dasselbe wie erwartet von strtoul mit dem Wert 10 für das Argument base.
o

Entspricht einer vorzeichenlosen Oktalganzzahl.

  • Das Format der Zahl ist dasselbe wie erwartet von strtoul mit dem Wert 8 für das Argument base.
x
X

Entspricht einer vorzeichenlosen Hexadezimalganzzahl.

  • Das Format der Zahl ist dasselbe wie erwartet von strtoul mit dem Wert 16 für das Argument base.
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 erwartet von strtof.
 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 Whitespace-Zeichen (bestimmt, als ob durch Aufruf von isspace) vor dem Versuch, 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-Wide-Character-Konvertierung durch, als ob mbrtowc mit einem mbstate_t-Objekt auf Null initialisiert vor der Konvertierung des ersten Zeichens 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 Gleitkommawerts, der im Exponenten mit keinen Ziffern endet, wie beim Parsen von "100er" mit dem Konvertierungsspezifizierer %f, wird die Sequenz "100e" (der längste Präfix einer möglicherweise gültigen Gleitkommazahl) verbraucht, was zu einem passenden Fehler 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, wobei "er" übrig bleibt, z.B. glibc Bug 1765.

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

[edit] 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.

[edit] Hinweise

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

[edit] Beispiel

Führen Sie diesen Code aus
#include <stdio.h>
#include <stdbool.h>
#include <stdarg.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

[edit] Referenzen

  • 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)

[edit] Siehe auch

(C11)(C11)(C11)
 liest formatierte Eingaben aus stdin, einem Dateistream oder einem Puffer
(Funktion) [bearbeiten]
(C99)(C11)(C11)(C11)(C11)
 gibt formatierte Ausgaben nach stdout, an einen Dateistream oder in einen Puffer aus
mit variabler Argumentenliste
(Funktion) [bearbeiten]
C++-Dokumentation für vscanf, vfscanf, vsscanf
Abgerufen von "https://cppreference.de/mwiki/index.php?title=c/io/vfscanf&oldid=125689"