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⟩.