Provided by:
manpages-de-dev_0.10-1_all 
BEZEICHNUNG
scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf - Anpassung des
Eingabeformats
"UBERSICHT
#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():
_XOPEN_SOURCE >= 600 || _ISOC99_SOURCE ||
_POSIX_C_SOURCE >= 200112L;
oder cc -std=c99
BESCHREIBUNG
Die Funktionenfamilie scanf() pruft 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 fur den Ruckgabewert
durch die zugehorige Umwandlungsspezifikation haben.
Falls die Anzahl der Umwandlungsspezifikation in format die Anzahl der
Zeiger-Argumente ubersteigt, sind die Erbenisse undefiniert. Falls die
Anzahl der Zeiger-Argumente die Anzahl der Umwandlungsspezifikation
ubersteigt, werden die uberzahligen 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() verhalt 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 fehlschlagt, werden keine weiteren
Eingaben gelesen und scanf() kehrt zuruck. Ein >>Fehlschlagen<< kann
folgendes sein: input failure bedeutet, dass Eingabezeichen nicht
verfugbar sind. matching failure heiBt, dass die Eingabe ungeeignet war
(siehe unten).
Eine Richtlinie kann Folgendes sein:
o eine Abfolge von Leerraumen (Leerzeichen, Tabulator,
Zeilenvorschub, etc.; siehe isspace(3)). Diese Richtlinie passt
auf jede Menge von Leerraumen, einschlieBlich keinen in der
Eingabe.
o ein normales Zeichen (d.h. ein anderes, als ein Leerraum oder
>>%<<). Dieses Zeichen muss exakt mit dem nachsten Zeichen der
Eingabe ubereinstimmen.
o eine Umwandlungsspezifikation, die mit dem Zeichen >>%<<
(Prozent) beginnt. Eine Abfolge von Zeichen wird gemaB dieser
Spezifikation umgewandelt und das Ergebnis wird in das
zugehorige Zeiger-Argument platziert. Falls das nachste Element
nicht der Umwandlungsspezifikation entspricht, schlagt die
Umwandlung fehl - dies ist ein matching failure.
Jede Umwandlungsspezifikation in format fangt entweder mit dem Zeichen
>>%<< an oder der Zeichensequenz >>%n$<< (siehe unten fur die
Unterscheidung) gefolgt von:
o ein optionales >>*<<-Zeichen zur Unterdruckung der Zuweisung:
scanf() liest die Eingabe gemaB der Umwandlungsspezifikation,
verwirft aber die Eingabe. Es wird kein zugehoriges
Zeiger-Argument benotigt und diese Spezifikation ist nicht in
der Anzahl der erfolgreichen Zuweisungen enthalten, die von
scanf() zuruckgegeben werden.
o ein optionales >>a<<-Zeichen. Dies wird mit
Zeichenkettenumwandlungen benutzt und entlastet den Aufrufenden
von der Notwendigkeit einen zugehorigen Puffer zu reservieren,
der die Eingabe erhalt: Stattdessen reserviert scanf() einen
Puffer von ausreichender GroBe und weist die Adresse dieses
Puffers dem zugehorigen 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 langer
benotigt 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).
o 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 Leerraume am Anfang (die Ausnahmen sind
nachfolgend vermerkt). Diese verworfenen Zeichen werden nicht
bei der Berechnung der maximalen Feldbreite mitgezahlt.
Eingabeumwandlung von Zeichenketten speichert ein
Null-Endezeichen (>>\0<<), um das Ende der Eingabe zu
kennzeichnen; die maximale Feldbreite enthalt dieses Endezeichen
nicht.
o ein optionales Typ-"Anderungszeichen. Das Typ-Anderungszeichen l
wird zum Beispiel bei Ganzzahlumwandlungen, wie %d benutzt, um
anzugeben, dass sich das zugehorige Zeiger-Argument auf long int
statt auf einen Zeiger vom Typ int bezieht.
o eine Umwandlungsspezifikation, die den Typ der durchzufuhrenden
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, auBer dass eine
Zeichenkette die >>%n$<<-Spezifikationen enthalt %% und %* umfassen
kann. Falls format >>%<<-Spezifikationen enthalt, 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-"Anderungszeichen konnen in einer
Umwandlungsspezifikation erscheinen:
h zeigt an, dass die Umwandlung entweder d, i, o, u, x, X oder n
sein wird und der nachste Zeiger ein Zeiger auf ein short int
oder unsigned short int (statt int) sein wird.
hh wie fur h, aber der nachste Zeiger ist ein Zeiger auf ein signed
char oder ein unsigned char.
j wie fur h, aber der nachste Zeiger ist ein Zeiger auf ein
intmax_t oder ein uintmax_t. Dieses Anderungszeichen wurde in
C99 eingefuhrt.
l zeigt an, dass die Umwandlung entweder d, i, o, u, x, X oder n
sein wird und der nachste 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 nachste Zeiger
ein Zeiger auf ein double (statt float ) sein wird. Die Angabe
von zwei l-Zeichen ist aquivalent zu L. Falls sie zusammen mit
%c oder %s benutzt werden, wird der zugehorige 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 nachste Zeiger ein Zeiger auf ein long double ist oder dass
die Umwandlung entweder d, i, o, u oder x sein wird und der
nachste Zeiger ein Zeiger auf ein long long sein wird.
q ist aquivalent zu L. Dieses Spezifiakationssymbol existiert
nicht in ANSI-C.
t wie fur h, der nachste Zeiger ist aber ein Zeiger auf ein
ptrdiff_t. Dieses Anderungszeichen wurde in C99 eingefuhrt.
z wie fur h, der nachste Zeiger ist aber ein Zeiger auf ein
size_t. Dieses Anderungszeichen wurde in C99 eingefuhrt.
Die folgenden Umwandlungsspezifikationen sind verfugbar:
% passt zum Buchstabensymbol >>%<<. Das heiBt, %% im Formatstring
passt zum einzelnen Eingabezeichnen >>%<<. Es findet keine
Umwandlung statt (aber Leerraume am Anfang werden verworfen) und
eine Zuweisung tritt nicht auf.
d passt zu einer optionalen vorzeichenbehafteten dezimalen
Ganzzahl; der nachste Zeiger muss ein Zeiger auf int sein.
D aquivalent zu ld; dies existiert nur aus Grunden der
Ruckwartskompatibilitat. (Beachten Sie, dass dies daher nur in
Libc4 der Fall ist. In Libc5 und Glibc wird das %D
stillschweigend ignoriert, was alte Programme zu mysteriosem
Fehlschlagen veranlasst.)
i passt zu einer optionalen vorzeichenbehafteten Ganzzahl; der
nachste 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 nachste
Zeiger muss ein Zeiger auf ein unsigned int sein.
u passt zu einer vorzeichenlosen dezimalen Ganzzahl; der nachste
Zeiger muss ein Zeiger auf ein unsigned int sein.
x passt zu einer vorzeichenlosen hexadezimalen Ganzzahl; der
nachste Zeiger muss ein Zeiger auf ein unsigned int sein.
X aquivalent zu x
f passt zu einer optionalen vorzeichenbehafteten FlieBkommazahl;
der nachste Zeiger muss ein Zeiger auf ein float sein.
e aquivalent zu f.
g aquivalent zu f.
E aquivalent zu f.
a (C99) aquivalent zu f.
s passt zu einer Zeichenfolge, die keinen Leerraum darstellt; der
nachste Zeiger muss Zeiger auf ein Zeichenfeld sein, das groB
genueg ist. um die Eingabesequenz und das abschlieBende
Null-Zeichen (>>\0<<) aufnehmen zu konnen. Die
Eingabezeichenkette stoppt an Leerraumen oder an der maximalen
FeldgroBe, je nachdem, was zuerst auftritt.
c passt zu einer Zeichenfolge, deren Lange durch die maximale
Feldgr"oBe (Vorgabe 1) angegeben wird; der nachste Zeiger muss
ein Zeiger auf ein char sein und es muss genug Platz fur alle
Zeichen vorhanden sein (es wird keine abschlieBende Null
angehangt.) Das ubliche Uberspringen der fuhrenden Leerraume
wird unterdruckt. Benutzen Sie ein explizites Leerzeichen im
Format, um Leerraume zu uberspringen .
[ passt zu einer nicht leeren Abfolge von Zeichen aus der
angegebenen Zusammenstellung akzeptierter Zeichen; der nachste
Zeiger muss ein Zeiger auf char sein und genug Platz fur alle
Zeichen der Zeichenkette einschlieBlich abschlieBendem Null-Byte
bieten. Das ubliche Uberspringen der fuhrenden Leerraume wird
unterdruckt. Die Zeichenkette soll aus Zeichen in einer (oder
keiner) besonderen Zusammenstellung bestehen; die
Zusammenstellung wird durch die Zeichen zwischen der offnenden [
und schlieBenden ] Klammer definiert. Die Zusammenstellung
schlieBt jene Zeichen aus, wenn das erste Zeichen nach der
offnenden Klammer ein Zirkumflex (^) ist. Um der
Zusammenstellung eine schlieBende Klammer hinzuzufugen, setzen
Sie sie als erstes Zeichen nach der offnenden Klammer oder dem
Zirkumflex; jede andere Position wurde die Zusammenstellung
beenden. Um einen Bindestrich einzufugen, setzen Sie ihn als
letztes Zeichen vor der schlieBenden Klammer am Ende. [^]0-9-]
bedeutet zum Beispiel, die Zusammenstellung >>alles auBer
schlieBender 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 FeldgroBe erschopft ist.
p passt zu einem Zeigerwert (wie durch >>%p<< in printf(3)
ausgegeben); der nachste Zeiger muss ein Zeiger auf void sein.
n es wird nichts erwartet; stattdessen wird die Anzahl der
Zeichen, die bis jetzt eingelesen wurden, im nachsten Zeiger
gespeichert, welcher ein Zeiger auf int sein muss. Dies ist
keine Umwandlung, obwohl sie durch das Zeichen zum Unterdrucken
von Zuweisungen * unterdruckt werden kann. Der C-Standard sagt:
>>Die Ausfuhrung einer %n-Richtlinie erhoht nicht die Anzahl der
Zuweisungen, die bei Fertigstellung der Ausfuhrung zuruckgegeben
werden<<, aber die Berichtigung scheint dem zu widersprechen. Es
ist wahrscheinlich ratsam, keine Annahmen uber die Auswirkungen
von %n-Umwandlungen auf den Ruckgabewert zu treffen.
R"UCKGABEWERT
Diese Funktionen geben die Anzahl der Eingabeelemente zuruck, die
erfolgreich ubereinstimmten und zugewiesen wurden. Dies konnen weniger
sein, als bereitgestellt wurden oder null, wenn ein fruherer Abgleich
scheiterte.
Der Wert EOF wird zuruckgegeben, wenn das Ende der Eingabe erreicht
wird, bevor entweder die erste erfolgreiche Umwandlung oder das erste
Fehlschlagen eines Abgleichs auftrat. EOF wird auch zuruckgegeben, wenn
ein Lesefehler auftritt. In diesem Fall wird die Fehleranzeige fur 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 Leseoperation wurde blocken.
EBADF Der Dateideskriptor, der datenstrom zugrundeliegt, ist ungultig
oder nicht zum Lesen geoffnet.
EILSEQ Eingabebyte-Abfolge bildet kein gultiges 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 wurde die GroBe
uberschreiten, die in dem zugehorigen Ganzzahl-Typ gespeichert
werden konnte.
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 fur long long,
wahrend ll oder die Benutzung von L in Ganzzahlumwandlungen die
GNU-Schreibweise ist.
Die Linuxversion dieser Funktionen basiert auf der GNU-Bibliothek libio
Eine prazisere Beschreibung findet sich in der info-Dokumentation von
GNU libc (glibc-1.08).
ANMERKUNGEN
Die GNU-C-Bibliothek unterstutzt eine nicht standardisierte
Erweiterung, die die Bibliothek veranlasst dynamisch eine Zeichenkette
von ausreichender GroBe fur Eingabezeichenketten und die %s- und
%a[Bereich]-Umwandlungsspezifikationen zu reservieren. Um von dieser
Funktion Gebrauch zu machen, geben Sie als Langenanderungszeichen a an
(also %as oder %a[range]). Der Aufrufende muss die zuruckgegebene
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("gelesen: %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 notig free(3)
aufzurufen, wenn der Aufruf von scanf() eine Zeichenkette erfolgreich
gelesen hat.
Das Anderungszeichen a ist nicht verfugbar, wenn das Programm mit gcc
-std=c99 oder gcc -D_ISOC99_SOURCE kompiliert wurde (auBer wenn auch
_GNU_SOURCE angegeben wurde). In diesem Fall wird a als
Spezifikationssymbol fur FlieBkommazahlen interpretiert (siehe oben).
Seit Version 2.7 stellt Glibc auBerdem das Anderungszeichen m fur den
gleichen Zweck wie das Anderungszeichen a bereit. Das Anderungszeichen
m hat die folgenden Vorteile:
* Es konnte auch auf %c-Umwandlungsspezifikationen angewandt werden
(z.B. %3mc).
* Es vermeidet Mehrdeutigkeit bezuglich der Umwandlungsspezifikation
fur FlieBkommazahlen %a (und wird nicht von gcc -std=c99 etc.
beeinflusst).
* Es ist in der bevorstehenden Uberarbeitung des POSIX.1-Standards
spezifiziert.
FEHLER
Alle Funktionen sind vollkommen konform zu C89, stellen jedoch die
zusatzlichen Spezifikationssymbole q und a sowie ein zusatzliches
Verhalten der Spezifikationssymbole L und l zur Verfugung. Letzteres
kann als Fehler angesehen werden, da es das Verhalten der
Spezifikationssymbole verandert, die in C89 definiert sind.
Einige Kombinationen von Typanderungssymbolen und
Umwandlungsspezifikationen, die durch ANSI-C definiert sind, sind
sinnlos (z.B. %Ld). Wahrend sie ein wohldefiniertes Verhalten unter
Linux haben, braucht dies auf anderen Architekturen nicht der Fall zu
sein. Daher ist es gewohnlich besser Anderungssymbole 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
FlieBkommaumwandlungen aquivalent 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 Veroffentlichung 3.32 des Projekts
Linux-man-pages. Eine Beschreibung des Projekts und Informationen, wie
Fehler gemeldet werden konnen, finden sich unter
http://www.kernel.org/doc/man-pages/.
"UBERSETZUNG
Die deutsche Ubersetzung dieser Handbuchseite wurde von Patrick Rother
<krd@gulu.net> und Chris Leick <c.leick@vollbio.de> erstellt.
Diese Ubersetzung ist Freie Dokumentation; lesen Sie die GNU General
Public License Version 3 oder neuer bezuglich der Copyright-
Bedingungen. Es wird KEINE HAFTUNG ubernommen.
Wenn Sie Fehler in der Ubersetzung dieser Handbuchseite finden,
schicken Sie bitte eine E-Mail an <debian-l10n-
german@lists.debian.org>.