SCANF(3)

NAME
scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf - Eingabeformatierung

ÜBERSICHT
#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);

BESCHREIBUNG
Die Funktionenfamilie scanf prüft Eingaben in Bezug auf ein format wie unten beschrieben. Dieses Format darf Umwandlungsspezifikationen enthalten; die Ergebnisse solcher Umwandungen, 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 Argumentliste 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 muß genau zu jedem folgenden Umwandlungsspezifakator passen (siehe `unterdrücken' unten). Jede Umwandlung wird durch das Zeichen % (Prozentzeichen) eingeleitet. Der String format 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).

Umwandlungen
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, daß 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, daß die Umwandlung eine von dioux oder n sein wird, und der nächste Zeiger ein Zeiger auf ein short int (im Gegensatz zu int ) sein wird.

l   Zeigt an, daß 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 daß 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, daß die Umwandlung eine von efg sein wird und der nächste Zeiger ein Zeiger auf ein long double ist, oder daß die Umwandlung eine von dioux sein wird und der nächste Zeiger ein Zeiger auf ein long long sein wird. (Beachte, daß "long long" kein Typ nach ANSI C ist. Jedes Programm, das dies benutzt wird nicht auf alle anderen Architekturen übertragbar sein.)

q   ist äquvalent 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 verarbeitet. Bevor die Umwandlung beginnt übergehen die meisten Umwandungen Leerräume; diese Leerräume zählen nicht gegenüber der Feldgröße.

Die folgenden Umwandlungen sind verfügbar:

%   Findet ein Zeichen `%'. Das heisst, `%%' 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 muß 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 muß ein Zeiger auf int sein. Die Ganzzahl wird eingelesen 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 muß ein Zeiger auf ein unsigned int sein.

u   Findet eine vorzeichenfreie dezimale Ganzzahl; der nächste Zeiger muß ein Zeiger auf ein unsigned int sein.

x   Findet eine vorzeichenfreie hexadezimale Ganzzahl; der nächste Zeiger muß ein Zeiger auf ein unsigned int sein.

X   Äquivalent zu x

f   Findet eine optional vorzeichenbehaftete Fließkommazahl; der nächste Zeiger muß 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 muß Zeiger auf char sein, und das Feld muß 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 muß Zeiger auf char sein und es muß 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 muß 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 werden, die (nicht) in einer bestimmten Menge sind; die Menge wird definniert 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, daß sich nicht in der Menge befindet (oder bei circumflex bei Auftreten eines Zeichens, daß 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 muß 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 muß. Dies ist keine Umwandlung, obwohl sie durch das Flag * unterdrückt werden kann.

RÜCKGABEWERTE
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.

SIEHE AUCH
strtol(3), strtoul(3), strtod(3), getc(3), printf(3).

STANDARDS
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 Bibliothek. Eine konkretere Beschreibung findet sich in der info -Dokumentation von GNU libc (glibc-1.08).

BUGS
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 werden, 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.