fwscanf(3S) fwscanf(3S)
NAME
fwscanf, wscanf, swscanf - Formatierte Wide-Character-Eingabe
SYNTAX
cc [option ...] datei ... -lw [bibliothek ...]
#include <stdio.h>
#include <wchar.h>
int fwscanf(FILE *stream, const wchart *format, ...);
int wscanf(const wchart *format, ...);
int swscanf(const wchart *s, const wchart *format, ...);
BESCHREIBUNG
Die Funktion fwscanf() liest Eingabe aus dem Stream, auf den stream
zeigt, gesteuert durch den Wide-Character-String, auf den format
zeigt. Diese String gibt die zulässigen Eingabefolgen an sowie die
Art, wie diese für die Zuweisung umzuwandeln sind. Hierbei werden
nachfolgende Argumente als Zeiger auf die Objekte verwendet, in die
die umgewandelte Eingabe geschrieben wird. Wenn nicht genügend Argu-
mente für das Format vorliegen, ist das Ergebnis undefiniert. Ist das
Format bereits ausgeschöpft, obwohl noch Argumente vorhanden sind,
werden diese überzähligen Argumente zwar normal ausgewertet, ansonsten
jedoch ignoriert.
Die Funktion wscanf() entspricht der Funktion fwscanf(), wobei das
Argument stdin vor den Argumenten von wscanf() eingefügt ist.
Die Funktion swscanf() entspricht der Funktion fwscanf(), mit der Aus-
nahme, daß das Argument s einen Wide-Character-String anstelle eines
Streams angibt, aus dem die Eingabe erfolgt. Wenn das Ende des Wide-
Character-Strings erreicht wird, entspricht dies dem Erreichen des
Dateiendes bei der Funktion fwscanf().
Format
Das Format besteht aus null oder mehr Anweisungen, einem oder mehreren
Zwischenraum-Wide-Characters, einem normalen Wide-Character (weder %
noch einem Zwischenraum-Wide-Character) oder aus einer Umwandlungsan-
weisung. Jede Umwandlungsanweisung beginnt mit einem %. Nach dem %
stehen die folgenden Zeichen in der angegebenen Reihenfolge:
- Ein Wide-Character * zur Unterdrückung der Zuweisung (optional).
- Eine ganze Dezimalzahl ungleich Null zur Angabe der maximalen Feld-
größe (als Wide-Character) (optional).
- h, l oder L zur Angabe der Größe des eingehenden Objekts (optio-
nal). Den Umwandlungszeichen c, s und [ muß ein l vorangehen, wenn
das zugehörige Argument ein Zeiger auf wchart anstatt ein Zeiger
auf einen Zeichentyp ist. Den Umwandlungszeichen d, i und n muß
Seite 1 Reliant UNIX 5.44 Gedruckt 11/98
fwscanf(3S) fwscanf(3S)
entweder ein h vorangehen, wenn das zugehörige Argument ein Zeiger
auf short int anstatt auf int ist, oder ein l, wenn es sich bei dem
Argument um einen Zeiger auf long int handelt. Ebenso muß den
Umwandlungszeichen o, u und x entweder ein h vorangehen, wenn das
zugehörige Argument ein Zeiger auf unsigned short int anstatt auf
unsigned int ist, oder ein l, wenn es sich hierbei um einen Zeiger
auf unsigned long int handelt. Schließlich muß den Umwandlungszei-
chen e, f und g entweder ein l vorangehen, wenn das zugehörige
Argument ein Zeiger auf double anstatt auf float ist, oder ein L,
wenn es sich hierbei um einen Zeiger auf long double handelt. Wenn
h, l oder L mit einem anderen Umwandlungszeichen angegeben wird,
ist das Verhalten unbestimmt.
- Ein Wide-Character, das den Typ der anzuwendenden Umwandlung
angibt. Die gültigen Umwandlungszeichen werden weiter unten
beschrieben.
Die Funktion fwscanf() führt jede Anweisung im Format nacheinander
aus. Wenn eine Anweisung (wie weiter unten genauer beschrieben) fehl-
schlägt, kehrt die Funktion fwscanf() zurück. Fehler werden als Einga-
befehler beschrieben (bei einem Codierungsfehler oder wenn Eingabezei-
chen nicht verfügbar sind) oder als Übereinstimmungsfehler (bei ungül-
tiger Eingabe).
Eine Anweisung mit Zwischenraum-Wide-Character(s) wird ausgeführt,
indem die Eingabe bis zum ersten Wide-Character gelesen wird, das kein
Zwischenraumzeichen ist (dieses wird nicht gelesen) oder bis keine
weiteren Wide-Characters mehr gelesen werden können.
Eine Anweisung, die aus einem normalen Wide-Character besteht, wird
ausgeführt, indem das nächste Wide-Character im Stream gelesen wird.
Unterscheidet sich dieses Wide-Character von dem der Anweisung,
schlägt die Anweisung fehl, und das abweichende Wide-Character sowie
alle anderen nachfolgenden Wide-Characters bleiben ungelesen.
Eine Umwandlungsanweisung definiert eine Menge von übereinstimmenden
Eingabe-Strings (wie weiter unten für jedes Umwandlungszeichen
beschrieben). Eine Umwandlungsanweisung wird in den folgenden Schrit-
ten ausgeführt:
Zwischenraum-Wide-Characters in der Eingabe (wie durch die Funktion
iswspace() angegeben) werden übergangen, es sei denn, die Anweisung
enthält das Umwandlungszeichen c oder n. Diese Zwischenraum-Wide-
Characters werden beim Abgleich mit einer angegebenen Feldgröße nicht
berücksichtigt.
Ein Eingabefeld wird aus dem Stream gelesen, sofern die Umwandlung
kein Umwandlungszeichen n enthält. Ein Eingabefeld ist definiert als
die längste Folge von Eingabe-Wide-Characters (bis zu einer angegebe-
nen Feldgröße), die einer passenden Folge bzw. einem Präfix einer sol-
chen Folge entspricht. Das erste Wide-Character (falls vorhanden) nach
dem Eingabefeld bleibt ungelesen. Wenn die Länge des Eingabefelds Null
Seite 2 Reliant UNIX 5.44 Gedruckt 11/98
fwscanf(3S) fwscanf(3S)
ist, schlägt die Ausführung der Anweisung fehl; dies ist ein Überein-
stimmungsfehler, es sei denn, die Eingabe aus dem Strom wurde durch
ein Dateiende, einen Codierungsfehler oder einen Lesevorgang verhin-
dert. In diesem Fall handelt es sich um einen Eingabefehler.
Außer bei dem Umwandlungszeichen % wird das Eingabefeld (oder, bei
einer %n-Anweisung die Zahl der Eingabe-Wide-Characters) in einen dem
Umwandlungszeichen entsprechenden Typ umgewandelt. Handelt es sich bei
dem Eingabefeld nicht um einen passenden String, schlägt die Ausfüh-
rung der Anweisung fehl. Dies ist ein Übereinstimmungsfehler. Sofern
die Zuordnung nicht durch ein * unterdrückt wird, wird das Ergebnis
der Umwandlung in das Objekt geschrieben, auf das das erste Argument
nach dem Formatargument zeigt, für das noch kein Umwandlungsergebnis
vorliegt. Weist dieses Objekt nicht den entsprechenden Typ auf, oder
kann das Ergebnis der Umwandlung in dem vorgegebenen Bereich nicht
dargestellt werden, so ist das Verhalten undefiniert.
Umwandlungszeichen
Folgende Umwandlungszeichen sind gültig:
d Erkennt eine Dezimalzahl, wahlweise mit oder ohne Vorzeichen, die
das gleiche Format hat, wie für den String der Funktion wcstol()
mit dem Wert 10 für das Basisargument erwartet wird. Das entspre-
chende Argument muß ein Zeiger auf eine Ganzzahl sein.
i Erkennt eine Dezimalzahl, wahlweise mit oder ohne Vorzeichen, die
das gleiche Format hat, wie für den String der Funktion wcstol()
mit dem Wert 0 für das Basisargument erwartet wird. Das entspre-
chende Argument muß ein Zeiger auf eine Ganzzahl sein.
o Erkennt eine Oktalzahl, wahlweise mit oder ohne Vorzeichen, die
das gleiche Format hat, wie für den String der Funktion wcstol()
mit dem Wert 8 für das Basisargument erwartet wird. Das entspre-
chende Argument muß ein Zeiger auf eine Ganzzahl ohne Vorzeichen
sein.
u Erkennt eine Dezimalzahl, wahlweise mit oder ohne Vorzeichen, die
das gleiche Format hat, wie für den String der Funktion wcstol()
mit dem Wert 10 für das Basisargument erwartet wird. Das entspre-
chende Argument muß ein Zeiger auf eine Ganzzahl ohne Vorzeichen
sein.
x Erkennt eine Hexadezimalzahl, wahlweise mit oder ohne Vorzeichen,
die das gleiche Format hat, wie für den String der Funktion
wcstol() mit dem Wert 16 für das Basisargument erwartet wird. Das
entsprechende Argument muß ein Zeiger auf eine Ganzzahl ohne Vor-
zeichen sein.
e, f, g
Erkennt eine Gleitkommazahl, wahlweise mit oder ohne Vorzeichen,
die das gleiche Format hat, wie für den String der Funktion
wcstol() erwartet wird. Das entsprechende Argument muß ein Zeiger
Seite 3 Reliant UNIX 5.44 Gedruckt 11/98
fwscanf(3S) fwscanf(3S)
auf eine Gleitkommazahl sein.
s Erkennt einen String aus Nicht-Zwischenraum-Wide-Characters. Wenn
kein l vorhanden ist, werden Zeichen aus dem Eingabefeld so wie
bei wiederholten Aufrufen der Funktion wcrtomb() umgewandelt,
wobei der Umwandlungsstatus durch ein Objekt mbstatet beschrie-
ben wird, das vor der Umwandlung des ersten Wide-Characters auf
Null gesetzt wird. Das entsprechende Argument muß ein Zeiger auf
einen Zeichen-Array sein, der groß genug sein muß, um der String
und ein abschließendes Nullzeichen aufnehmen zu können, das auto-
matisch hinzugefügt wird.
Wenn ein l vorhanden ist, muß das entsprechende Argument ein Zei-
ger auf das erste Element eines Arrays des Typs wchart sein, das
groß genug ist, um den String und ein abschließendes Null-Wide-
Character aufnehmen zu können, das automatisch hinzugefügt wird.
[ Erkennt einen nichtleeren String von Wide-Characters aus einer
Menge erwarteter Zeichen (die Zeichenmenge scanset). Wenn kein l
vorhanden ist, werden Zeichen aus dem Eingabefeld so wie bei wie-
derholten Aufrufen der Funktion wcrtomb() umgewandelt, wobei der
Umwandlungsstatus durch ein Objekt mbstatet beschrieben wird,
das vor der Umwandlung des ersten Wide-Characters auf Null
gesetzt wird. Das entsprechende Argument muß ein Zeiger auf einen
Zeichen-Array sein, der groß genug sein muß, um den String und
ein abschließendes Nullzeichen aufnehmen zu können, das automa-
tisch hinzugefügt wird. Wenn ein l vorhanden ist, muß das ent-
sprechende Argument ein Zeiger auf das erste Element eines Arrays
des Typs wchart sein, das groß genug ist, um den String und ein
abschließendes Null-Wide-Character aufnehmen zu können, das auto-
matisch hinzugefügt wird.
Das Umwandlungszeichen enthält alle nachfolgenden Wide-Characters
im Format-String bis einschließlich dem Wide-Character für die
rechte eckige Klammer (]). Die Wide-Characters zwischen den ecki-
gen Klammern (die Zeichenliste scanlist) umfassen die Zeichen-
menge scanset, sofern das Wide-Character nach der linken eckigen
Klammer kein Zirkumflex (^) ist. In diesem Fall enthält die Zei-
chenmenge scanset alle Wide-Characters, die in der Zeichenmenge
zwischen dem Zirkumflex und der rechten eckigen Klammer stehen.
Wenn die Umwandlungsanweisung mit einem [ ] oder [^] beginnt,
gehört das Wide-Character für die rechte eckige Klammer zur Zei-
chenliste und das Wide-Character für die nächste rechte eckige
Klammer ist die Klammer, die die Anweisung beendet. Andernfalls
beendet das Wide-Character für die erste rechte eckige Klammer
die Anweisung. Wenn in der Zeichenliste ein Wide-Character - ent-
halten ist, wird das Verhalten durch die Implementierung defi-
niert, außer es handelt sich hierbei um das erste Wide-Character
bzw. das zweite nach einem Zirkumflex oder um das letzte Zeichen.
c Erkennt einen String von Wide-Characters mit der Länge, die durch
die Feldgröße angegeben ist (l, wenn in der Anweisung keine
Seite 4 Reliant UNIX 5.44 Gedruckt 11/98
fwscanf(3S) fwscanf(3S)
Feldgröße angegeben ist). Ohne die Angabe l werden Zeichen aus
dem Eingabefeld so wie bei wiederholten Aufrufen der Funktion
wcrtomb() umgewandelt, wobei der Umwandlungsstatus durch ein
Objekt mbstatet beschrieben wird, das vor der Umwandlung des
ersten Wide-Characters auf Null gesetzt wird. Das entsprechende
Argument muß ein Zeiger auf einen Zeichen-Array sein, der groß
genug sein muß, um den String aufnehmen zu können. Es wird kein
Nullzeichen hinzugefügt.
Wenn ein l vorhanden ist, muß das entsprechende Argument ein Zei-
ger auf das erste Element eines Arrays des Typs wchart sein, der
groß genug ist, um den String aufnehmen zu können. Es wird kein
Null-Wide-Character hinzugefügt.
P Erkennt eine durch die Implementierung definierte Menge von
Strings, die der Menge von Strings entsprechen sollte, die durch
die Umwandlung %p der Funktion fwprintf() erstellt werden kann.
Das entsprechende Argument muß ein Zeiger auf einen Zeiger auf
void sein. Die Interpretation des Eingabeelements ist implemen-
tierungsabhängig. Wenn das Eingabeelement ein Wert ist, der
bereits vorher bei derselben Programmausführung umgewandelt
wurde, wird der Ergebniszeiger genau diesem Wert entsprechen;
andernfalls ist das Verhalten der Umwandlung %p nicht definiert.
n Es wird keine Eingabe verarbeitet. Das entsprechende Argument muß
ein Zeiger auf eine Ganzzahl sein, in die die Anzahl der Wide-
Characters geschrieben wird, die bisher durch den Aufruf der
Funktion fwscanf() aus dem Eingabe-Stream gelesen wurden. Die
Ausführung einer Anweisung %n hat keine Auswirkungen auf den
Zuweisungszähler, der nach Beendigung der Ausführung der Funktion
fwscanf() zurückgegeben wird.
% Erkennt ein einzelnes %: eine Umwandlung oder Zuweisung erfolgt
nicht. Die vollständige Umwandlungsanweisung muß %% sein.
Bei einer ungültigen Umwandlungsanweisung ist das Verhalten nicht
definiert.
Die Umwandlungszeichen E, G und X sind ebenfalls gültig und verhalten
sich genau so wie e, g bzw. x.
Wenn das Dateiende während der Eingabe erreicht wird, wird die Umwand-
lung beendet. Wird das Dateiende erreicht, bevor Wide-Characters gele-
sen wurden, die auf die aktuelle Anweisung passen (ausgenommen füh-
rende Zwischenraumzeichen, wo erlaubt), wird die Ausführung der aktu-
ellen Anweisung mit einem Eingabefehler beendet. Andernfalls wird die
Ausführung der nachfolgenden Anweisung (mit Ausnahme der Anweisung %n)
mit einem Eingabefehler beendet, sofern die Ausführung der aktuellen
Anweisung nicht mit einem Übereinstimmungsfehler beendet wird.
Abschließende Zwischenraumzeichen (einschließlich Wide-Characters für
Zeilenvorschub (NL)) bleiben ungelesen, wenn sie nicht mit einer
Seite 5 Reliant UNIX 5.44 Gedruckt 11/98
fwscanf(3S) fwscanf(3S)
Anweisung übereinstimmen. Der Erfolg von Zeichenübereinstimmungen und
unterdrückten Zuweisungen kann nur über die Anweisung %n bestimmt wer-
den.
RÜCKGABEWERT
Die Funktionen fwscanf(), wscanf() und swscanf() geben den Wert des
Makros EOF zurück, wenn ein Eingabefehler noch vor einer Umwandlung
auftritt. Andernfalls geben die Funktionen die Anzahl der zugewiesenen
Eingabefelder zurück, die unter der erwarteten Zahl liegen oder sogar
Null sein kann, wenn ein frühzeitiger Übereinstimmungsfehler aufgetre-
ten ist.
BEISPIELE
1) Der Aufruf:
#include <stdio.h>
#include <wchar.h>
/*...*/
int n, i; float x; wchart name[50];
n = fwscanf(stdin, L"%d%f%ls", &i, &x, name);
mit der Eingabezeile:
25 54.32E-1 thompson
weist n den Wert 3, i den Wert 25, x den Wert 5.432 und name den
String thompson\0 zu.
2) Der Aufruf:
#include <stdio.h>
#include <wchar.h>
/*...*/
int i; float x; double y;
fwscanf(stdin, L"%2d%f%*d %lf", &i, &x, &y);
mit der Eingabe:
56789 0123 56a72
weist i den Wert 56 und x den Wert 789.0 zu, überliest 0123 und weist
y den Wert 56.0 zu. Das nächste Wide-Character, das aus dem Eingabe-
Stream gelesen wird, ist a.
SIEHE AUCH
wcrtomb(3C), wcstod(3C), wcstol(3C), wcstoul(3C), wchar(5).
Seite 6 Reliant UNIX 5.44 Gedruckt 11/98