NOM¶
iconv - Conversion de jeux de caractères
SYNOPSIS¶
#include <iconv.h>
size_t iconv(iconv_t cd,
char **inbuf, size_t *inbytesleft,
char **outbuf, size_t *outbytesleft);
DESCRIPTION¶
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. La conversion peut s'arrêter pour quatre
raisons :
- 1.
- 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.
- 2.
- 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.
- 3.
- 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.
- 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 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.
VALEUR RENVOYÉE¶
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 la fonction
remplit
errno et renvoie
(size_t) -1.
ERREURS¶
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.
VERSIONS¶
Cette fonction est disponible dans la glibc depuis la version 2.1.
POSIX.1-2001.
NOTES¶
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.
VOIR AUSSI¶
iconv_close(3),
iconv_open(3)
COLOPHON¶
Cette page fait partie de la publication 3.44 du projet
man-pages Linux.
Une description du projet et des instructions pour signaler des anomalies
peuvent être trouvées à l'adresse
<
http://www.kernel.org/doc/man-pages/>.
TRADUCTION¶
Depuis 2010, cette traduction est maintenue à l'aide de l'outil po4a
<
http://po4a.alioth.debian.org/> par l'équipe de traduction
francophone au sein du projet perkamon
<
http://perkamon.alioth.debian.org/>.
Christophe Blaess <
http://www.blaess.fr/christophe/> (1996-2003), Alain
Portal <
http://manpagesfr.free.fr/> (2003-2006). Florentin Duneau et
l'équipe francophone de traduction de Debian (2006-2009).
Veuillez signaler toute erreur de traduction en écrivant à
<debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
paquet
manpages-fr.
Vous pouvez toujours avoir accès à la version anglaise de ce document
en utilisant la commande «
man -L C
<section> <page_de_man> ».