Provided by: manpages-fr-dev_3.57d1p1-1_all bug

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.

CONFORMITÉ

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