WPRINTF(3) Linux Programmer’s Manual WPRINTF(3)
wprintf, fwprintf, swprintf, vwprintf, vfwprintf, vswprintf - For‐
matierte Ausgabe mit weiten Zeichen
#include <stdio.h>
#include <wchar.h>
int wprintf(const wchar_t *format, ...);
int fwprintf(FILE *stream, const wchar_t *format, ...);
int swprintf(wchar_t *wcs, size_t maxlen,
const wchar_t *format, ...);
#include <stdarg.h>
int vwprintf(const wchar_t *format, va_list args);
int vfwprintf(FILE *stream, const wchar_t *format, va_list args);
int vswprintf(wchar_t *wcs, size_t maxlen,
const wchar_t *format, va_list args);
Im Englischen werden "weite Zeichen" mit "wide characters" bezeichnet.
Im Gegensatz zu herkömmlichen Zeichen werden sie mit mehreren Bytes
kodiert, so dass mehr als 256 unterschiedliche Zeichen zur Verfügung
stehen.
Die Gruppe der wprintf-Funktionen ist die Variante für weite Zeichen
der printf-Funktionen. Sie produzieren eine formatierte Ausgabe mit
weiten Zeichen.
Die Funktionen wprintf und vwprintf schreiben ihre Ausgabe als weite
Zeichen auf stdout. Dazu darf stdout nicht byte-orientiert sein (ver‐
gleichen Sie mit der Funktion fwide, um weitere Informationen zu erhal‐
ten).
Die Funktionen fwprintf und vfwprintf schreiben ihre Ausgabe als weite
Zeichen auf stream. Dazu darf stream nicht byte-orientiert sein (ver‐
gleichen Sie mit der Funktion fwide, um weitere Informationen zu erhal‐
ten).
Die Funktionen swprintf und vswprintf schreiben ihre Ausgabe in ein
Array aus weiten Zeichen. Es ist Aufgabe des Programmierers, dafür zu
sorgen, dass mindestens für maxlen weite Zeichen Platz in wcs vorhanden
ist.
Diese Funktionen entsprechen printf, vprintf, fprintf, vfprintf,
snprintf und vsprintf mit den folgenden Änderungen:
· Die Zeichenkette format besteht aus weiten Zeichen.
· Die Ausgabe besteht auch aus weiten Zeichen und nicht aus Bytes.
· swprintf und vswprintf benutzen ein Argument maxlen, sprintf und
vsprintf jedoch nicht. snprintf und vsnprint verwenden eben‐
falls ein solches Argument, doch diese Funktionen geben im Falle
eines Überlaufs nicht -1 zurück. (unter Linux)
Die Behandlung der Konvertierungszeichen %c und %s ist anders:
c Wenn kein Modifikator l vorhanden ist, wird das Argument int
durch die Funktion btowc in weite Zeichen umgewandelt, diese
werden geschrieben. Ist ein Modifikator l vorhanden, wird das
(weite Zeichen) Argument wint_t geschrieben.
s Wenn kein Modifikator l vorhanden ist, wird ein Argument ‘‘const
char *’’ erwartet, das ein Zeiger auf ein Array von Zeichen ist
(Zeiger auf eine Zeichenkette), die eine Folge aus multibyte-
Zeichen darstellt, beginnend im ursprünglichen "initial shift
state". Zeichen aus dem Feld werden in weite Zeichen umgewan‐
delt. Dabei wird jedesmal die Funktion mbrtowc mit einem Umset‐
zungszustand aufgerufen, beginnend im initialen Zustand vor dem
ersten Byte. Die weiten Zeichen werden bis zum Endcode "Null"
(aber nicht inklusive) geschrieben. Wird eine Genauigkeit
angegeben, so werden nicht mehr weite Zeichen als die angegebene
Anzahl geschrieben. Beachten Sie, dass die Genauigkeit die
Anzahl der weiten Zeichen, und nicht die Anzahl der Bytes oder
screen positions bezeichnet.
Das Feld muss eine "Null" als Endbyte beinhalten, es sei denn,
eine Genauigkeit ist angegeben und diese ist so klein, dass die
Anzahl der weiten Zeichen größer ist, als die vorgesehene Bre‐
ite. -- Wenn der Modifikator I vorhanden ist, wird ein Argument
‘‘const wchar_t *’’ erwartet, das ein Zeiger auf ein Feld von
weiten Zeichen ist. Weite Zeichen von diesem Array werden bis
zum weiten Null-Zeichen geschrieben. (Aber nicht inklusive.)
Wenn eine Genauigkeit angegeben wird, werden nicht mehr als die
angegebene Anzahl von Zeichen geschrieben. Das Feld muss ein
Endzeichen beinhalten, es sei denn, es ist eine Genauigkeit
angegeben, die kleiner oder gleich der Anzahl der weiten Zeichen
in dem Feld ist.
Die Funktionen geben die Anzahl der geschrieben weiten Zeichen zurück,
ausschließlich der terminierenden weiten Null, im Fall der Funktionen
swprintf und vswprintf. Im Fehlerfall wird -1 zurückgegeben.
Das Verhalten von wprintf hängt u.a. von LC_TYPE der aktuellen Ländere‐
instellung ab.
Falls die Zeichenkette format weiten Zeichen enthält, die keine ASCII-
Zeichen sind, wird das Programm nur dann richtig arbeiten, wenn der
LC_CTYPE der Ländereinstellung während der Laufzeit die gleiche ist,
wie der LC_CTYPE während des Kompilierens. Das passiert, weil der
Datentyp wchar_t plattform- und länderabhängig ist. (Die GNU Libc spe‐
ichert weite Zeichen als Unicode (ISO-10646), andere Plattformen haben
andere Lösungen. Auch die Verwendung von ISO C99 "universal character
names" der Form \unnnn helfen nicht.) Daher sollte die Zeichenkette
format in internationalisierten Programmen ausschließlich aus weiten
ASCII-Zeichen bestehen oder während der Laufzeit konstruiert werden
(z.B. durch gettext oder iconv gefolgt von einem mbstows).
ISO/ANSI C, UNIX98
printf(3), fprintf(3), snprintf(3), fputwc(3), fwide(3), wscanf(3).
GNU 20. November 1999 WPRINTF(3)