iconv(3C) iconv(3C)
NAME
iconv - Funktion zur Code-Umwandlung
SYNTAX
#include <iconv.h>
sizet iconv(iconvt cd, const char **inbuf, sizet *inbytesleft,
char **outbuf, sizet *outbytesleft);
BESCHREIBUNG
Die Funktion iconv() wandelt die Zeichenfolge aus einem Zeichensatz,
im durch inbuf angegebenen Feld, in eine Folge entsprechender Zeichen
eines anderen Zeichensatzes, im durch outbuf angegebenen Feld, um. Es
werden die Zeichensätze verwendet, die im Aufruf iconvopen() angege-
ben 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 bis zum
Ende des Puffers an, die umgewandelt werden müssen. Das Argument
outbuf zeigt auf eine Variable, die auf das erste verfügbare Byte im
Ausgabe-Puffer zeigt. outbytesleft gibt die Anzahl der verfügbaren
Bytes bis zum Ende des Puffers 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. Ist
der Ausgabe-Puffer nicht groß genug, um die gesamte Reset-Folge auf-
nehmen zu können, schlägt iconv() fehl. errno wird auf E2BIG gesetzt.
Weitere Aufrufe, bei denen inbuf kein Nullzeiger oder Zeiger auf einen
Nullzeiger ist, haben zur Folge, daß die Umwandlung auf dem aktuellen
Zustand des Umwandlungsdeskriptors aufsetzt.
Wenn eine Folge von Eingabe-Bytes im angegebenen Zeichensatz kein gül-
tiges Zeichen ergibt, hält die Umwandlung nach dem zuvor erfolgreich
umgewandelten Zeichen an. Wenn der Eingabe-Puffer mit einem unvoll-
stä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 unmit-
telbar 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 Varia-
ble, 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
Seite 1 Reliant UNIX 5.44 Gedruckt 11/98
iconv(3C) iconv(3C)
zustandsabhängigen Codierungen wird der Umwandlungsdeskriptor aktuali-
siert 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.
Die Funktion iconv() schlägt fehl, wenn:
EILSEQ Die Umwandlung der Eingabe wurde aufgrund 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 aufgrund eines unvollstän-
digen 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.
ERGEBNIS
Die Funktion 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ückgege-
ben. Wenn die gesamte Zeichenkette im Eingabe-Puffer umgewandelt wird,
ist der Wert, auf den inbytesleft zeigt, Null. Wenn die Umwandlung der
Eingabe aufgrund einer der oben angegebenen Bedingungen angehalten
wird, ist der Wert, auf den inbytesleft zeigt, ungleich Null. In die-
sem Fall gibt errno die Fehlerbedingung an. Wenn ein Fehler auftritt,
gibt iconv() (sizet)-1 zurück und setzt errno auf den Fehler.
SIEHE AUCH
iconvclose(3C), iconvopen(3C).
Seite 2 Reliant UNIX 5.44 Gedruckt 11/98