iconv

Syntaxe

Paramètres

Retour

La fonction iconv renvoie le nombre de caractères convertis de manière irréversible lors de cet appel ; les conversions réversibles ne sont pas comptabilisées. En cas d'erreur, elle définit errno et renvoie (size_t)(-1).

Description

Cette fonction permet d'effectuer une conversion d'ensemble de caractères.

Remarques

• Le paramètre cd doit être un descripteur de conversion créé à l'aide de la fonction iconv_open.
• Le cas principal est lorsque inbuf et *inbuf ne sont pas NULL. Dans ce cas, la fonction iconv convertit la séquence multi-octets commençant à *inbuf en une séquence multi-octets commençant à *outbuf. Au plus *inbytesleft octets, commençant à *inbuf, seront lus. Au plus *outbytesleft octets, commençant à *outbuf, seront écrits.
• La fonction iconv convertit un caractère multi-octet à la fois. Pour chaque conversion de caractère, elle incrémente *inbuf et décrémente *inbytesleft du nombre d'octets d'entrée convertis, elle incrémente *outbuf et décrémente *outbytesleft du nombre d'octets de sortie convertis, et elle met à jour l'état de conversion contenu dans cd. Si l'encodage des caractères de l'entrée est avec état, la fonction iconv peut également convertir une séquence d'octets d'entrée en une mise à jour de l'état de conversion sans produire d'octets de sortie ; une telle entrée est appelée séquence de décalage. La conversion peut s'arrêter pour cinq raisons :
• Une séquence multi-octets invalide est détectée en entrée. Dans ce cas, elle définit errno à EILSEQ et renvoie (size_t)(?1). *inbuf pointe vers le début de la séquence multi-octets invalide.
• Une séquence multi-octets valide est détectée, mais ne peut être traduite en l'encodage des caractères de la sortie. Cette condition dépend de l'implémentation et du descripteur de conversion. Dans la bibliothèque GNU C et GNU libiconv, si cd a été créé sans le suffixe //TRANSLIT, //IGNORE ou //NON_IDENTICAL_DISCARD, la conversion est stricte : les conversions avec perte produisent cette condition. Si le suffixe //TRANSLIT a été spécifié, la translittération peut éviter cette condition dans certains cas. Dans la bibliothèque C musl, cette condition ne peut pas se produire, car une conversion vers «*» est utilisée comme solution de repli. Dans les implémentations FreeBSD, NetBSD et Solaris d'iconv, cette condition ne peut pas non plus se produire, car une conversion vers «?» est utilisée comme solution de repli. Lorsque cette condition est remplie, la fonction iconv définit errno à EILSEQ et renvoie (size_t)(-1). *inbuf pointe vers le début de la séquence multi-octets non convertible.
• La séquence d'octets d'entrée a été entièrement convertie, c'est-à-dire que *inbytesleft est passé à 0. Dans ce cas, iconv renvoie le nombre de conversions irréversibles effectuées lors de cet appel.
• Une séquence multi-octets incomplète est détectée en entrée, et la séquence d'octets d'entrée se termine après celle-ci. Dans ce cas, elle définit errno à EINVAL et renvoie (size_t)(-1). *inbuf pointe vers le début de la séquence multi-octets incomplète.
• Le tampon de sortie n'a plus de place pour le prochain caractère converti. Dans ce cas, errno est défini sur E2BIG et renvoie (size_t)(-1).
• Un autre cas se présente lorsque inbuf est NULL ou *inbuf est NULL, mais que outbuf et *outbuf ne sont pas NULL. Dans ce cas, la fonction iconv tente de rétablir l'état de conversion de cd à son état initial et de stocker une séquence de décalage correspondante dans *outbuf. Au maximum *outbytesleft octets, à partir de *outbuf, seront écrits. Si le tampon de sortie n'a plus de place pour cette séquence de réinitialisation, errno est défini sur E2BIG et renvoie (size_t)(-1). Sinon, elle incrémente *outbuf et décrémente *outbytesleft du nombre d'octets écrits.
• Un troisième cas se présente lorsque inbuf est NULL ou *inbuf est NULL, et que outbuf est NULL ou *outbuf est NULL. Dans ce cas, la fonction iconv rétablit l'état initial de conversion de cd.
• Dans chaque série d'appels à la fonction iconv, le dernier doit être un appel avec inbuf ou *inbuf égal à NULL, afin de terminer la conversion de toute entrée partiellement convertie.
• Bien que inbuf et outbuf soient typés respectivement const char ** et char **, cela ne signifie pas que les objets qu'ils pointent peuvent être interprétés comme des chaînes de caractères C ou des tableaux de caractères : l'interprétation des séquences d'octets de caractères est gérée en interne par les fonctions de conversion. Dans certains encodages, un octet zéro peut être une partie valide d'un caractère multi-octets.
• L'appelant de la fonction iconv doit s'assurer que les pointeurs passés à la fonction permettent d'accéder aux caractères de l'ensemble de caractères approprié. Pour les encodages UCS-2-INTERNAL, UCS-4-INTERNAL et wchar_t, cela implique de garantir un alignement correct.

Erreurs

Les erreurs suivantes peuvent notamment se produire :

Conformité

POSIX:2024

Voir également

iconv_open, iconvctl, iconv_close.