Provided by: manpages-fr-dev_4.18.1-1_all bug

NOM

       iconv - Conversion de jeux de caractères

BIBLIOTHÈQUE

       Bibliothèque C standard (libc, -lc)

SYNOPSIS

       #include <iconv.h>

       size_t iconv(iconv_t cd,
                    char **restrict inbuf, size_t *restrict inbytesleft,
                    char **restrict outbuf, size_t *restrict 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. 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.

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,
       iconv() renvoie (size_t) -1 et définit errno pour indiquer l'erreur.

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 depuis la glibc 2.1.

ATTRIBUTS

       Pour une explication des termes utilisés dans cette section, consulter attributes(7).

       ┌────────────────────────────────────────────────┬──────────────────────┬─────────────────┐
       │InterfaceAttributValeur          │
       ├────────────────────────────────────────────────┼──────────────────────┼─────────────────┤
       │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.

STANDARDS

       POSIX.1-2001, POSIX.1-2008.

NOTES

       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.

VOIR AUSSI

       iconv_close(3), iconv_open(3), iconvconfig(8)

TRADUCTION

       La traduction française de cette  page  de  manuel  a  été  créée  par  Christophe  Blaess
       <https://www.blaess.fr/christophe/>,  Stéphan  Rafin  <stephan.rafin@laposte.net>, Thierry
       Vignaud <tvignaud@mandriva.com>, François Micaux, Alain  Portal  <aportal@univ-montp2.fr>,
       Jean-Philippe    Guérard   <fevrier@tigreraye.org>,   Jean-Luc   Coulon   (f5ibh)   <jean-
       luc.coulon@wanadoo.fr>,   Julien    Cristau    <jcristau@debian.org>,    Thomas    Huriaux
       <thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centraliens.net>, Florentin
       Duneau <fduneau@gmail.com>, Simon Paillard <simon.paillard@resel.enst-bretagne.fr>,  Denis
       Barbier <barbier@debian.org> et David Prévot <david@tilapin.org>

       Cette  traduction  est  une  documentation libre ; veuillez vous reporter à la GNU General
       Public  License  version 3  ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩   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 à ⟨debian-l10n-french@lists.debian.org⟩.