SCANF(3) Bibliotheksfunktionen SCANF(3)
scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf - Eingabeformatierung
#include <stdio.h>
int scanf( const char *format, ...);
int fscanf( FILE *stream, const char *format, ...);
int sscanf( const char *str, const char *format, ...);
#include <stdarg.h>
int vscanf( const char *format, va_list ap);
int vsscanf( const char *str, const char *format, va_list ap);
int vfscanf( FILE *stream, const char *format, va_list ap);
Die Funktionenfamilie scanf prüft Eingaben in Bezug auf ein format wie
unten beschrieben. Dieses Format darf Umwandlungsspezifikationen
enthalten; die Ergebnisse solcher Umwandlungen, falls vorhanden, werden
durch die pointer -Argumente gespeichert. Die Funktion scanf liest
Eingaben vom Standardeingabekanal stdin, fscanf liest Eingaben von dem
Streamzeiger stream, und sscanf liest ihre Eingaben von dem String, auf
den str zeigt.
Die Funktion vfscanf verhält sich analog zu vfprintf(3) und liest
Eingaben von dem Streamzeiger stream , wobei eine variable Argu‐
mentliste von Zeigern benutzt wird (siehe stdarg(3). Die Funktion
vscanf liest eine variable Argumentliste von der Standardeingabe und
die Funktion vsscanf liest von einem String; diese sind analog zu den
Funktionen vprintf und vsprintf .
Jedes folgende Argument pointer muss genau zu jedem folgenden Umwand‐
lungsspezifakator passen (siehe ‘unterdrücken’ unten). Jede Umwandlung
wird durch das Zeichen % (Prozentzeichen) eingeleitet. Der String for‐
mat darf auch andere Zeichen enthalten. Leerräume (wie Leerzeichen,
Tabulatoren oder Zeilenumbrüche) im String format passen zu einem
Freiraum jeder Größe, eingeschlossen keinem Freiraum, der Eingabe.
Alles andere passt nur zu sich selbst. Einlesen der Daten stoppt, wenn
ein Eingabezeichen nicht zu einem Formatzeichen passt. Einlesen stoppt
auch, wenn die Umwandlung nicht durchgeführt werden kann (siehe unten).
Dem Zeichen % , welches eine Umwandlung einleitet, dürfen einige flag
-Zeichen folgen:
* Unterdrückt Zuordnung. Die folgende Umwandlung wird wie gewohnt
durchgeführt, jedoch wird keine Zeiger benutzt; das Ergebnis der
Umwandlung wird verworfen.
a Zeigt an, dass die Umwandlung s sein wird; der nötige Speicher
für den String wird malloc’t, und der Zeiger darauf wird der
Zeigervariablen char zugeordnet, welche nicht initialisiert zu
werden braucht. Dieses Flag existiert nicht in ANSI C.
h Zeigt an, dass die Umwandlung eine von dioux oder n sein wird,
und der nächste Zeiger ein Zeiger auf ein short int (im Gegen‐
satz zu int ) sein wird.
l Zeigt an, dass die Umwandlung eine von dioux oder n sein wird,
und der nächste Zeiger ein Zeiger auf ein long int (im Gegensatz
zu int ) sein wird, oder dass die Umwandlung eine von efg sein
wird, und der nächste Zeiger ein Zeiger auf ein double (im
Gegensatz zu float ) sein wird. Angabe von zwei Flags l in
äquivalent zum Flag L.
L Zeigt an, dass die Umwandlung eine von efg sein wird und der
nächste Zeiger ein Zeiger auf ein long double ist, oder dass die
Umwandlung eine von dioux sein wird und der nächste Zeiger ein
Zeiger auf ein long long sein wird. (Beachte, dass "long long"
kein Typ nach ANSI C ist. Jedes Programm, das dies benutzt wird
nicht auf alle anderen Architekturen übertragbar sein.)
q ist äquivalent zu L. Dieses Flag existiert nicht in ANSI C.
Zusätzlich zu diesen Flags darf es eine optionale maximale Feldgröße
geben, die als dezimale Ganzzahl zwischen dem % und der Umwandlung
angegeben wird. Wenn keine Größe angegeben ist wird per Vorgabe
‘unendlich’ benutzt (mit einer Ausnahme, siehe unten); anderenfalls
werden höchstens diese Anzahl von Zeichen durch die Umwandlung verar‐
beitet. Bevor die Umwandlung beginnt übergehen die meisten Umwandlun‐
gen Leerräume; diese Leerräume zählen nicht gegenüber der Feldgröße.
Die folgenden Umwandlungen sind verfügbar:
% Findet ein Zeichen ‘%’. Das heißt, ‘%%’ im Formatstring findet
ein einzelnes Zeichnen ‘%’. Es findet keine Umwandlung statt
und Zuweisung tritt nicht auf.
d Findet eine optional verzeichenbehaftete dezimale Ganzzahl; der
nächste Zeiger muss ein Zeiger auf int sein.
D Äquivalent zu ld; dies existiert nur aus Kompatibilitätsgründen.
i Findet eine optional verzeichenbehaftete Ganzzahl; der nächste
Zeiger muss ein Zeiger auf int sein. Die Ganzzahl wird eingele‐
sen zur Basis 16 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 Findet eine vorzeichenfreie oktale Ganzzahl; der nächste Zeiger
muss ein Zeiger auf ein unsigned int sein.
u Findet eine vorzeichenfreie dezimale Ganzzahl; der nächste
Zeiger muss ein Zeiger auf ein unsigned int sein.
x Findet eine vorzeichenfreie hexadezimale Ganzzahl; der nächste
Zeiger muss ein Zeiger auf ein unsigned int sein.
X Äquivalent zu x
f Findet eine optional vorzeichenbehaftete 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
s Findet eine Folge von Zeichen, die keinen Leerraum darstellen;
der nächste Zeiger muss Zeiger auf char sein, und das Feld muss
groß genug sein um die Folge und das abschließende NUL Zeichen
aufzunehmen. Der Eingabestring stoppt an Leerräumen oder an der
maximalen Feldgrößen, je nachdem, was zuerst auftritt.
c Findet eine Folge von width Zeichen (Vorgabe 1); der nächste
Zeiger muss Zeiger auf char sein und es muss genug Platz für
alle Zeichen existieren. (Es wird kein abschließendes NUL
angehängt.) Das gewöhnliche Unterdrücken vor einleitenden
Leerräumen wird unterdrückt. Um Leerräume zu überspringen
benutze explizit ein Leerzeichen im Formatstring.
[ Findet eine nichtleere Folge von Zeichen aus der angegebenen
Menge von zu akzeptierenden Zeichen; der nächste Zeiger muss
Zeiger auf char sein und es muss genug Platz für alle Zeichen
des Strings sein, plus einem abschließenden NUL Zeichen. Das
gewöhnliche Unterdrücken vor einleitenden Leerräumen wird
unterdrückt. Der Strings soll aus Zeichen zusammengesetzt wer‐
den, die (nicht) in einer bestimmten Menge sind; die Menge wird
definiert durch die Zeichen einer öffnenden [ und einer
schließenden ] Klammen. Die Menge schließt diese Zeichen aus
wenn das erste Zeichen nach der öffnenden Klammer ein circumflex
^ ist. Im einer schließende Klammer in der Menge zu haben, gib
sie als erstes Zeichen hinter der öffnenden Klammer oder dem
circumflex an; jede andere Position beendet die Menge. Der
Bindestrich - ist auch ein spezielles Zeichen; wenn er zwischen
zwei anderen Zeichen steht fügt er alle Zeichen zwischen den
beiden zu der Menge hinzu. Um einen Bindestrich zuzufügen, gib
ihn als letztes Zeichen vor der schließenden Klammer an. Zum
Beispiel meint ‘[^]0-9-]’ ‘alles außer schließender Klammen,
Null bis Neun, und Bindestrich’ Der String endet bei Auftreten
eines Zeichens, das sich nicht in der Menge befindet (oder bei
circumflex bei Auftreten eines Zeichens, das sich in der Menge
befindet), oder bei Erreichen der Feldgröße.
p Findet einen Zeigerwert (wie durch ‘%p’ ausgegeben bei
printf(3); der nächste Zeiger muss ein Zeiger auf void sein.
n Nichts wird 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 Umwand‐
lung, obwohl sie durch das Flag * unterdrückt werden kann.
Diese Funktionen geben die Anzahl der zugewiesenen Eingabeelemente
zurück, welche kleiner als gewünscht sein kann, oder auch Null im Fall
einer fehlgeschlagenen Suche. Null zeigt an, dass obwohl Eingabe
verfügbar war, keine Zuweisung erfolgt ist; typischerweise durch
ungültige Eingabezeichen, wie ein alphabetisches Zeichen für eine
Umwandlung %d’. Der Wert EOF wird zurückgegeben wenn ein Eingabefehler
vor einer Umwandlung auftritt, wie z.B. ein Dateiende. Wenn ein Fehler
oder Dateiende auftritt, nachdem eine Umwandlung begonnen hat, wird die
Anzahl der bis dahin erfolgreich umgewandelten Zeichen zurückgegeben.
strtol(3), strtoul(3), strtod(3), getc(3), printf(3).
Die Funktionen fscanf, scanf, und sscanf sind konform zu ANSI
C3.159-1989 (‘‘ANSI C’’).
Das Flag q ist in BSD 4.4 die Notation für long long, während ll oder
die Benutzung von L in Ganzzahlumwandlungen die GNU-Notation ist.
Die Linuxversion dieser Funktionen basiert auf der GNU libio Biblio‐
thek. Eine konkretere Beschreibung findet sich in der info -Dokumenta‐
tion von GNU libc (glibc-1.08).
Alle Funktionen sind vollkommen konform zu ANSI C3.159-1989, stellen
jedoch die zusätzliche Flags q und a , sowie ein zusätzliches Verhalten
der Flags L und l zur Verfügung. Letzteres kann als Bug angesehen wer‐
den, da es das Verhalten der Flags verändert, die in ANSI C3.159-1989
definiert sind.
Einige Kombinationen von Flags, die durch ANSI C definiert sind, machen
in ANSI C keinen Sinn (e.g. %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 Flags zu
benutzen, die gar nicht durch ANSI C definiert sind, d.h. benutze q
anstatt L in Kombination mit Umwandlungen diouxX oder ll.
Die Benutzung von q ist nicht die gleiche wie bei BSD 4.4, da die in
Fließkommaumwandlungen äquivalent zu L benutzt werden kann.
LINUX MANPAGE 3. Januar 1997 SCANF(3)