.\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" References consulted:
.\"   GNU glibc-2 source code and manual
.\"   Dinkumware C library reference http://www.dinkumware.com/
.\"   OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html
.\"   ISO/IEC 9899:1999
.\"
.\" Translated by Walter Harms <walter.harms@informatik.uni-oldenburg.de>
.\" 2002-02-10: Modified heavily by Martin Schulze <joey@infodrom.org>
.\"
.TH WPRINTF 3  "20. November 1999" "GNU" "Linux Programmer's Manual"
.SH BEZEICHNUNG
wprintf, fwprintf, swprintf, vwprintf, vfwprintf, vswprintf \- Formatierte Ausgabe mit weiten Zeichen
.SH ÜBERSICHT
.nf
.B #include <stdio.h>
.B #include <wchar.h>
.sp
.BI "int wprintf(const wchar_t *" format ", ...);"
.BI "int fwprintf(FILE *" stream ", const wchar_t *" format ", ...);"
.BI "int swprintf(wchar_t *" wcs ", size_t " maxlen ,
.BI "              const wchar_t *" format ", ...);"
.sp
.B #include <stdarg.h>
.sp
.BI "int vwprintf(const wchar_t *" format ", va_list " args );
.BI "int vfwprintf(FILE *" stream ", const wchar_t *" format ", va_list " args );
.BI "int vswprintf(wchar_t *" wcs ", size_t " maxlen ,
.BI "               const wchar_t *" format ", va_list " args );
.fi
.SH 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.
.PP
Die Gruppe der 
.BR wprintf \-Funktionen
ist die Variante für weite Zeichen der
.BR printf \-Funktionen.
Sie produzieren eine formatierte Ausgabe mit weiten Zeichen.
.PP
Die Funktionen
.B wprintf 
und
.B vwprintf
schreiben ihre Ausgabe als weite Zeichen auf
.IR stdout .
Dazu darf
.I stdout
nicht byte-orientiert sein (vergleichen Sie mit der Funktion
.BR fwide ,
um weitere Informationen zu erhalten).
.PP
Die Funktionen
.B fwprintf 
und
.B vfwprintf
schreiben ihre Ausgabe als weite Zeichen auf
.IR stream .
Dazu darf
.I stream
nicht byte-orientiert sein (vergleichen Sie mit der Funktion
.BR fwide ,
um weitere Informationen zu erhalten).
.PP
Die Funktionen
.B swprintf 
und
.B vswprintf
schreiben ihre Ausgabe in ein Array aus weiten Zeichen.
Es ist Aufgabe des Programmierers, dafür zu sorgen, dass mindestens für
.I maxlen
weite Zeichen Platz
in
.I wcs
vorhanden ist.
.PP
Diese Funktionen entsprechen
.BR printf ,
.BR vprintf ,
.BR fprintf ,
.BR vfprintf ,
.B snprintf
und
.B vsprintf
mit den folgenden Änderungen:
.TP
.B \(bu
Die Zeichenkette
.I format
besteht aus weiten Zeichen.
.TP
.B \(bu
Die Ausgabe besteht auch aus weiten Zeichen und nicht aus Bytes.
.TP
.B \(bu
.B swprintf 
und
.B vswprintf
benutzen ein
Argument
.IR maxlen ,
.B sprintf 
und
.B vsprintf
jedoch nicht.
.B snprintf
und
.B vsnprint
verwenden ebenfalls ein solches Argument, doch diese Funktionen geben im
Falle eines Überlaufs nicht -1 zurück. (unter Linux)
.PP
Die Behandlung der Konvertierungszeichen
.B %c
und
.B %s
ist anders:
.TP
.B c
Wenn kein Modifikator
.B l
vorhanden ist, wird das Argument
.I int
durch die Funktion
.B btowc
in weite Zeichen umgewandelt, diese werden geschrieben. 
Ist ein Modifikator
.B l
vorhanden, wird das (weite Zeichen) Argument
.I wint_t
geschrieben.
.TP
.B s
Wenn kein Modifikator
.B l
vorhanden ist, wird ein Argument
.IR "" `` "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
.B 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
.IR "weiten Zeichen" ,
und nicht die Anzahl der 
.I Bytes
oder
.I "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
.B I
vorhanden ist, wird ein Argument
.IR "" `` "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.
.SH "RÜCKGABEWERT"
Die Funktionen geben die Anzahl der geschrieben weiten Zeichen zurück,
ausschließlich der terminierenden weiten Null, im Fall der Funktionen
.B swprintf
und
.BR vswprintf .
Im Fehlerfall wird -1 zurückgegeben.
.SH BEMERKUNGEN
Das Verhalten von
.B wprintf 
hängt u.a. von LC_TYPE der aktuellen Ländereinstellung ab.
.PP
Falls die Zeichenkette
.I 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
.B 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
.I format
in internationalisierten Programmen ausschließlich aus weiten
ASCII-Zeichen bestehen oder während der Laufzeit konstruiert werden
(z.B. durch
.B gettext
oder
.B iconv
gefolgt von einem
.BR mbstows ).
.SH "KONFORM ZU"
ISO/ANSI C, UNIX98
.SH "SIEHE AUCH"
.BR printf (3),
.BR fprintf (3),
.BR snprintf (3),
.BR fputwc (3),
.BR fwide (3),
.BR wscanf (3).