iconv(3) Library Functions Manual iconv(3) NOM iconv - Conversion de jeux de caracteres BIBLIOTHEQUE Bibliotheque C standard (libc, -lc) SYNOPSIS #include size_t iconv(iconv_t cd, char **restrict inbuf, size_t *restrict inbytesleft, char **restrict outbuf, size_t *restrict outbytesleft); DESCRIPTION La fonction iconv() convertit une sequence de caracteres dans un jeu de caracteres en une sequence de caracteres dans un autre jeu de caracteres. Le parametre cd est un descripteur de conversion (en anglais conversion descriptor), cree prealablement par un appel a iconv_open(3) ; le descripteur de conversion definit les jeux de caracteres qu'iconv() utilise pour cette conversion. Le parametre inbuf est l'adresse d'une variable qui pointe vers le premier caractere de la sequence d'entree ; le parametre outbuf est l'adresse d'une variable qui pointe vers le premier octet disponible dans le tampon de sortie, et outbytesleft indique le nombre d'octets disponibles dans le tampon de sortie. Cette routine est principalement utilisee quand inbuf et *inbuf sont non NULL. Dans ce cas, iconv() convertit la sequence multioctet debutant en *inbuf en une sequence multioctet commencant en *outbuf. Au plus *inbytesleft octets seront lus, en partant de *inbuf. Au plus *outbytesleft octets seront ecrits en commencant en *outbuf. The iconv() function converts one multibyte character at a time, and for each character conversion it increments *inbuf and decrements *inbytesleft by the number of converted input bytes, it increments *outbuf and decrements *outbytesleft by the number of converted output bytes, and it updates the conversion state contained in cd. If the character encoding of the input is stateful, the iconv() function can also convert a sequence of input bytes to an update to the conversion state without producing any output bytes; such input is called a shift sequence. The conversion can stop for five reasons: - Une sequence multioctet invalide a ete trouvee en entree. Dans ce cas, errno est definie a EILSEQ et la fonction renvoie (size_t) -1. Ensuite, *inbuf pointera sur le debut de la sequence multioctet non valable. - Il existe des sequences multioctet qui qui sont correctes mais qui ne peuvent pas etre traduites dans le caractere encodant la sortie. Les conditions dependent de l'implementation et du descripteur de conversion. Dans la bibliotheque C de GNU et libiconv de GNU, si cd a ete cree sans le suffixe //TRANSLIT ou //IGNORE, la conversion est stricte : les conversions avec pertes produisent cette condition. Si le suffixe //TRANSLIT a ete specifiee, la translitteration peut eviter cette condition dans certains cas. Dans la bibliotheque C de musl, cette condition ne peut pas se produire parce qu'une conversion en << * >> est utilisee comme solution de repli. Dans les implementations d'iconv de FreeBSD, NetBSD et Solaris, la condition ne peut pas survenir parce qu'une conversion en << ? >> est utilisee comme solution de repli. Quand cette condition se rencontre, iconv() definit errno a EILSEQ et renvoie (size_t) -1. Ensuite, *inbuf pointera sur le debut de la sequence multioctet non convertible. - La sequence d'entree multioctet a ete convertie entierement, c'est-a-dire que *inbytesleft est descendu jusqu'a zero. Dans ce cas, iconv() renvoie le nombre de conversions irreversibles realisees durant l'appel. - Une sequence multioctet incomplete a ete trouvee alors que la sequence d'entree se terminait. Dans ce cas, errno est definie a EINVAL et la fonction renvoie (size_t) -1. Ensuite, *inbuf pointera sur le debut de la sequence multioctet incomplete. - Le tampon de sortie n'a plus de place pour stocker le prochain caractere converti. Dans ce cas, errno contiendra E2BIG et la fonction renverra (size_t) -1. Une autre possibilite se presente quand inbuf ou *inbuf est NULL, mais si ni outbuf, ni *outbuf ne le sont. Dans ce cas, la fonction iconv() essaye de mettre l'etat de conversion de cd dans l'etat initial, et de memoriser la sequence de decalage correspondante dans *outbuf. Au maximum *outbytesleft octets seront ecrits en commencant en *outbuf. Si le tampon de sortie ne contient pas assez de place pour reinitialiser la sequence, errno est definie a E2BIG et la fonction renvoie (size_t) -1. Sinon, elle augmente *outbuf et diminue *outbytesleft du nombre d'octets ecrits. Un troisieme cas est possible, si inbuf ou *inbuf est NULL, et si outbuf ou *outbuf est NULL. Dans ce cas, la fonction iconv() replace l'etat de conversion cd dans l'etat de conversion initial. VALEUR RENVOYEE La fonction iconv() renvoie le nombre de caracteres convertis de maniere irreversible durant l'appel. Les conversions reversibles ne sont pas prises en compte. En cas d'erreur, iconv() renvoie (size_t) -1 et definit errno pour indiquer l'erreur. ERREURS Les erreurs suivantes peuvent se produire, entre autres : E2BIG Il n'y a pas assez de place dans *outbuf. EILSEQ Une sequence multioctet invalide a ete trouvee en entree. EINVAL Une sequence multioctet incomplete a ete trouvee en entree. ATTRIBUTS Pour une explication des termes utilises dans cette section, consulter attributes(7). +-------------------------+--------------------------+-----------------+ |Interface | Attribut | Valeur | +-------------------------+--------------------------+-----------------+ |iconv() | Securite des threads | MT-Safe race:cd | +-------------------------+--------------------------+-----------------+ La fonction iconv() peut etre appelee par plusieurs << threads >> (MT-Safe) tant que les appelants s'arrangent pour exclure mutuellement l'argument cd. NORMES POSIX.1-2008. HISTORIQUE glibc 2.1. POSIX.1-2001. NOTES Dans chaque serie d'appels a iconv(), le dernier devrait etre celui ayant inbuf ou *inbuf egal a NULL, afin de purger toute entree partiellement convertie. Bien qu'inbuf et outbuf soient declares de type char **, cela ne signifie pas que les objets vers lesquels ils pointent puissent etre interpretes comme des chaines de caracteres C ou comme des tableaux de caracteres ; l'interpretation des sequences d'octets comme caracteres est geree de maniere interne par les fonctions de conversion. Dans certains jeux de caracteres, un octet nul peut etre une partie valide d'un caractere multioctet. Celui qui appelle iconv() doit s'assurer que les pointeurs passes a la fonction permettent d'acceder aux caracteres dans le jeu de caracteres approprie. Il faut en particulier assurer un alignement correct sur les plateformes qui ont des exigences tres strictes en matiere d'alignement. VOIR AUSSI iconv_close(3), iconv_open(3), iconvconfig(8) TRADUCTION La traduction francaise de cette page de manuel a ete creee par Christophe Blaess , Stephan Rafin , Thierry Vignaud , Francois Micaux, Alain Portal , Jean-Philippe Guerard , Jean-Luc Coulon (f5ibh) , Julien Cristau , Thomas Huriaux , Nicolas Francois , Florentin Duneau , Simon Paillard , Denis Barbier , David Prevot , Thomas Vincent et Jean- Pierre Giraud Cette traduction est une documentation libre ; veuillez vous reporter a la GNU General Public License version 3 concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITE LEGALE. Si vous decouvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message a . Pages du manuel de Linux 6.18 8 fevrier 2026 iconv(3)