fwprintf(3S) fwprintf(3S)
NAME
fwprintf, wprintf, swprintf, vfwprintf, vwprintf, vswprintf - Forma-
tierte Wide-Character-Ausgabe
SYNTAX
cc [option ...] datei ... -lw [bibliothek ...]
#include <stdarg.h>
#include <stdio.h>
#include <wchar.h>
int fwprintf(FILE *stream, const wchart *format, ...);
int wprintf(const wchart *format, ...);
int swprintf(wchart *s, sizet n, const wchart *format, ...);
int vfwprintf(FILE *stream, const wchart *format, valist arg);
int vwprintf(const wchart *format, valist arg);
int vswprintf(wchart *s, sizet n, const wchart *format, valist arg);
BESCHREIBUNG
Die Funktion fwprintf() schreibt die Ausgabe auf den Stream stream und
wird dabei durch den Wide-Character-String format gesteuert. format
gibt an, wie nachfolgende Argumente für die Ausgabe umgewandelt werden
sollen. Wenn nicht genügend Argumente 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 in der üblichen Weise ausgewertet, ansonsten jedoch ignoriert.
Die Funktion fwprintf() kehrt zurück, wenn das Ende des Format-String
erreicht ist.
Die Funktion wprintf() entspricht der Funktion fwprintf(), wobei das
Argument stdout vor den Argumenten von wprintf() eingefügt ist.
Die Funktion swprintf() entspricht der Funktion fwprintf(), nur daß
hier die generierte Ausgabe in einen durch das Argument s angegebenen
Array von Wide-Characters und nicht auf einen Stream geschrieben wird.
Es werden maximal n Wide-Characters geschrieben, einschließlich eines
abschließenden Null-Wide-Characters, das immer angefügt wird (sofern n
nicht Null ist).
Die Funktion vfwprintf() entspricht der Funktion fwprintf(), wobei die
variable Argumentliste durch arg ersetzt wird. arg sollte durch das
Makro vastart (und eventuell nachfolgende vaarg-Aufrufe) initiali-
siert worden sein. Die Funktion vfwprintf() ruft nicht das Makro
vaend auf.
Seite 1 Reliant UNIX 5.44 Gedruckt 11/98
fwprintf(3S) fwprintf(3S)
Hinweis:
Da die Funktionen vfwprintf(), vswprintf() und vwprintf() das Makro
vaarg aufrufen, ist der Wert von arg nach Rückkehr der Funktion unbe-
stimmt.
Die Funktion vwprintf() entspricht der Funktion swprintf(), wobei die
variable Argumentliste durch arg ersetzt wird. arg sollte durch das
Makro vastart (und eventuell nachfolgende vaarg-Aufrufe) initiali-
siert worden sein. Die Funktion vwprintf() ruft nicht das Makro vaend
auf.
Die Funktion vswprintf() entspricht der Funktion swprintf(), wobei die
variable Argumentliste durch arg ersetzt wird. arg sollte durch das
Makro vastart (und eventuell nachfolgende vaarg-Aufrufe) initiali-
siert worden sein. Die Funktion vswprintf() ruft nicht das Makro
vaend auf.
Format
Das Format besteht aus null oder mehr Anweisungen: einfache Wide-
Characters (nicht %) und Anweisungen für die Umwandlung. Die Verarbei-
tung der Umwandlungsanweisungen erfolgt so, als würden diese Anweisun-
gen im Format-String durch Wide-Character-Strings ersetzt, die jeweils
aus dem Abrufen (und falls zutreffend dem anschließenden Umwandeln
gemäß der angegebenen Umwandlungsanweisung) von null oder mehr Argu-
menten resultieren. Der erweiterte Wide-Character-Format-String wird
dann auf den Ausgabe-Stream geschrieben.
Jede Umwandlungsanweisung wird durch das Wide-Character % eingeleitet.
Hinter dem Zeichen % erscheinen nacheinander folgende Elemente:
- Null oder mehr flags (in beliebiger Reihenfolge), die die Bedeutung
der Umwandlungsanweisung modifizieren.
- Eine optionale Angabe field width für die Mindestfeldgröße. Wenn
der umgewandelte Wert weniger Wide-Characters als die Feldgröße
hat, wird er links (oder rechts, wenn das weiter unten beschriebene
Flag für linksbündiges Ausrichten angegeben wurde) mit Leerzeichen
(Voreinstellung) bis zur Feldgröße aufgefüllt. Die Feldgröße kann
in Form eines Sterns * (wie unten beschrieben) oder einer Dezimal-
zahl angegeben werden. (Beachten Sie hierbei, daß 0 als ein Flag
und nicht als Anfang einer Feldgröße verwendet wird.)
- Eine optionale Genauigkeitsangabe precision, die die Mindestanzahl
von Ziffern angibt, die bei den Umwandlungen d, i, o, u, x und X
erscheinen sollen, die Anzahl der Ziffern, die hinter einem Dezi-
malpunkt für die Umwandlungen e, E und f angezeigt werden sollen,
die maximale Anzahl signifikanter Ziffern für die Umwandlungen mit
g und G oder die maximale Anzahl Wide-Characters, die bei der s-
Umwandlung aus einem String ausgegeben werden soll. Die Genauigkeit
wird durch einen Punkt (.), gefolgt von einem Stern * (wie unten
beschrieben) oder einer optionalen Dezimalzahl angegeben. Eine
Seite 2 Reliant UNIX 5.44 Gedruckt 11/98
fwprintf(3S) fwprintf(3S)
leere Ziffernfolge wird als Null behandelt. Die Verwendung anderer
Zeichen für die Genauigkeitsangabe führt zu unbestimmten Ergebnis-
sen.
- Ein optionales l gibt an, daß eine nachfolgende Umwandlungsanwei-
sung c für ein wintt-Argument und eine nachfolgende Umwandlungsan-
weisung s auf einen Zeiger auf ein wchart-Argument angewendet
wird.
Ein optionales h gibt an, daß eine nachfolgende Umwandlungsanwei-
sung d, i, o, u, x oder X auf ein Argument short int oder unsigned
short int angewendet wird; (das Argument wird entsprechend den C-
Regeln zur Wertumwandlung für ganze Zahlen unterstützt, und sein
Wert wird vor der Ausgabe in short int oder unsigned short int
umgewandelt); es gibt ferner an, daß eine nachfolgende Umwandlungs-
anweisung n ein Zeiger auf ein short int ist.
Ein optionales l gibt an, daß eine nachfolgende Umwandlungsanwei-
sung d, i, o, u, x oder X auf ein long int- oder unsigned long
int-Argument angewendet wird; es gibt ferner an, daß eine nachfol-
gende Umwandlungsanweisung n auf auf ein long int-Argument angewen-
det wird. Eine Option L gibt an, daß eine nachfolgende Umwandlungs-
anweisung e, E, f, g oder G auf ein long double-Argument angewendet
wird.
Wenn h, l oder L mit einer anderen Umwandlungsanweisung angegeben
wird, ist das Ergebnis unbestimmt.
- Ein Wide-Character, das den Typ der anzuwendenden Umwandlung
angibt.
Wie oben bereits erwähnt, kann eine Feldgröße und/oder Genauigkeit
auch durch einen Stern * angezeigt werden. In diesem Fall gibt ein
ganzzahliges Argument (int) die Feldgröße bzw. die Genauigkeit an. Die
Argumente, die Feldgröße und/oder Genauigkeit angeben, müssen (in die-
ser Reihenfolge) vor dem umzuwandelnden Argument (falls vorhanden)
stehen. Ein negatives Argument für die Feldgröße wird als ein Flag -
gefolgt von einer positiven Feldgröße interpretiert. Ein negatives
Argument für die Genauigkeit wird so interpretiert, als wäre keine
Genauigkeit angegeben.
Flags
Die Wide-Character-Flags und ihre Bedeutungen:
- Das Ergebnis der Umwandlung wird linksbündig im Feld ausgegeben.
(Ohne Angabe dieses Flags wird es rechtsbündig ausgegeben.)
+ Das Ergebnis einer Umwandlung mit Vorzeichen beginnt immer mit
einem Vorzeichen (+ oder -). (Ohne Angabe dieses Flags beginnt es
nur dann mit einem Vorzeichen, wenn ein negativer Wert umgewan-
delt wird.)
Seite 3 Reliant UNIX 5.44 Gedruckt 11/98
fwprintf(3S) fwprintf(3S)
space
Wenn das erste Wide-Character einer Umwandlung mit Vorzeichen
kein Vorzeichen ist, oder wenn eine Umwandlung mit Vorzeichen als
Ergebnis keine Wide-Characters aufweist, wird vor dem Ergebnis
ein Leerzeichen eingefügt. Wenn das Flag space zusammen mit dem
Flag + auftritt, wird das Flag space ignoriert.
# Das Ergebnis soll in eine andere Form umgewandelt werden. Bei einer
Umwandlung mit o wird die Genauigkeit erhöht, um zu erzwingen, daß
die erste Ziffer des Ergebnisses eine Null ist (falls erforder-
lich). Für eine Umwandlung mit x (oder X) wird einem Ergebnis, das
ungleich null ist, ein Ox (oder 0X) vorangestellt. Für Umwandlungen
mit e, E, f, g und G enthält das Ergebnis immer ein Wide-Character
für den Dezimalpunkt, selbst wenn diesem Zeichen keine Ziffern mehr
folgen. (Normalerweise erscheint im Ergebnis dieser Unmwandlungen
nur dann ein Wide-Character für den Dezimalpunkt, wenn diesem Zei-
chen noch eine Ziffer folgt.) Bei Umwandlungen mit g und G werden
abschließende Nullen nicht aus dem Ergebnis gestrichen. Bei anderen
Umwandlungen ist das Ergebnis unbestimmt.
0 Bei Umwandlungen mit d, i, o, u, x, X, e, E, f, g und G werden
führende Nullen (die einer beliebigen Vorzeichen- oder Basisan-
gabe folgen) verwendet, um auf die Feldgröße aufzufüllen; für das
Auffüllen werden keine Leerzeichen verwendet. Wenn die Flags 0
und - zusammen angegeben werden, wird das Flag 0 ignoriert. Bei
Umwandlungen mit d, i, o, u, x und X wird das Flag 0 ignoriert,
wenn eine Genauigkeitsangabe vorhanden ist. Bei anderen Umwand-
lungen ist das Ergebnis unbestimmt.
Umwandlungsanweisungen
Die Umwandlungsanweisungen und ihre Bedeutungen:
d, i Das Argument des Typs int wird in einen dezimalen Wert mit Vor-
zeichen der Form [-]dddd umgewandelt. Die Genauigkeit gibt die
Mindestanzahl der auszugebenden Ziffern an. Wenn der umgewandelte
Wert mit weniger Ziffern angezeigt werden kann, wird er mit füh-
renden Nullen erweitert. Die Voreinstellung für die Genauigkeit
ist 1. Die Umwandlung eines Nullwerts mit einer Genauigkeit von
Null ergibt kein Wide-Character.
o, u, x, X
Das Argument des Typs unsigned int wird in eine oktale Darstel-
lung ohne Vorzeichen (o), eine dezimale Darstellung ohne Vorzei-
chen (u) oder eine hexadezimale Darstellung ohne Vorzeichen (u)
(oder X) in der Form dddd umgewandelt. Die Buchstaben abcdef wer-
den für eine x-Umwandlung und die Buchstaben ABCDEF für eine X-
Umwandlung verwendet. Die Genauigkeit gibt die Mindestanzahl der
auszugebenden Ziffern an. Wenn der umgewandelte Wert mit weniger
Ziffern angezeigt werden kann, wird er mit führenden Nullen
erweitert. Die Voreinstellunfg für die Genauigkeit ist 1. Die
Umwandlung eines Nullwerts mit einer Genauigkeit von Null ergibt
kein Wide-Character.
Seite 4 Reliant UNIX 5.44 Gedruckt 11/98
fwprintf(3S) fwprintf(3S)
f Das Argument des Typs double int wird in eine dezimale Darstel-
lung in der Form [-]ddd.ddd umgewandelt, wobei die Anzahl der
Ziffern nach dem Wide-Character für den Dezimalpunkt der Genauig-
keitsangabe entspricht. Wenn die Genauigkeitsangabe fehlt, werden
6 Ziffern ausgegeben. Wenn die Genauigkeit Null und das Flag #
nicht angegeben ist, wird kein Wide-Character für den Dezimal-
punkt ausgegeben. Wenn ein Wide-Character für den Dezimalpunkt
ausgegeben wird, erscheint zumindest eine Zahl vor dem Punkt. Der
Wert wird auf die entsprechende Anzahl Ziffern gerundet.
e, E Das Argument des Typs double wird in der Form [-]d.ddde±dd umge-
wandelt, wobei eine Ziffer vor dem Wide-Character für den Dezi-
malpunkt steht (und zwar ist diese Ziffer ungleich null, wenn das
Argument ungleich null ist) und die Anzahl der Ziffern nach dem
Wide-Character für den Dezimalpunkt der Genauigkeit entspricht.
Wenn die Genauigkeitsangabe fehlt, werden 6 Ziffern ausgegeben.
Wenn die Genauigkeit null und das Flag # nicht angegeben ist,
wird kein Wide-Character für den Dezimalpunkt ausgegeben. Der
Wert wird auf die entsprechende Anzahl Ziffern gerundet. Die
Umwandlungsanweisung E erzeugt eine Zahl mit E anstatt mit e vor
dem Exponenten. Der Exponent enthält immer mindestens zwei Zif-
fern. Wenn der Wert null ist, ist auch der Exponent null.
g, G Das Argument des Typs double wird in der Form f oder e (bezie-
hungsweise in der Form E im Falle der Umwandlungsanweisung G)
umgewandelt. Die Genauigkeit gibt die Anzahl der signifikanten
Stellen an. Wenn die Genauigkeit null ist, wird eine Stelle aus-
gegeben. Die verwendete Form hängt von dem umgewandelten Wert ab.
e (oder E) wird nur verwendet, wenn der aus der Umwandlung resul-
tierende Exponent kleiner als -4 oder größer oder gleich der
Genauigkeitsangabe ist. Abschließende Nullen werden aus dem
gebrochenen Teil des Ergebnisses entfernt. Ein Wide-Character für
den Dezimalpunkt erscheint nur dann, wenn ihm eine Ziffer folgt.
c Wenn keine Angabe l vorliegt, wird das Argument des Typs int in
ein Wide-Character wie bei einem Aufruf btowc() umgewandelt und
ausgegeben. Andernfalls wird der Typ wintt des Arguments in den
Typ wchart umgewandelt und ausgegeben.
s Wenn keine Angabe l vorliegt, wird das Argument als ein Zeiger
auf einen Zeichen-Array mit Mehrbytefolge beginnend im Anfangsum-
wandlungsstatus interpretiert. Zeichen aus dem Array werden wie
bei einem wiederholten Aufruf der Funktion mbrtowc() umgewandelt,
wobei der Umwandlungsstatus durch ein Objekt mstatet beschrieben
wird, das vor der Umwandlung des ersten Mehrbytezeichens auf Null
gesetzt und bis (aber nicht einschließlich) zum abschließenden
Null-Wide-Character geschrieben wird. Wenn die Genauigkeit ange-
geben ist, werden nicht mehr als die angegebenen Wide-Characters
geschrieben. Wenn die Genauigkeit nicht angegeben oder größer als
der umgewandelte Array ist, enthält der umgewandelte Array ein
Null-Wide-Character.
Seite 5 Reliant UNIX 5.44 Gedruckt 11/98
fwprintf(3S) fwprintf(3S)
Wenn eine Angabe l vorliegt, wird das Argument als ein Zeiger auf
einen wchart-Array interpretiert. Wide-Characters aus dem Array
werden bis (aber nicht einschließlich) zu einem abschließenden
Null-Wide-Character geschrieben. Wenn die Genauigkeit angegeben
ist, werden nicht mehr als die festgelegte Anzahl Wide-Characters
geschrieben. Wenn die Genauigkeit nicht angegeben oder größer als
der umgewandelte Array ist, enthält der umgewandelte Array ein
Null-Wide-Character.
P Das Argument ist ein Zeiger auf void. Der Wert des Zeigers wird
in eine implementierungsabhängige Folge von druckbaren Wide-
Characters umgewandelt.
n Das Argument ist ein Zeiger auf eine Ganzzahl, in die die Anzahl
der Wide-Characters geschrieben wurde, die bisher durch diesen
Aufruf von fwprintf() auf den Ausgabe-Stream geschrieben wurden.
Kein Argument wird umgewandelt.
% Ein %-Wide-Character wird geschrieben. Kein Argument wird umge-
wandelt. Die vollständige Umwandlungsanweisung lautet %%.
Wenn die Umwandlungsanweisung ungültig ist, ist das Verhalten unbe-
stimmt.
Wenn ein Argument eine Union- oder eine Aggregatfunktion ist oder auf
eine solche zeigt (mit Ausnahme eines Arrays des Typs char mit Umwand-
lung %s, eines Arrays des Typs chart mit Umwandlung %ls oder eines
Zeigers mit Umwandlung %p), ist das Verhalten unbestimmt.
In keinem Fall bewirkt eine nicht vorhandene oder kleine Feldgröße,
daß ein Feld abgeschnitten wird. Wenn das Ergebnis einer Umwandlung
größer als die Feldgröße ist, wird das Feld entsprechend, um das
Ergebnis aufnehmen zu können.
RÜCKGABEWERT
Die Funktionen fwprintf(), wprintf(), vfwprintf() und vwprintf() geben
die Anzahl der übertragenen Wide-Characters. Wenn ein Ausgabefehler
aufgetreten ist, wird einen negativer Wert zurückgegeben.
Die Funktionen swprintf() und vswprintf() geben die Anzahl der Wide-
Characters zurück, die in den Array geschrieben wurden, ohne das
abschließende Null-Wide-Character. Wenn n oder mehr Wide-Characters
geschrieben werden sollten, wird ein negativer Wert zurückgegeben.
HINWEISE
Der Mindestwert für die maximale Anzahl Wide-Characters, die durch
eine einzelne Umwandlung erzeugt werden, ist 509.
BEISPIELE
Die Ausgabe von Datum und Uhrzeit im Format "Sunday, July 3, 10:02"
bei einer Ausgabe von pi bis auf fünf Dezimalstellen genau erzielen
Sie folgendermaßen:
Seite 6 Reliant UNIX 5.44 Gedruckt 11/98
fwprintf(3S) fwprintf(3S)
#include <math.h>
#include <stdio.h>
#include <wchar.h>
/* ... */
wchart *weekday, *month; /* pointers to wide string */
int day, hour, min;
fwprintf(stdout, L"%ls, %ls %d, %.2d:%.2d\n",
weekday, month, day, hour, min);
fwprintf(stdout, l"pi = %.5f\n", 4 * atan(1.0));
SIEHE AUCH
btowc(3C), mbrtowc(3C), stdarg(5), stdio(5), wchar(5).
Seite 7 Reliant UNIX 5.44 Gedruckt 11/98