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)):
vscanf(), vsscanf(), vfscanf():
_ISOC99_SOURCE ||
_POSIX_C_SOURCE >= 200112L
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.
Falls die Anzahl der Umwandlungsspezifikation in format die
Anzahl der Zeiger-Argumente übersteigt, sind die Erbenisse
undefiniert. Falls die Anzahl der Zeiger-Argumente die Anzahl der
Umwandlungsspezifikation übersteigt, werden die
überzähligen Zeiger-Argumente ausgewertet, aber
ansonsten ignoriert.
Die Funktion scanf() liest Eingaben von der Standardeingabe
stdin, fscanf liest Eingaben von dem Datenstrom-Zeiger
datenstrom und sscanf liest ihre Eingaben aus der
Zeichenkette, auf den zeichenkette zeigt.
Die Funktion vfscanf() verhält sich analog zu
vfprintf(3) und liest Eingaben von dem Datenstrom-Zeiger
datenstrom, wobei eine variable Argumentliste von Zeigern benutzt
wird (siehe stdarg(3)). Die Funktion vscanf() liest eine
variable Argumentliste von der Standardeingabe und die Funktion
vsscanf() liest sie aus einer Zeichenkette; diese sind analog zu den
Funktionen vprintf(3) beziehungsweise vsprintf(3).
Die Zeichenkette format besteht aus einer Abfolge von
Richtlinien, die beschreiben, wie die Abfolge der Eingabezeichen
verarbeitet wird. Wenn das Verarbeiten einer Richtlinie fehlschlägt,
werden keine weiteren Eingaben gelesen und scanf() kehrt
zurück. Ein »Fehlschlagen« kann folgendes sein:
input failure bedeutet, dass Eingabezeichen nicht verfügbar
sind. matching failure heißt, dass die Eingabe ungeeignet war
(siehe unten).
Eine Richtlinie kann Folgendes sein:
- •
- 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.
Jede Umwandlungsspezifikation in format fängt
entweder mit dem Zeichen »%« an oder der Zeichensequenz
»%n$« (siehe unten für die
Unterscheidung) gefolgt von:
- •
- 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 Maskierungszeichen (') für dezimale Umwandlungen.
Dies legt fest, dass die Eingabezahl einen Tausendertrenner wie in der
Kategorie LC_NUMERIC der aktuellen Locale definiert enthalten kann
(siehe setlocale(3)). Das Maskierungszeichen kann dem
»*«-Zuweisungsunterdrückungszeichen folgen oder ihm
vorangehen.
- •
- ein optionales »m«-Zeichen. Dies wird mit
Zeichenkettenumwandlungen benutzt (%s, %c, %[) 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.
- •
- 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.
- •
- ein Umwandlungskennzeichner, der den Typ der
durchzuführenden Eingabeumwandlung angibt.
Die Umwandlungsspezifikationen in format haben zwei Formen,
entweder mit »%« oder mit
»%n$« beginnend. Die beiden Formen
sollten nicht in der gleichen Formatzeichenkette gemischt werden,
außer dass eine Zeichenkette die
»%n$«-Spezifikationen enthält
%% und %* umfassen kann. Falls format
»%«-Spezifikationen enthält, dann korrespondieren diese
in der Reihenfolge mit nachfolgenden Zeiger-Argumenten. In der Form
»%n$« (die in POSIX.1-2001, aber nicht in
C99 spezifiziert ist), ist n eine dezimale Ganzzahl, die anzeigt,
dass die umgewandelte Eingabe an die Stelle platziert werden sollte, auf die
sich das dem nten Zeiger-Argument folgende format
bezieht.
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. Dieser Kennzeichner existiert in ANSI-C
nicht.
- 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.
Die folgenden Umwandlungskennzeichner sind
verfügbar:
- %
- 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 das erste Element eines Zeichenfelds
sein, das groß genug ist, um die Eingabesequenz und das
abschließende Null-Byte (»\0«), das automatisch
hinzugefügt wird, 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 und
erhöht nicht die von der Funktion zurückgegebene
Anzahl. Die Zuweisung kann durch das
Zuweisungsunterdrückungszeichen * unterdrückt werden,
die Auswirkung auf den Rückgabewert ist jedoch nicht definiert.
Daher sollten keine %*n-Umwandlungen benutzt werden.
Bei Erfolg geben diese Funktionen 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.
Der Wert EOF wird zurückgegeben, wenn das Ende der
Eingabe erreicht wird, bevor entweder die erste erfolgreiche Umwandlung oder
das erste Fehlschlagen eines Abgleichs auftrat. EOF wird auch
zurückgegeben, wenn ein Lesefehler auftritt. In diesem Fall wird die
Fehleranzeige für den Datenstrom gesetzt (siehe ferror(3)) und
errno so gesetzt, dass es den Fehler angibt.
- EAGAIN
- Der Dateideskriptor, der datenstrom zugrundeliegt, ist als nicht
blockierend gekennzeichnet und die Leseaktion würde
blockieren.
- 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 Leseaktion wurde durch ein Signal unterbrochen; siehe
signal(7).
- EINVAL
- nicht genug Argumente oder format ist NULL
- ENOMEM
- Speicher aufgebraucht.
- ERANGE
- Das Ergebnis einer Ganzzahl-Umwandlung würde die
Größe überschreiten, die in dem zugehörigen
Ganzzahl-Typ gespeichert werden könnte.
Siehe attributes(7) für eine Erläuterung der
in diesem Abschnitt verwandten Ausdrücke.
Schnittstelle |
Attribut |
Wert |
scanf(), fscanf(), sscanf(), vscanf(),
vsscanf(), vfscanf() |
Multithread-Fähigkeit |
MT-Safe locale |
Die Funktionen fscanf(), scanf() und sscanf()
sind konform zu c89, C99 und POSIX.1-2001. Diese Vorgaben spezifizieren
nicht den Fehler ERANGE.
Der Kennzeichner 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).
Ursprünglich unterstützte die GNU-C-Bibliothek die
dynamische Reservierung für Eingabezeichenketten (als eine
Nichtstandarderweiterung) über das Zeichen a. (Diese
Funktionalität ist bis mindestens Glibc 2.0 zurück
verfügbar.) Daher könnte jemand das Folgende schreiben, um
scanf() einen Puffer für eine Eingabezeichenkette reservieren
zu lassen. Ein Zeiger auf diesen Puffer wird in *buf
zurückgegeben:
char *buf;
scanf("%as", &buf);
Die Verwendung des Buchstabens a für diesen Zweck
war problematisch, da a auch im ISO-C-Standard als andere Bezeichnung
für f (Fließkommaeingabe) spezifiziert ist.
POSIX.1-2008 spezifiziert stattdessen den Modifikator m für
die Zuweisungsreservierung (wie oben unter BESCHREIBUNG dokumentiert).
Beachten Sie, dass der Modifikator a nicht verfügbar
ist, falls 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
Kennzeichner für Fließkommazahlen interpretiert (siehe
oben).
Ab Version 2.7 wurde Glibc Unterstützung für dem
Modifikator m hinzugefügt. Neue Programme sollten diesen
Modifikator anstelle von a benutzen.
Neben der Standardisierung durch POSIX, hat der Modifikator
m auch die folgenden Vorteile gegenüber der Verwendung von
a:
- Es könnte auch auf %c-Umwandlungskennzeichner angewandt
werden (z.B. %3mc).
- Es vermeidet Mehrdeutigkeit bezüglich der Umwandlungskennzeichner
für Fließkommazahlen %a (und wird nicht von gcc
-std=c99 etc. beeinflusst).
Alle Funktionen sind vollkommen konform zu C89, stellen jedoch die
zusätzlichen Kennzeichner q und a sowie ein
zusätzliches Verhalten des Kennzeichners L und l zur
Verfügung. Letzteres kann als Fehler angesehen werden, da es das
Verhalten der Kennzeichner verändert, die in C89 definiert sind.
Einige Kombinationen von Typänderungssymbolen und
Umwandlungskennzeichner, 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.
Um den Kennzeichner für die dynamische
Reservierungsumwandlung zu verwenden, geben Sie als Längenmodifikator
m an (also %ms oder %m[Bereich]). Der
Aufrufende muss die zurückgegebene Zeichenkette mit free(3),
wie im folgenden Beispiel, freigeben:
char *p;
int n;
errno = 0;
n = scanf("%m[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.
Diese Seite ist Teil der Veröffentlichung 4.16 des Projekts
Linux-man-pages. Eine Beschreibung des Projekts, Informationen, wie
Fehler gemeldet werden können sowie die aktuelle Version dieser Seite
finden sich unter https://www.kernel.org/doc/man-pages/.
ÜBERSETZUNG
Die deutsche Übersetzung dieser Handbuchseite wurde von
Patrick Rother <krd@gulu.net>, Chris Leick <c.leick@vollbio.de>
und Helge Kreutzmann <debian@helgefjell.de> erstellt.
Diese Übersetzung ist Freie Dokumentation; lesen Sie die
GNU General Public License Version 3 oder neuer bezüglich der
Copyright-Bedingungen. Es wird KEINE HAFTUNG übernommen.
Wenn Sie Fehler in der Übersetzung dieser Handbuchseite
finden, schicken Sie bitte eine E-Mail an
<debian-l10n-german@lists.debian.org>.