noble (3) iconv.3.gz
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ță │ 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-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⟩.