table of contents
SCANF(3) | Linux-Programmierhandbuch | SCANF(3) |
BEZEICHNUNG¶
scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf - Anpassung des EingabeformatsÜBERSICHT¶
#include <stdio.h> int scanf(const char *format, ...); int fscanf(FILE *datenstrom, const char *format, ...); int sscanf(const char *zeichenkette, const char *format, ...);#include <stdarg.h> int vscanf(const char *format, va_list ap); int vsscanf(const char *zeichenkette, const char *format, va_list ap); int vfscanf(FILE *datenstrom, const char *format, va_list ap);
Mit Glibc erforderliche Makros (siehe feature_test_macros(7)):
_XOPEN_SOURCE >= 600 ||
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L;
oder cc -std=c99
BESCHREIBUNG¶
Die Funktionenfamilie scanf() prüft Eingaben in Bezug auf ein format, wie es im Folgenden beschrieben wird. Dieses Format darf Umwandlungsspezifikationen enthalten; die Ergebnisse solcher Umwandlungen, falls vorhanden, werden an den Stellen gespeichert, auf die die Zeiger-Argumente verweisen, die sich an das format halten. Jedes Zeiger-Argument muss einen geeigneten Typ für den Rückgabewert durch die zugehörige Umwandlungsspezifikation haben.- •
- eine Abfolge von Leerräumen (Leerzeichen, Tabulator, Zeilenvorschub, etc.; siehe isspace(3)). Diese Richtlinie passt auf jede Menge von Leerräumen, einschließlich keinen in der Eingabe.
- •
- ein normales Zeichen (d.h. ein anderes, als ein Leerraum oder »%«). Dieses Zeichen muss exakt mit dem nächsten Zeichen der Eingabe übereinstimmen.
- •
- eine Umwandlungsspezifikation, die mit dem Zeichen »%« (Prozent) beginnt. Eine Abfolge von Zeichen wird gemäß dieser Spezifikation umgewandelt und das Ergebnis wird in das zugehörige Zeiger-Argument platziert. Falls das nächste Element nicht der Umwandlungsspezifikation entspricht, schlägt die Umwandlung fehl – dies ist ein matching failure.
- •
- ein optionales »*«-Zeichen zur Unterdrückung der Zuweisung: scanf() liest die Eingabe gemäß der Umwandlungsspezifikation, verwirft aber die Eingabe. Es wird kein zugehöriges Zeiger-Argument benötigt und diese Spezifikation ist nicht in der Anzahl der erfolgreichen Zuweisungen enthalten, die von scanf() zurückgegeben werden.
- •
- ein optionales »a«-Zeichen. Dies wird mit Zeichenkettenumwandlungen benutzt und entlastet den Aufrufenden von der Notwendigkeit einen zugehörigen Puffer zu reservieren, der die Eingabe erhält: Stattdessen reserviert scanf() einen Puffer von ausreichender Größe und weist die Adresse dieses Puffers dem zugehörigen Zeiger-Argument zu, das ein Zeiger auf eine char *-Variable sein sollte. (Diese Variable muss nicht vor dem Aufruf initialisiert werden.) Der Aufrufende sollte diesen Puffer danach mit free(3) freigeben, wenn er nicht länger benötigt wird. Dies ist eine GNU-Erweiterung; C99 verwendet das Zeichen »a« als Umwandlungs-Speifikationssymbol (und es kann auch in der GNU-Implementierung als solches benutzt werden).
- •
- eine optionale dezimale Ganzzahl, die die maximale Feldbreite angibt. Das Lesen von Zeichen stoppt entweder wenn dieses Maximum erreicht wurde oder wenn ein unpassendes Zeichen gefunden wurde, je nachdem, was eher auftrat. Die meisten Umwandlungen verwerfen Leerräume am Anfang (die Ausnahmen sind nachfolgend vermerkt). Diese verworfenen Zeichen werden nicht bei der Berechnung der maximalen Feldbreite mitgezählt. Eingabeumwandlung von Zeichenketten speichert ein terminierendes Null-Byte (»\0«), um das Ende der Eingabe zu kennzeichnen; die maximale Feldbreite enthält dieses Endezeichen nicht.
- •
- ein optionales Typ-Änderungszeichen. Das Typ-Änderungszeichen l wird zum Beispiel bei Ganzzahlumwandlungen, wie %d benutzt, um anzugeben, dass sich das zugehörige Zeiger-Argument auf long int statt auf einen Zeiger vom Typ int bezieht.
- •
- eine Umwandlungsspezifikation, die den Typ der durchzuführenden Eingabeumwandlung angibt.
Umwandlungen¶
Die folgenden Typ-Änderungszeichen können in einer Umwandlungsspezifikation erscheinen:- h
- zeigt an, dass die Umwandlung entweder d, i, o, u, x, X oder n sein wird und der nächste Zeiger ein Zeiger auf ein short int oder unsigned short int (statt int) sein wird.
- hh
- wie für h, aber der nächste Zeiger ist ein Zeiger auf ein signed char oder ein unsigned char.
- j
- wie für h, aber der nächste Zeiger ist ein Zeiger auf ein intmax_t oder ein uintmax_t. Dieses Änderungszeichen wurde in C99 eingeführt.
- l
- zeigt an, dass die Umwandlung entweder d, i, o, u, x, X oder n sein wird und der nächste Zeiger ein Zeiger auf ein long int oder ein unsigned long int (statt int) sein wird oder dass die Umwandlung entweder e, f oder g sein wird und der nächste Zeiger ein Zeiger auf ein double (statt float ) sein wird. Die Angabe von zwei l-Zeichen ist äquivalent zu L. Falls sie zusammen mit %c oder %s benutzt werden, wird der zugehörige Parameter als ein Zeiger auf ein Wide-Character beziehungsweise eine Wide-Character-Zeichenkette betrachtet.
- L
- zeigt an, dass die Umwandlung entweder e, f oder g sein wird und der nächste Zeiger ein Zeiger auf ein long double ist oder dass die Umwandlung entweder d, i, o, u oder x sein wird und der nächste Zeiger ein Zeiger auf ein long long sein wird.
- q
- ist äquivalent zu L. Dieses Spezifiakationssymbol existiert nicht in ANSI-C.
- t
- wie für h, der nächste Zeiger ist aber ein Zeiger auf ein ptrdiff_t. Dieses Änderungszeichen wurde in C99 eingeführt.
- z
- wie für h, der nächste Zeiger ist aber ein Zeiger auf ein size_t. Dieses Änderungszeichen wurde in C99 eingeführt.
- %
- passt zum Buchstabensymbol »%«. Das heißt, %% im Formatstring passt zum einzelnen Eingabezeichnen »%«. Es findet keine Umwandlung statt (aber Leerräume am Anfang werden verworfen) und eine Zuweisung tritt nicht auf.
- d
- passt zu einer optionalen vorzeichenbehafteten dezimalen Ganzzahl; der nächste Zeiger muss ein Zeiger auf int sein.
- D
- äquivalent zu ld; dies existiert nur aus Gründen der Rückwärtskompatibilität. (Beachten Sie, dass dies daher nur in Libc4 der Fall ist. In Libc5 und Glibc wird das %D stillschweigend ignoriert, was alte Programme zu mysteriösem Fehlschlagen veranlasst.)
- i
- passt zu einer optionalen vorzeichenbehafteten Ganzzahl; der nächste Zeiger muss ein Zeiger auf int sein. Die Ganzzahl wird zur Basis 16 gelesen, wenn sie mit 0x oder 0X beginnt, zur Basis 8, wenn sie mit 0 beginnt, anderenfalls zur Basis 10. Nur Zeichen, die zur Basis passen, werden benutzt.
- o
- passt zu einer vorzeichenlosen oktalen Ganzzahl; der nächste Zeiger muss ein Zeiger auf ein unsigned int sein.
- u
- passt zu einer vorzeichenlosen dezimalen Ganzzahl; der nächste Zeiger muss ein Zeiger auf ein unsigned int sein.
- x
- passt zu einer vorzeichenlosen hexadezimalen Ganzzahl; der nächste Zeiger muss ein Zeiger auf ein unsigned int sein.
- X
- äquivalent zu x
- f
- passt zu einer optionalen vorzeichenbehafteten Fließkommazahl; der nächste Zeiger muss ein Zeiger auf ein float sein.
- e
- äquivalent zu f.
- g
- äquivalent zu f.
- E
- äquivalent zu f.
- a
- (C99) äquivalent zu f.
- s
- passt zu einer Zeichenfolge, die keinen Leerraum darstellt; der nächste Zeiger muss Zeiger auf ein Zeichenfeld sein, das groß genug ist, um die Eingabesequenz und das abschließende Null-Byte (»\0«) aufnehmen zu können. Die Eingabezeichenkette stoppt an Leerräumen oder an der maximalen Feldgröße, je nachdem, was zuerst auftritt.
- c
- passt zu einer Zeichenfolge, deren Länge durch die maximale Feldgröße (Vorgabe 1) angegeben wird; der nächste Zeiger muss ein Zeiger auf ein char sein und es muss genug Platz für alle Zeichen vorhanden sein (es wird keine abschließende Null angehängt.) Das übliche Überspringen der führenden Leerräume wird unterdrückt. Benutzen Sie ein explizites Leerzeichen im Format, um Leerräume zu überspringen .
- [
- passt zu einer nicht leeren Abfolge von Zeichen aus der angegebenen Zusammenstellung akzeptierter Zeichen; der nächste Zeiger muss ein Zeiger auf char sein und genug Platz für alle Zeichen der Zeichenkette einschließlich abschließendem Null-Byte bieten. Das übliche Überspringen der führenden Leerräume wird unterdrückt. Die Zeichenkette soll aus Zeichen in einer (oder keiner) besonderen Zusammenstellung bestehen; die Zusammenstellung wird durch die Zeichen zwischen der öffnenden [ und schließenden ] Klammer definiert. Die Zusammenstellung schließt jene Zeichen aus, wenn das erste Zeichen nach der öffnenden Klammer ein Zirkumflex ( ^) ist. Um der Zusammenstellung eine schließende Klammer hinzuzufügen, setzen Sie sie als erstes Zeichen nach der öffnenden Klammer oder dem Zirkumflex; jede andere Position würde die Zusammenstellung beenden. Um einen Bindestrich einzufügen, setzen Sie ihn als letztes Zeichen vor der schließenden Klammer am Ende. [^]0-9-] bedeutet zum Beispiel, die Zusammenstellung »alles außer schließender Klammer, null bis neun und Bindestrich«. Die Zeichenkette endet mit dem Erscheinen eines nicht in der Zusammenstellung enthaltenen Zeichens (oder mit einem enthaltenen Zirkumflex) oder wenn die Feldgröße erschöpft ist.
- p
- passt zu einem Zeigerwert (wie durch »%p« in printf(3) ausgegeben); der nächste Zeiger muss ein Zeiger auf void sein.
- n
- es wird nichts erwartet; stattdessen wird die Anzahl der Zeichen, die bis jetzt eingelesen wurden, im nächsten Zeiger gespeichert, welcher ein Zeiger auf int sein muss. Dies ist keine Umwandlung, obwohl sie durch das Zeichen zum Unterdrücken von Zuweisungen * unterdrückt werden kann. Der C-Standard sagt: »Die Ausführung einer %n-Richtlinie erhöht nicht die Anzahl der Zuweisungen, die bei Fertigstellung der Ausführung zurückgegeben werden«, aber die Berichtigung scheint dem zu widersprechen. Es ist wahrscheinlich ratsam, keine Annahmen über die Auswirkungen von %n-Umwandlungen auf den Rückgabewert zu treffen.
RÜCKGABEWERT¶
Diese Funktionen geben die Anzahl der Eingabeelemente zurück, die erfolgreich übereinstimmten und zugewiesen wurden. Dies können weniger sein, als bereitgestellt wurden oder null, wenn ein früherer Abgleich scheiterte.FEHLER¶
- EAGAIN
- Der Dateideskriptor, der datenstrom zugrundeliegt, ist als nicht blockierend gekennzeichnet und die Leseoperation würde blocken.
- EBADF
- Der Dateideskriptor, der datenstrom zugrundeliegt, ist ungültig oder nicht zum Lesen geöffnet.
- EILSEQ
- Eingabebyte-Abfolge bildet kein gültiges Zeichen
- EINTR
- Die Leseoperation wurde durch ein Signal unterbrochen; siehe signal(7).
- EINVAL
- nicht genug Argumente oder format ist NULL
- ENOMEM
- Platz im Hauptspeicher reicht nicht aus
- ERANGE
- Das Ergebnis einer Ganzzahl-Umwandlung würde die Größe überschreiten, die in dem zugehörigen Ganzzahl-Typ gespeichert werden könnte.
KONFORM ZU¶
Die Funktionen fscanf(), scanf() und sscanf() sind konform zu c89, C99 und POSIX.1-2001. Diese Vorgaben spezifizieren nicht den Fehler ERANGE. Das Spezifikationssymbol q ist die 4.4BSD-Schreibweise für long long, während ll oder die Benutzung von L in Ganzzahlumwandlungen die GNU-Schreibweise ist. Die Linuxversion dieser Funktionen basiert auf der GNU-Bibliothek libio Eine präzisere Beschreibung findet sich in der info-Dokumentation von GNU libc (glibc-1.08).ANMERKUNGEN¶
Die GNU-C-Bibliothek unterstützt eine nicht standardisierte Erweiterung, die die Bibliothek veranlasst dynamisch eine Zeichenkette von ausreichender Größe für Eingabezeichenketten und die %s- und %a[ Bereich]-Umwandlungsspezifikationen zu reservieren. Um von dieser Funktion Gebrauch zu machen, geben Sie als Längenänderungszeichen a an (also %as oder %a[range]). Der Aufrufende muss die zurückgegebene Zeichenkette mit free(3), wie im folgenden Beispiel freigeben:char *p; int n; errno = 0; n = scanf("%a[a-z]", &p); if (n == 1) { printf("read: %s\n", p); free(p); } else if (errno != 0) { perror("scanf"); } else { fprintf(stderr, "Keine passenden Zeichen\n"); }
Wie im vorstehenden Beispiel gezeigt, ist es nur nötig free(3) aufzurufen, wenn der Aufruf von scanf() eine Zeichenkette erfolgreich gelesen hat. Das Änderungszeichen a ist nicht verfügbar, wenn das Programm mit gcc -std=c99 oder gcc -D_ISOC99_SOURCE kompiliert wurde (außer wenn auch _GNU_SOURCE angegeben wurde). In diesem Fall wird a als Spezifikationssymbol für Fließkommazahlen interpretiert (siehe oben).
- *
- Es könnte auch auf %c-Umwandlungsspezifikationen angewandt werden (z.B. %3mc).
- *
- Es vermeidet Mehrdeutigkeit bezüglich der Umwandlungsspezifikation für Fließkommazahlen %a (und wird nicht von gcc -std=c99 etc. beeinflusst).
- *
- Es ist in der bevorstehenden Überarbeitung des POSIX.1-Standards spezifiziert.
FEHLER¶
Alle Funktionen sind vollkommen konform zu C89, stellen jedoch die zusätzlichen Spezifikationssymbole q und a sowie ein zusätzliches Verhalten der Spezifikationssymbole L und l zur Verfügung. Letzteres kann als Fehler angesehen werden, da es das Verhalten der Spezifikationssymbole verändert, die in C89 definiert sind. Einige Kombinationen von Typänderungssymbolen und Umwandlungsspezifikationen, die durch ANSI-C definiert sind, sind sinnlos (z.B. %Ld). Während sie ein wohldefiniertes Verhalten unter Linux haben, braucht dies auf anderen Architekturen nicht der Fall zu sein. Daher ist es gewöhnlich besser Änderungssymbole zu benutzen, die gar nicht durch ANSI-C definiert sind, also q anstelle von L in Kombination mit der Umwandlungen d, i, o, u, x und X oder ll. Die Benutzung von q ist nicht die gleiche wie auf 4.4BSD, da sie in Fließkommaumwandlungen äquivalent zu L benutzt werden kann.SIEHE AUCH¶
getc(3), printf(3), setlocale(3), strtod(3), strtol(3), strtoul(3)KOLOPHON¶
Diese Seite ist Teil der Veröffentlichung 3.42 des Projekts Linux- man-pages. Eine Beschreibung des Projekts und Informationen, wie Fehler gemeldet werden können, finden sich unter http://www.kernel.org/doc/man-pages/.ÜBERSETZUNG¶
Die deutsche Übersetzung dieser Handbuchseite wurde von Patrick Rother <krd@gulu.net> und Chris Leick <c.leick@vollbio.de> erstellt.28. September 2011 | GNU |