Provided by: manpages-de-dev_4.13-4_all 
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)):
vscanf(), vsscanf(), vfscanf():
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
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 der zugehörigen
Umwandlungsspezifikation haben.
Falls die Anzahl der Umwandlungsspezifikation in format die Anzahl der Zeiger-Argumente übersteigt, sind
die Ergebnisse 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 die
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:
• einem optionalen »*«-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.
• einem optionalen englischen Anführungszeichen (') für dezimale Umwandlungen. Dies gibt an, 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.
• einem optionalen »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.
• einer optionalen dezimalen 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.
• einem optionalen 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 statt auf einen Zeiger vom Typ int bezieht.
• einem 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.
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 oder unsigned short (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 oder ein unsigned long (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.
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 optional 0x oder 0X vorangestellt
werden kann, was ignoriert wird); 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 Menge 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 ausschließlich aus Zeichen bestehen, die in einer
bestimmten Menge (nicht) enthalten sind; die Menge wird durch die Zeichen zwischen der öffnenden [
und schließenden ] Klammer definiert. Die Menge schließt jene Zeichen aus, wenn das erste Zeichen
nach der öffnenden Klammer ein Zirkumflex (^) ist. Um der Menge 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 Menge 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 Menge
»alles außer schließender Klammer, null bis neun und Bindestrich«. Die Zeichenkette endet mit dem
Erscheinen eines nicht in der Menge 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.
RÜCKGABEWERT
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 »matching
failure« auftrat.
Der Wert EOF wird zurückgegeben, wenn das Ende der Eingabe erreicht wird, bevor entweder die erste
erfolgreiche Umwandlung oder ein »matching failure« 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.
FEHLER
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.
ATTRIBUTE
Siehe attributes(7) für eine Erläuterung der in diesem Abschnitt verwandten Ausdrücke.
┌──────────────────────┬───────────────────────┬────────────────┐
│ Schnittstelle │ Attribut │ Wert │
├──────────────────────┼───────────────────────┼────────────────┤
│ scanf(), fscanf(), │ Multithread-Fähigkeit │ MT-Safe locale │
│ sscanf(), vscanf(), │ │ │
│ vsscanf(), vfscanf() │ │ │
└──────────────────────┴───────────────────────┴────────────────┘
KONFORM ZU
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).
ANMERKUNGEN
Der Zuweisungs- und Reservierungsmodifikator »a«
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).
FEHLER
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.
BEISPIELE
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.
SIEHE AUCH
getc(3), printf(3), setlocale(3), strtod(3), strtol(3), strtoul(3)
KOLOPHON
Diese Seite ist Teil der Veröffentlichung 5.10 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 die
Mailingliste der Übersetzer.
GNU 13. August 2020 SCANF(3)