iconv - Zeichen umwandeln

Definition	#include <iconv.h> size_t iconv(iconv_t cd, const char **inbuf, size_t *inbytesleft, char **outbuf, size_t *outbytesleft);
Beschreibung	iconv() wandelt eine Zeichenfolge eines Zeichensatzes in eine entsprechende Zeichenfolge eines anderen Zeichensatzes um. Die Ausgangszeichenfolge steht im durch inbuf angegebenen Feld, die umgewandelte Zeichenfolge wird in das durch outbuf angegebene Feld abgelegt. Es werden die Zeichensätze verwendet, die im Aufruf iconv_open() angegeben sind, der den Umwandlungsdeskriptor cd zurückgegeben hat. Das Argument inbuf zeigt auf eine Variable, die auf das erste Zeichen im Eingabe-Puffer zeigt. inbytesleft gibt die Anzahl der Bytes an, die umgewandelt werden müssen. Das Argument outbuf zeigt auf eine Variable, die auf das erste Byte im Ausgabe-Puffer zeigt; outbytesleft gibt die Anzahl der Bytes an. Bei zustandsabhängigen Codierungen wird der Umwandlungsdeskriptor cd durch einen Aufruf, für den inbuf ein Nullzeiger ist oder für den inbuf auf einen Nullzeiger zeigt, in den ursprünglichen Shift-Zustand versetzt. Wenn iconv() so aufgerufen wird, outbuf kein Nullzeiger oder Zeiger auf einen Nullzeiger ist und outbytesleft auf einen positiven Wert zeigt, bringt iconv() die Bytefolge in den Ausgabe-Puffer, um den Ausgabe-Puffer in den ursprünglichen Shift-Zustand zu versetzen. Wenn der Ausgabe-Puffer nicht groß genug ist, um die gesamte Reset-Folge aufnehmen zu können, schlägt iconv() fehl. errno wird auf E2BIG gesetzt. Weitere Aufrufe, bei denen inbuf kein Nullzeiger oder kein Zeiger auf einen Nullzeiger ist, haben zur Folge, dass die Umwandlung auf dem aktuellen Zustand des Umwandlungsdeskriptors aufsetzt. Wenn eine Folge von Eingabe-Bytes im angegebenen Zeichensatz kein gültiges Zeichen ergibt, hält die Umwandlung nach dem zuvor erfolgreich umgewandelten Zeichen an. Wenn der Eingabe-Puffer mit einem unvollständigen Zeichen oder einer unvollständigen Shift-Sequenz endet, so hält die Umwandlung nach den zuvor erfolgreich umgewandelten Bytes an. Wenn der Ausgabe-Puffer nicht ausreichend groß ist, um die gesamte, umgewandelte Eingabe aufnehmen zu können, hält die Umwandlung unmittelbar vor den Eingabe-Bytes an, die einen Überlauf des Ausgabe-Puffers zur Folge hätten. Die Variable, auf die inbuf zeigt, wird aktualisiert und zeigt dann auf das Byte nach dem letzten in der Umwandlung erfolgreich verwendeten Byte. Der Wert, auf den inbytesleft zeigt, wird verringert und gibt die Anzahl der Bytes an, die sich noch im Eingabe-Puffer befinden und noch nicht umgewandelt sind. Die Variable, auf die outbuf zeigt, wird aktualisiert und zeigt dann auf das Byte nach dem letzten Byte mit umgewandelten Ausgabedaten. Der Wert, auf den outbytesleft zeigt, wird verringert und gibt dann die Anzahl der Bytes an, die noch im Ausgabe-Puffer zur Verfügung stehen. Bei zustandsabhängigen Codierungen wird der Umwandlungsdeskriptor aktualisiert und gibt dann den Shift-Zustand an, der am Ende der letzten erfolgreich umgewandelten Bytefolge gültig ist. Wenn iconv() im Eingabe-Puffer ein Zeichen findet, das zwar gültig ist, für das es aber im Ziel-Zeichensatz kein entsprechendes Zeichen gibt, führt iconv() für dieses Zeichen eine implementierungsabhängige Umwandlung aus.
Returnwert	iconv() aktualisiert die Variablen, auf die die Argumente zeigen. Diese geben dann das Ausmaß der Umwandlung an. Es wird die Anzahl der durchgeführten, nicht-identischen Umwandlungen zurückgegeben. Wenn die gesamte Zeichenkette im Eingabe-Puffer umgewandelt wird, ist der Wert, auf den inbytesleft zeigt, null. Wenn die Umwandlung der Eingabe auf Grund einer der oben angegebenen Bedingungen angehalten wird, ist der Wert, auf den inbytesleft zeigt, ungleich null. In diesem Fall gibt errno die Fehlerbedingung an. Wenn ein Fehler auftritt, gibt iconv() (size_t)-1 zurück und setzt errno, um den Fehler anzuzeigen.
Fehler	iconv() schlägt fehl, wenn gilt:
	EILSEQ	Die Umwandlung der Eingabe wurde auf Grund eines Eingabe-Bytes angehalten, das nicht zum Eingabe-Zeichensatz gehört.
	E2BIG	Die Umwandlung der Eingabe wurde angehalten, weil im Ausgabe-Puffer nicht genügend Platz zur Verfügung steht.
	EINVAL	Die Umwandlung der Eingabe wurde auf Grund eines unvollständigen Zeichens oder einer unvollständigen Shift-Sequenz am Ende des Eingabe-Puffers angehalten.
	EBADF	Das Argument cd ist kein gültiger Umwandlungsdeskriptor für eine offene Datei.
Siehe auch	iconv_open(), iconv_close(), iconv.h.