iconv(3) Library Functions Manual iconv(3)

iconv - efectuează conversia setului de caractere

Biblioteca C standard (libc, -lc)

#include <iconv.h>
size_t iconv(iconv_t cd,
             char **restrict inbuf, size_t *restrict inbytesleft,
             char **restrict outbuf, size_t *restrict outbytesleft);

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

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.

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

Nu există spațiu suficient la *outbuf.
O secvență multi-octet nevalidă a fost întâlnită la intrare.
O secvență multi-octet incompletă a fost întâlnită la intrare.

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.

POSIX.1-2008.

glibc 2.1. POSIX.1-2001.

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

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

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

31 octombrie 2023 Pagini de manual de Linux 6.06