iconv - Conversion de jeux de caractères
Bibliothèque C standard (
libc,
-lc)
#include <iconv.h>
size_t iconv(iconv_t cd,
char **restrict inbuf, size_t *restrict inbytesleft,
char **restrict outbuf, size_t *restrict outbytesleft);
La fonction
iconv() convertit une séquence de caractères
dans un jeu de caractères en une séquence de caractères
dans un autre jeu de caractères. Le paramètre
cd est un
descripteur de conversion (en anglais
conversion descriptor),
créé préalablement par un appel à
iconv_open(3) ; le descripteur de conversion définit les
jeux de caractères qu'
iconv() utilise pour cette conversion. Le
paramètre
inbuf est l'adresse d'une variable qui pointe vers le
premier caractère de la séquence d'entrée ; le
paramètre
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 utilisée quand
inbuf et
*inbuf sont non NULL. Dans ce cas,
iconv() convertit la
séquence multioctet débutant en
*inbuf en une
séquence multioctet 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 multioctet à 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 et met à jour l'état de conversion contenu
au sein de
cd. Si le jeu de caractère de l'entrée est
avec état, la fonction
iconv() peut aussi convertir une
séquence d'octets d'entrée en une mise à jour de
l'état de conversion sans produire d'octet de sortie ; une
entrée de ce type est appelée
shift sequence. La
conversion peut s'arrêter pour quatre raisons :
- •
- Une séquence multioctet invalide a été
trouvée en entrée. Dans ce cas, errno est
définie à EILSEQ et la fonction renvoie
(size_t) -1. Ensuite, *inbuf pointera sur le
début de la séquence multioctet invalide.
- •
- La séquence d'entrée multioctet 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.
- •
- Une séquence multioctet incomplète a
été trouvée alors que la séquence
d'entrée se terminait. Dans ce cas, errno est définie
à EINVAL et la fonction renvoie (size_t) -1.
Ensuite, *inbuf pointera sur le début de la séquence
multioctet incomplète.
- •
- 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 si 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,
errno est définie
à
E2BIG et la fonction renvoie
(size_t) -1. 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 si
outbuf ou
*outbuf est NULL. Dans ce cas, la fonction
iconv() replace l'état de conversion
cd dans
l'état de conversion initial.
La fonction
iconv() renvoie le nombre de caractères convertis de
manière irréversible durant l'appel. Les conversions
réversibles ne sont pas prises en compte. En cas d'erreur,
iconv() renvoie
(size_t) -1 et définit
errno pour indiquer l'erreur.
Les erreurs suivantes peuvent se produire, entre autres :
- E2BIG
- Il n'y a pas assez de place dans *outbuf.
- EILSEQ
- Une séquence multioctet invalide a été
trouvée en entrée.
- EINVAL
- Une séquence multioctet incomplète a
été trouvée en entrée.
Cette fonction est disponible depuis la glibc 2.1.
Pour une explication des termes utilisés dans cette section, consulter
attributes(7).
| Interface |
Attribut |
Valeur |
|
iconv() |
Sécurité des threads |
MT-Safe race:cd |
La fonction
iconv() peut être appelée par plusieurs
« threads » (MT-Safe) tant que les appelants
s'arrangent pour exclure mutuellement l'argument
cd.
POSIX.1-2001, POSIX.1-2008.
Dans chaque série d'appels à
iconv(), le dernier devrait
être celui ayant
inbuf ou
*inbuf égal à
NULL, afin de purger toute entrée partiellement convertie.
Bien qu'
inbuf et
outbuf soient déclarés de type
char **, cela ne signifie pas que les objets vers lesquels ils
pointent puissent être interprétés comme des
chaînes de caractères C ou comme des tableaux de
caractères ; l'interprétation des séquences
d'octets comme caractères est gérée de manière
interne par les fonctions de conversion. Dans certains jeux de
caractères, un octet nul peut être une partie valide d'un
caractère multioctet.
Celui qui appelle
iconv() doit s'assurer que les pointeurs passés
à la fonction permettent d'accéder aux caractères dans le
jeu de caractères approprié. Il faut en particulier assurer un
alignement correct sur les plateformes qui ont des exigences très
strictes en matière d'alignement.
iconv_close(3),
iconv_open(3),
iconvconfig(8)
La traduction française de cette page de manuel a été
créée par Christophe Blaess
<
https://www.blaess.fr/christophe/>, Stéphan Rafin
<
[email protected]>, Thierry Vignaud
<
[email protected]>, François Micaux, Alain Portal
<
[email protected]>, Jean-Philippe Guérard
<
[email protected]>, Jean-Luc Coulon (f5ibh)
<
[email protected]>, Julien Cristau
<
[email protected]>, Thomas Huriaux <
[email protected]>,
Nicolas François <
[email protected]>, Florentin
Duneau <
[email protected]>, Simon Paillard
<
[email protected]>, Denis Barbier
<
[email protected]> et David Prévot <
[email protected]>
Cette traduction est une documentation libre ; veuillez vous reporter
à la
GNU
General Public License version 3 concernant les conditions de copie
et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.
Si vous découvrez un bogue dans la traduction de cette page de manuel,
veuillez envoyer un message à
[email protected]