Provided by: manpages-ro-dev_4.21.0-2_all bug

NUME

       iconv - efectuează conversia setului de caractere

BIBLIOTECA

       Biblioteca C standard (libc, -lc)

REZUMAT

       #include <iconv.h>

       size_t iconv(iconv_t cd,
                    char **restrict inbuf, size_t *restrict inbytesleft,
                    char **restrict outbuf, size_t *restrict outbytesleft);

DESCRIERE

       Funcția iconv() convertește o secvență de caractere dintr-o codificare de caractere într-o
       secvență de caractere  dintr-o  altă  codificare  de  caractere.  Argumentul  cd  este  un
       descriptor  de  conversie, creat anterior printr-un apel la iconv_open(3); descriptorul de
       conversie definește codificările  de  caractere  pe  care  iconv()  le  utilizează  pentru
       conversie.  Argumentul  inbuf  este  adresa unei variabile care indică primul caracter din
       secvența de intrare; inbytesleft indică numărul de octeți din memoria  tampon  respectivă.
       Argumentul  outbuf  este  adresa  unei  variabile  care  indică primul octet disponibil în
       memoria tampon de ieșire; outbytesleft indică numărul de  octeți  disponibili  în  memoria
       tampon de ieșire.

       Cazul  principal este atunci când inbuf nu este NULL și *inbuf nu este NULL. În acest caz,
       funcția iconv() convertește secvența de mai mulți octeți  care  începe  la  *inbuf  într-o
       secvență  de  mai mulți octeți care începe la *outbuf. Vor fi citiți cel mult *inbytesleft
       octeți, începând de la *inbuf. Se vor scrie cel mult *outbytesleft octeți, începând de  la
       *outbuf.

       Funcția  iconv()  convertește  câte  un  caracter  multi-octet la un moment dat și, pentru
       fiecare convertire de caracter, mărește *inbuf și descrește  *inbytesleft  cu  numărul  de
       octeți  de  intrare  convertiți,  mărește *outbuf și descrește *outbytesleft cu numărul de
       octeți de ieșire convertiți și actualizează starea de conversie conținută în cd. În  cazul
       în  care  codificarea caracterelor de intrare este de tip statutar, funcția iconv() poate,
       de asemenea, să convertească o secvență de octeți de intrare într-o actualizare  a  stării
       de  conversie  fără  a  produce  niciun  octet  de  ieșire; o astfel de intrare se numește
       secvență „shift”. Conversia se poate opri din patru motive:

       •  O secvență multi-octet nevalidă este întâlnită la intrare.  În acest caz,  configurează
          errno  la  EILSEQ  și  returnează  (size_t) -1.  *inbuf rămâne îndreptat spre începutul
          secvenței multi-octet nevalide.

       •  Secvența de octeți de intrare a fost convertită  în  întregime,  adică  *inbytesleft  a
          coborât  la  0.  În  acest  caz,  iconv() returnează numărul de conversii nereversibile
          efectuate în timpul acestui apel.

       •  O secvență de mai mulți octeți incompletă este întâlnită la intrare,  iar  secvența  de
          octeți de intrare se termină după ea. În acest caz, se stabilește errno la EINVAL și se
          returnează (size_t) -1.  *inbuf rămâne îndreptat spre începutul  secvenței  multi-octet
          incomplete.

       •  Memoria  tampon de ieșire nu mai are loc pentru următorul caracter convertit.  În acest
          caz, configurează errno la E2BIG și returnează (size_t) -1.

       Un caz diferit este atunci când inbuf este NULL sau *inbuf este NULL, dar outbuf  nu  este
       NULL  și  *outbuf nu este NULL. În acest caz, funcția iconv() încearcă să fixeze starea de
       conversie a lui  cd  la  starea  inițială  și  să  stocheze  o  secvență  de  transformare
       corespunzătoare  în  *outbuf.  Se  vor scrie cel mult *outbytesleft octeți, începând de la
       *outbuf. Dacă memoria tampon  de  ieșire  nu  mai  are  loc  pentru  această  secvență  de
       reinițializare, configurează errno la E2BIG și returnează (size_t) -1.  În caz contrar, se
       incrementează *outbuf și se decrementează *outbytesleft cu numărul de octeți scriși.

       Un al treilea caz este atunci când inbuf este NULL sau *inbuf este NULL, iar  outbuf  este
       NULL sau *outbuf este NULL. În acest caz, funcția iconv() stabilește starea de conversie a
       lui cd la starea inițială.

VALOAREA RETURNATĂ

       Funcția iconv() returnează numărul de caractere convertite  într-un  mod  nereversibil  în
       timpul  acestui  apel;  conversiile  reversibile  nu  sunt luate în considerare. În caz de
       eroare, iconv() returnează (size_t) -1 și configurează errno pentru a indica eroarea.

ERORI

       Pot apărea, printre altele, următoarele erori:

       E2BIG  Nu există spațiu suficient la *outbuf.

       EILSEQ O secvență multi-octet nevalidă a fost întâlnită la intrare.

       EINVAL O secvență multi-octet incompletă a fost întâlnită la intrare.

VERSIUNI

       Această funcție este disponibilă începând cu glibc 2.1.

ATRIBUTE

       Pentru o explicație a termenilor folosiți în această secțiune, a se vedea attributes(7).

       ┌───────────────────────────────────────────────────┬───────────────────┬─────────────────┐
       │InterfațăAtributValoare         │
       ├───────────────────────────────────────────────────┼───────────────────┼─────────────────┤
       │iconv()                                            │ Siguranța firelor │ MT-Safe race:cd │
       └───────────────────────────────────────────────────┴───────────────────┴─────────────────┘

       Funcția iconv() este MT-Safe, atâta timp cât apelanții iau măsuri de  excludere  reciprocă
       pentru argumentul cd.

STANDARDE

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

NOTE

       În  fiecare  serie  de  apeluri  către iconv(), ultimul ar trebui să fie unul cu inbuf sau
       *inbuf egal cu NULL, pentru a elimina orice intrare parțial convertită.

       Deși inbuf și outbuf sunt tipizate ca char **, acest lucru nu  înseamnă  că  obiectele  pe
       care  le  indică pot fi interpretate ca șiruri de caractere C sau ca matrice de caractere:
       interpretarea secvențelor de octeți de caractere este gestionată în mod  intern  de  către
       funcțiile  de conversie. În unele codificări, un octet zero poate fi o parte validă a unui
       caracter multi-octet.

       Cel care apelează iconv() trebuie să se asigure că indicatorii  trecuți  în  funcție  sunt
       adecvați  pentru  accesarea  caracterelor  din  setul  de caractere corespunzător. Aceasta
       include asigurarea alinierii corecte pe platformele care  au  restricții  stricte  privind
       alinierea.

CONSULTAȚI ȘI

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

TRADUCERE

       Traducerea  în  limba  română  a  acestui  manual  a  fost  creată  de Remus-Gabriel Chelu
       <remusgabriel.chelu@disroot.org>

       Această  traducere  este  documentație  gratuită;  citiți  Licența  publică  generală  GNU
       Versiunea  3  ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩  sau  o  versiune  ulterioară cu
       privire la condiții privind drepturile de autor.  NU se asumă Nicio RESPONSABILITATE.

       Dacă găsiți erori în traducerea acestui  manual,  vă  rugăm  să  trimiteți  un  e-mail  la
       ⟨translation-team-ro@lists.sourceforge.net⟩.