scanf(3S) scanf(3S)
NAME
scanf, fscanf, sscanf - Formatierte Eingabe
SYNTAX
#include <stdio.h>
int scanf(const char *format, ...);
int fscanf(FILE *stream, const char *format, ...);
int sscanf(const char *s, const char *format, ...);
BESCHREIBUNG
scanf() liest von der Standardeingabe stdin.
fscanf() liest vom angegebenen Eingabe-Stream stream.
sscanf() liest aus dem String s.
Jede dieser Funktionen liest Bytes, interpretiert sie nach dem angege-
benen Format und speichert die Ergebnisse in den jeweiligen Argumen-
ten. Jede Funktion erwartet einen Steuer-String format und eine Menge
von Zeigerargumenten, die angeben, wo die umgewandelte Eingabe gespei-
chert werden soll. Wenn nicht genügend Argumente für das Format vor-
handen sind, ist das Verhalten nicht definiert. Wenn das Format ausge-
schöpft ist und noch Argumente übrig sind, werden die überzähligen
Argumente einfach ignoriert.
Eine in format angegebene Umwandlungsanweisung steuert die Umwandlung
des nächsten Eingabefelds; das Ergebnis wird in die Variable geschrie-
ben, auf die das entsprechende Argument zeigt. Mit * kann die Zuwei-
sung unterdrückt werden, wenn ein Feld übersprungen werden soll. Ein
Eingabefeld wird als String ohne Zwischenraumzeichen definiert; es
erstreckt sich bis zum nächsten nicht passenden Zeichen oder bis zur
maximalen Feldbreite, falls diese angegeben ist.
Umwandlungen können auch auf das nte Argument in der Argumentliste
anstatt auf das nächste noch nicht verwendete Argument angewendet wer-
den. In diesem Fall wird das Umwandlungszeichen % durch die Folge %n$
ersetzt, wobei n eine Dezimalzahl ist, die die Position des Arguments
in der Argumentliste angibt. Das erste Argument %1$ folgt unmittelbar
auf format.
Der Steuer-String kann entweder die Form einer Umwandlungsanweisung,
daß heißt % oder die Form %n$ enthalten; allerdings können beide For-
men nicht innerhalb eines Steuer-Strings gemischt werden. Nur die For-
men %% und %* können mit der Form %n$ gemischt werden.
Der Steuer-String format enthält im allgemeinen Umwandlungsanweisun-
gen, die zur Steuerung der Interpretation von Eingabefolgen verwendet
werden. format setzt sich aus den folgenden Zeichen zusammen:
Seite 1 Reliant UNIX 5.44 Gedruckt 11/98
scanf(3S) scanf(3S)
- Zwischenraumzeichen (Leerzeichen, Tabulatoren, NL-Zeichen (New
Line) oder FF-Zeichen (Form Feed)).
- Normale Zeichen (nicht % und keine Zwischenraumzeichen) bewirken,
daß das nächste Zeichen aus der Eingabe gelesen und mit dem Byte
aus format verglichen wird. Wenn diese nicht übereinstimmen, blei-
ben dieses und die folgenden Bytes ungelesen.
- Umwandlungsanweisungen.
Diese beginnen mit dem Zeichen % oder mit dem String %n$. Danach
wird in der angegebenen Reihenfolge folgendes angegeben:
1. * zur Unterdrückung der Zuweisung (optional)
2. Eine Dezimalzahl ungleich Null, zur Angabe der maximalen Feld-
größe (optional)
3. h, l oder L zur Angabe der Größe des erwarteten Objekts (optio-
nal)
4. Umwandlungszeichen zur Angabe der durchzuführenden Umwandlung
(siehe Erläuterung unten)
Eine Umwandlungsanweisung wird in den folgenden Schritten ausgeführt:
Zwischenraumzeichen (wie von der Funktion isspace() angegeben) werden
ignoriert, es sei denn, die Umwandlungsanweisung enthält das Umwand-
lungszeichen [, c, C oder n. Wenn die Anweisung kein n enthält, wird
ein Eingabefeld gelesen. Ein Eingabefeld ist definiert als die längste
Folge von Eingabebytes (bis zu einer bestimmten maximalen Feldgröße,
die je nach Umwandlungszeichen in Zeichen oder Bytes gerechnet wird),
die die erste Teilfolge einer passenden Folge ist. Das erste Byte
(falls vorhanden) nach dem Eingabefeld bleibt ungelesen. Bei einem
Eingabefeld der Länge Null wird die Umwandlung mit einem Fehler been-
det. Das Eingabefeld wird in einen dem Umwandlungszeichen entsprechen-
den Typ umgewandelt. Wenn das Eingabefeld nicht paßt, wird die Umwand-
lung mit einem Fehler beendet. Wenn die Zuweisung nicht mit * unter-
drückt wurde, wird das Ergebnis der Umwandlung in die Variable
geschrieben, auf die das nächste auf format folgende Argument zeigt.
Wenn dieses Objekt nicht den entsprechenden Typ hat, oder das Ergebnis
der Umwandlung in dem vorhandenen Bereich nicht dargestellt werden
kann, ist das Verhalten undefiniert.
Umwandlungszeichen
Die Umwandlungszeichen werden nacheinander ausgewertet. Wenn eines
dieser Zeichen nicht interpretiert werden kann, kehrt die Funktion mit
einem Fehler zurück. Folgende Umwandlungszeichen sind gültig:
Seite 2 Reliant UNIX 5.44 Gedruckt 11/98
scanf(3S) scanf(3S)
c, lc
Liest einen String der Länge, die durch die Feldgröße angegeben
ist (1, wenn in der Anweisung keine Feldgröße angegeben ist). Das
entsprechende Argument muß ein Zeiger auf das erste Byte eines
Arrays des Typs char, signed char oder unsigned char sein, der
groß genug ist, um den String aufnehmen zu können. Es wird kein
Nullbyte hinzugefügt. Das übliche Überspringen von Zwischenraum-
zeichen wird unterdrückt.
Wenn ein l vorhanden ist, muß die Eingabe eine Folge aus Mehrby-
tezeichenumwandlungen im Anfangsumwandlungsstatus sein. Jedes
Mehrbytezeichen wird wie bei einem Aufruf der Funktion mbrtowc()
in ein Wide-Character umgewandelt, wobei der Umwandlungsstatus
durch ein Objekt mbsstatet beschrieben wird, das vor der Umwand-
lung des ersten Mehrbytezeichens auf Null gesetzt wird. Das ent-
sprechende Argument muß ein Zeiger auf einen Zeichen-Array des
Typs wchart sein, der groß genug ist, um den String und ein
abschließendes Nullzeichen, das automatisch hinzugefügt wird,
aufnehmen zu können.
C Liest einen String der Länge, die durch die Feldgröße angegeben
ist (1, wenn in der Anweisung keine Feldgröße angegeben ist). Der
eingelesene String wird wie mit der Funktion mbstowcs() in eine
Folge von Wide-Characters umgewandelt. Das entsprechende Argument
muß ein Zeiger auf das erste Byte eines Arrays des Typs wchart
sein, der groß genug ist, um das Ergebnis der Umwandlung aufneh-
men zu können. Es wird kein Nullbyte hinzugefügt.
Wenn die Folge im Anfangsumwandlungsstatus beginnt, entspricht
die Umwandlung der Funktion mbwstowcs(); andernfalls ist das Ver-
halten undefiniert. Das übliche Überspringen von Zwischenraumzei-
chen unterbleibt in diesem Fall.
Dieses Umwandlungszeichen wird ab XPG4-Modus unterstützt.
d Liest eine Dezimalzahl, wahlweise mit oder ohne Vorzeichen, die
das gleiche Format hat wie der String der Funktion strtol() mit
dem Wert 10 für das Argument base. Das entsprechende Argument muß
ein Zeiger auf int sein.
e, f, g
Liest eine Gleitkommazahl, wahlweise mit oder ohne Vorzeichen,
die das gleiche Format hat wie der String der Funktion strstr().
Das entsprechende Argument muß ein Zeiger auf float sein.
E Im ANSI-Modus (cc -kansi) verhält sich E genau wie e. Im K&R-
Modus (cc -kcc) verhält sich E genau wie le.
G Im ANSI-Modus (cc -kansi) verhält sich G genau wie g. Im K&R-
Modus (cc -kcc) verhält sich G genau wie lg.
Seite 3 Reliant UNIX 5.44 Gedruckt 11/98
scanf(3S) scanf(3S)
hd, hi, hn
Das entsprechende Argument muß ein Zeiger auf short int anstatt
auf int sein.
ho, hu, hx
Das entsprechende Argument muß ein Zeiger auf unsigned short int
anstatt auf unsigned int sein.
i Liest eine ganze Zahl, wahlweise mit oder ohne Vorzeichen, die
das gleiche Format hat wie der String der Funktion strtol() mit
dem Wert 0 für das Argument base. Das entsprechende Argument muß
ein Zeiger auf int sein.
ld, li, ln
Das entsprechende Argument muß ein Zeiger auf long int anstatt
auf int sein.
lld, llx
Liest eine ganze Zahl, wahlweise mit oder ohne Vorzeichen, die
das gleiche Format hat wie der String der Funktion strtoll() mit
dem Wert 0 für das Argument base. Das entsprechende Argument muß
ein Zeiger auf long long int anstatt auf int sein.
le, lf, lg
Das entsprechende Argument muß ein Zeiger auf double anstatt auf
float sein.
lo, lu, lx
Das entsprechende Argument muß ein Zeiger auf unsigned long int
anstatt auf unsigned int sein.
Le, Lf, Lg
Das entsprechende Argument muß ein Zeiger auf long double sein.
n Es wird keine Eingabe verarbeitet. Das entsprechende Argument muß
ein Zeiger auf int sein, in den die Anzahl der Zeichen geschrie-
ben wird, die bisher durch den Aufruf der Funktion vom Eingabe-
Stream gelesen wurden. Die Ausführung einer Anweisung %n erhöht
nicht den Zuweisungszähler, der bei der Beendigung der Ausführung
der Funktion zurückgegeben wird.
o Liest eine Oktalzahl, wahlweise mit oder ohne Vorzeichen, die das
gleiche Format hat wie der String der Funktion strtol() mit dem
Wert 8 für das Argument base. Das entsprechende Argument muß ein
Zeiger auf unsigned int sein.
Seite 4 Reliant UNIX 5.44 Gedruckt 11/98
scanf(3S) scanf(3S)
p Liest eine Hexadezimalzahl mit dem Wert 16 für das Argument base,
die das gleiche Format hat wie die Menge, die von der Umwandlung
%p der Funktion fprintf() erzeugt werden kann. Das entsprechende
Argument muß ein Zeiger auf void sein. Die Interpretation des
Eingabeelements ist implementierungsabhängig. Wenn das Eingabe-
element ein Wert ist, der bereits vorher bei derselben Program-
mausführung umgewandelt wurde, wird der Ergebniszeiger genau die-
sem Wert entsprechen; andernfalls ist das Verhalten der Umwand-
lung %p nicht definiert.
s, ls
Liest einen String ohne Zwischenraumzeichen. Das entsprechende
Argument muß ein Zeiger auf das erste Byte eines Arrays des Typs
char, signed char oder unsigned char sein, der groß genug ist, um
den String und ein abschließendes Nullbyte, das automatisch hin-
zugefügt wird, aufnehmen zu können.
Wenn ein l vorhanden ist, muß die Eingabe eine Folge aus Mehrby-
tezeichenumwandlungen im Anfangsumwandlungsstatus sein. Jedes
Mehrbytezeichen wird wie bei einem Aufruf der Funktion mbrtowc()
in ein Wide-Character umgewandelt, wobei der Umwandlungsstatus
durch ein ein Objekt mbsstatet beschrieben wird, das vor der
Umwandlung des ersten Mehrbytezeichens auf Null gesetzt wird. Das
entsprechende Argument muß ein Zeiger auf das erste Byte eines
Zeichen-Arrays des Typs wchart sein, der groß genug ist, um den
String und ein abschließendes Nullzeichen, das automatisch hinzu-
gefügt wird, aufnehmen zu können.
S Liest einen String ohne Zwischenraumzeichen. Dieser String wird
wie mit der Funktion mbstowcs() in eine Folge von Wide-Characters
umgewandelt. Das entsprechende Argument muß ein Zeiger auf das
erste Byte eines Arrays des Typs wchart sein, der groß genug
ist, um das Ergebnis der Umwandlung und ein abschließendes Null-
byte, das automatisch hinzugefügt wird, aufnehmen zu können. Wenn
die Feldgröße festgelegt ist, bestimmt sie die maximal akzep-
tierte Anzahl von Zeichen.
Dieses Umwandlungszeichen wird ab XPG4-Modus unterstützt.
u Liest eine Dezimalzahl, wahlweise mit oder ohne Vorzeichen, die
das gleiche Format hat wie der String der Funktion strtol() mit
dem Wert 10 für das Argument base. Das entsprechende Argument muß
ein Zeiger auf unsigned int sein.
x Liest eine Hexadezimalzahl, wahlweise mit oder ohne Vorzeichen,
die das gleiche Format hat wie der String der Funktion strtol()
mit dem Wert 16 für das Argument base. Das entsprechende Argument
muß ein Zeiger auf unsigned int sein.
X Im ANSI-Modus (cc -kansi) verhält sich X genau wie x. Im K&R-
Modus (cc -kcc) verhält sich X genau wie lx.
Seite 5 Reliant UNIX 5.44 Gedruckt 11/98
scanf(3S) scanf(3S)
[, l[
Liest einen nichtleeren String aus einer Menge von erwarteten
Bytes. Das entsprechende Argument muß ein Zeiger auf einen
Zeichen-Array des Typs wchart sein, der groß genug ist, um den
String und ein abschließendes Nullzeichen, das automatisch hinzu-
gefügt wird, aufnehmen zu können. Die Umwandlungsanweisung ent-
hält alle aufeinanderfolgenden Bytes in dem String format, bis
einschließlich der entsprechenden rechten eckigen Klammer ]. Die
Bytes zwischen den eckigen Klammern umfassen die Zeichenmenge,
sofern das Byte nach der linken eckigen Klammer kein Zirkumflex
(^) ist. In diesem Fall enthält die Zeichenmenge alle Bytes, die
nicht zwischen ^ und der rechten eckigen Klammer stehen. Wenn die
Umwandlungsanweisung mit [] oder [^] beginnt, gehört die rechte
eckige Klammer zur Zeichenliste, und die nächste rechte eckige
Klammer ist die Klammer, die die Anweisung beendet. Ansonsten
beendet immer die erste rechte eckige Klammer die Anweisung.
Ein Bereich von Bytes in der Zeichenmenge kann in der Form erstes
- letztes dargestellt werden; so kann [0123456789] auch durch
[0-9] ausgedrückt werden. Bei einer solchen Konstruktion muß
erstes lexikalisch kleiner oder gleich letztes sein, sonst steht
- für sich selbst. Das Zeichen - steht auch immer dann für sich
selbst, wenn es das erste oder letzte Zeichen in der Zeichenliste
ist. Um die eckige rechte Klammer als ein Element der Zeichen-
menge zu erhalten, muß sie als erstes Zeichen (möglicherweise mit
vorangestelltem ^) in der Zeichenliste erscheinen. In diesem Fall
wird die rechte eckige Klammer syntaktisch nicht als schließende
Klammer interpretiert. Es muß zumindest ein Zeichen für diese
Umwandlung passen, damit sie als erfolgreich betrachtet wird.
Wenn ein l vorhanden ist, muß die Eingabe eine Folge aus Mehrby-
tezeichenumwandlungen im Anfangumwandlungsstatus sein. Jedes
Mehrbytezeichen wird wie bei einem Aufruf der Funktion mbrtowc()
in ein Wide-Character umgewandelt, wobei der Umwandlungsstatus
durch ein Objekt mbsstatet beschrieben wird, das vor der Umwand-
lung des ersten Mehrbytezeichens auf Null gesetzt wird. Das ent-
sprechende Argument muß ein Zeiger auf einen Zeichen-Array des
Typs wchart sein, der groß genug ist, um die Folge aus Wide-
Characters aufnehmen zu können. Es wird kein Null-Wide-Character
hinzugefügt.
% Ein einzelnes % wird an dieser Stelle in der Eingabe erwartet; es
erfolgt keine Zuweisung oder Umwandlung. Die vollständige Umwand-
lungsanweisung muß %% sein.
Bei jedem anderen als den aufgeführten Umwandlungszeichen werden h, l
oder L ignoriert.
Wenn auf das % ein ungültiges Umwandlungszeichen folgt, sind die
Ergebnisse der Operation nicht vorhersehbar.
Seite 6 Reliant UNIX 5.44 Gedruckt 11/98
scanf(3S) scanf(3S)
Jede Funktion berücksichtigt die Erkennung eines sprachenabhängigen
Dezimalzeichens im Eingabe-String. Das Dezimalzeichen ist durch die
Umgebung des Programms (LCNUMERIC) definiert. In der C-Umgebung oder
in einer Umgebung, in der das Dezimalzeichen nicht definiert ist, ent-
spricht es standardmäßig dem Punkt.
Die Umwandlung durch scanf() endet am Dateiende, am Ende des Steuer-
String oder wenn ein Eingabezeichen in Konflikt mit dem Steuer-String
gerät.
Wird das Dateiende erreicht, bevor Zeichen gelesen wurden, die auf die
aktuelle Anweisung passen (ausgenommen führende Zwischenraumzeichen,
wo erlaubt), wird die Ausführung der aktuellen Anweisung mit einem
Eingabefehler beendet. Wenn das Dateiende während der Ausführung einer
der nachfolgenden Anweisungen erreicht wird, wird die Umwandlung mit
einem Eingabefehler beendet.
Abschließende Zwischenraumzeichen (einschließlich Zeilenvorschubzei-
chen (NL)) bleiben ungelesen, wenn sie nicht einer Umwandlunsanweisung
entsprechen. Der Erfolg von Zeichenübereinstimmungen und Zuweisungen
kann nur über die Anweisung %n bestimmt werden.
BEISPIELE
Der Aufruf der Funktion scanf():
int i, n; float x; char name[50];
n = scanf("%d%f%s", &i, &x, name);
mit der Eingabezeile:
25 54.32E-1 thompson
weist n den Wert 3, i den Wert 25 und x den Wert 5.432 zu; name ent-
hält den String thompson\0.
Der Aufruf der Funktion scanf():
int i; float x; char name[50];
(void) scanf("%2d%f%*d %[0-9]", &i, &x, name);
mit der Eingabezeile:
56789 0123 56a72
weist i den Wert 56 und x den Wert 789.0 zu, überliest 0123 und legt
die Zeichen 56\0 in name ab. Das nächste von stdin gelesene Zeichen
wird a sein.
Seite 7 Reliant UNIX 5.44 Gedruckt 11/98
scanf(3S) scanf(3S)
RÜCKGABEWERTE
Diese Routinen geben die Anzahl erfolgreich gelesener und zugewiesener
Eingabefelder zurück. Diese Zahl kann null sein, wenn bereits frühzei-
tig ein Konflikt zwischen einem Eingabezeichen und dem Steuer-String
aufgetreten ist. Wenn die Eingabe noch vor dem ersten Konflikt oder
der ersten Umwandlung endet, wird EOF zurückgegeben.
FEHLER
Die folgenden Beschreibungen der Fehlercodes sind funktionsspezifisch.
Eine allgemeingültige Beschreibung finden Sie in introprm2(2) bzw. in
errno(5).
Die Funktion schlägt fehl, wenn Daten gelesen werden müssen und falls:
EAGAIN Das Flag ONONBLOCK für den Dateideskriptor, der stream
zugrundeliegt, ist gesetzt, und der Prozeß wurde beim
Lesevorgang verzögert.
EBADF Der Dateideskriptor, der stream zugrundeliegt, ist kein
gültiger Dateideskriptor, der zum Lesen geöffnet ist.
EINTR Infolge eines Signals wurde die Leseoperation beendet, und
es wurden keine Daten übertragen.
EIO Ein physischer Ein-/Ausgabefehler ist aufgetreten, oder
der Prozeß gehört zu einer Hintergrundprozeßgruppe, welche
von dem kontrollierenden Terminal zu lesen versucht. Ent-
weder ignoriert oder blockiert der Prozeß das Signal
SIGTTIN, oder die Prozeßgruppe des Prozesses ist verwaist.
Dieser Fehler kann auch unter implementationsabhängigen
Bedingungen gemeldet werden.
EOVERFLOW Die Datei ist eine reguläre Datei, und es wurde versucht,
bis hin oder über den maximalen Offset hinaus zu lesen,
der dem entsprechenden Datenstrom zugeordnet ist.
Die Funktion kann fehlschlagen, falls:
EILSEQ Die Engabe-Byte-Sequenz bildet kein gültiges Zeichen.
EINVAL Es sind nicht genügend Argumente vorhanden.
ENOMEM Es ist nur unzureichend Speicherplatz vorhanden.
ENXIO Es wurde eine Anforderung an ein nicht-existierendes Gerät
gemacht bzw. die Anforderung ist außerhalb der Möglichkei-
ten des Geräts.
HINWEISE
Wenn die Anwendung, die fprintf() aufruft, Objekte des Typs wchart
enthält, müssen die Dateien sys/types.h und stddef.h eingebunden wer-
den.
Seite 8 Reliant UNIX 5.44 Gedruckt 11/98
scanf(3S) scanf(3S)
Wenn der Formatsteuer-String Umwandlungsanweisungen der Form % ent-
hält, wird jedes Argument in der Argumentliste genau einmal verwendet.
Die Umwandlungszeichen C und S werden ab XPG4-Modus unterstützt.
SIEHE AUCH
cc(1), strtod(3C), strtol(3C), printf(3S), lfs(5), stdio(5).
Seite 9 Reliant UNIX 5.44 Gedruckt 11/98