#include <iconv.h> size_t iconv(iconv_t cd, char **inbuf, size_t *inbytesleft, char **outbuf, size_t *outbytesleft);
Cette routine est principalement quand inbuf et *inbuf sont non-NULL. Dans ce cas, iconv() convertit la séquence multi-octets débutant en *inbuf en une séquence multi-octets commençant en *outbuf. Au plus *inbytesleft octets seront lus, en partant de *inbuf. Au plus *outbytesleft octets seront écrits en commençant en *outbuf.
La fonction iconv() convertit un caractère multi-octet à la fois; Pour chaque conversion elle augmente *inbuf et diminue *inbytesleft du nombre d'octets d'entrée convertis, et elle augmente *outbuf et diminue *outbytesleft du nombre d'octets de sortie écrits. Elle met à jour l'état de conversion contenu au sein de cd. La conversion peut s'arrêter pour quatre raisons :
1. Une séquence multi-octets invalide a été trouvée en entrée. Dans ce cas, la fonction renvoie (size_t) -1 après avoir mis EILSEQ dans errno. Ensuite, *inbuf pointera sur le début de la séquence multi-octets invalide.
2. La séquence d'entrée multi-octets a été convertie entièrement, c'est-à-dire que *inbytesleft est descendu jusqu'à zéro. Dans ce cas, iconv() renvoie le nombre de conversions irréversibles réalisées durant l'appel.
3. Une séquence multi-octets incomplète a été trouvée alors que la séquence d'entrée se terminait. Dans ce cas, la fonction renvoie (size_t) -1 après avoir mis EINVAL dans errno. Ensuite, *inbuf pointera sur le début de la séquence multi-octets incomplète.
4. Le tampon de sortie n'a plus de place pour stocker le prochain caractère converti. Dans ce cas, errno contiendra E2BIG et la fonction renverra (size_t) -1.
Une autre possibilité se présente quand inbuf ou *inbuf est NULL, mais ni outbuf, ni *outbuf ne le sont. Dans ce cas, la fonction iconv() essaye de mettre l'état de conversion de cd dans l'état initial, et de mémoriser la séquence de décalage correspondante dans *outbuf. Au maximum *outbytesleft octets seront écrits en commençant en *outbuf. Si le tampon de sortie ne contient pas assez de place pour réinitialiser la séquence, la fonction renvoie (size_t) -1 après avoir mis E2BIG dans errno. Sinon, elle augmente *outbuf et diminue *outbytesleft du nombre d'octets écrits.
Un troisième cas est possible, si inbuf ou *inbuf est NULL, et outbuf ou *outbuf est NULL. Dans ce cas, la fonction iconv() replace l'état de conversion cd dans l'état de conversion initial.
Ce document est une traduction réalisée par Christophe Blaess <http://www.blaess.fr/christophe/> le 31 août 2000 et révisée le 17 juillet 2008.
L'équipe de traduction a fait le maximum pour réaliser une adaptation française de qualité. La version anglaise la plus à jour de ce document est toujours consultable via la commande : « LANG=C man 3 iconv ». N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.
Dernière mise à jour : 17 juillet 2008