WPRINTF(3)

BEZEICHNUNG
wprintf, fwprintf, swprintf, vwprintf, vfwprintf, vswprintf - Formatierte Ausgabe mit weiten Zeichen

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

BESCHREIBUNG
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 (vergleichen Sie mit der Funktion fwide, um weitere Informationen zu erhalten).

Die Funktionen fwprintf und vfwprintf schreiben ihre Ausgabe als weite Zeichen auf stream. Dazu darf stream nicht byte-orientiert sein (vergleichen Sie mit der Funktion fwide, um weitere Informationen zu erhalten).

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 ebenfalls 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 umgewandelt. Dabei wird jedesmal die Funktion mbrtowc mit einem Umsetzungszustand 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 Breite. -- 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.

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

BEMERKUNGEN
Das Verhalten von wprintf hängt u.a. von LC_TYPE der aktuellen Ländereinstellung 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 speichert 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).

KONFORM ZU
ISO/ANSI C, UNIX98

SIEHE AUCH
printf(3), fprintf(3), snprintf(3), fputwc(3), fwide(3), wscanf(3).