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.65 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> ».