Provided by: manpages-ro-dev_4.23.1-1_all 
NUME
iconv - efectuează conversia setului de caractere
BIBLIOTECA
Biblioteca C standard (libc, -lc)
SINOPSIS
#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 cinci 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.
• Se întâlnește o secvență multi-octet care este validă, dar care nu poate fi convertită
în codificarea caracterelor de ieșire. Această condiție depinde de implementare și de
descriptorul de conversie. În biblioteca GNU C și GNU libiconv, dacă cd a fost creat
fără sufixul //TRANSLIT sau //IGNORE, conversia este strictă: conversiile cu pierderi
produc această condiție. Dacă a fost specificat sufixul //TRANSLIT, transliterarea
poate evita această condiție în unele cazuri. În biblioteca musl C, această condiție nu
poate apărea deoarece se utilizează o conversie în '*' ca soluție de rezervă. Nici în
implementările FreeBSD, NetBSD și Solaris ale iconv() nu poate apărea această condiție,
deoarece se utilizează o conversie în '?' ca soluție de rezervă. Atunci când această
condiție este îndeplinită, iconv() stabilește errno la EILSEQ și returnează
(size_t) -1. *inbuf este lăsată indicând începutul secvenței multi-octet
neconvertibile.
• 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-IEȘIRE
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.
ATRIBUTE
Pentru o explicație a termenilor folosiți în această secțiune, a se vedea attributes(7).
┌───────────────────────────────────────────────────┬───────────────────┬─────────────────┐
│Interfață │ Atribut │ Valoare │
├───────────────────────────────────────────────────┼───────────────────┼─────────────────┤
│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-2008.
ISTORIC
glibc 2.1. POSIX.1-2001.
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 făcută 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⟩.