NOMBRE¶
iconv - realiza la conversión del conjunto de caracteres
SINOPSIS¶
#include <iconv.h>
size_t iconv(iconv_t cd,
char **inbuf, size_t *inbytesleft,
char **outbuf, size_t *outbytesleft);
DESCRIPCIÓN¶
El argumento
cd debe ser un descriptor de conversión creado
mediante la función
iconv_open.
El principal caso se da cuando
inbuf es distinto de NULL y
*inbuf
es distinto de NULL. En este caso, la función
iconv convierte la
secuencia multibyte que comienza en
*inbuf en una secuencia multibyte
que comenzará en
*outbuf. Como mucho se leerán
*inbytesleft bytes, comenzando en
*inbuf. Como mucho se
escribirán
*outbytesleft bytes, comenzando en
*outbuf.
La función
iconv convierte un carácter multibyte a la vez,
y para cada conversión individual incrementa
*inbuf y decrementa
*inbytesleft con el número de bytes de entrada convertidos,
incrementa
*outbuf y decrementa
*outbytesleft con el
número de bytes de salida convertidos, y actualiza el estado de la
conversión contenido en
cd. La conversión puede detenerse
por cuatro motivos:
1. Se encontró una secuencia multibyte inválida en la entrada. En
este caso se asigna a
errno el valor
EILSEQ y se devuelve
(size_t)(-1).
*inbuf se deja apuntando al principio de la secuencia
multibyte inválida.
2. La secuencia de bytes de entrada ha sido totalmente convertida, esto es,
*inbytesleft ha llegado a 0. En este caso
iconv devuelve el
número de conversiones no recuperables realizadas durante esta llamada.
3. Se encontró una secuencia multibyte incompleta en la entrada, y la
secuencia de bytes de entrada termina después de ella. En este caso se
asigna a
errno el valor
EINVAL y se devuelve (size_t)(-1).
*inbuf se deja apuntando al principio de la secuencia multibyte
incompleta.
4. El buffer de salida no tiene suficiente espacio para el siguiente
carácter convertido. En este caso se asigna a
errno el valor
E2BIG y se devuelve (size_t)(-1).
Un caso diferente es cuando
inbuf es NULL o
*inbuf es NULL, pero
outbuf no es NULL y
*outbuf no es NULL. En este caso, la
función
iconv intenta poner el estado de conversión de
cd en el estado inicial y almacenar una secuencia de cambios
correspondiente en
*outbuf. Como mucho se ecribirán
*outbytesleft bytes, comenzando en
*outbuf. Si el buffer de
salida se queda sin espacio para esta secuencia de reinicio, la función
asigna a
errno el valor
E2BIG y devuelve (size_t)(-1). En otro
caso incrementa
*outbuf y decrementa
*outbytesleft con el
número de bytes escritos.
Un tercer caso es cuando
inbuf es NULL o
*inbuf es NULL, y
outbuf es NULL o
*outbuf es NULL. En este caso, la
función
iconv pone el estado de conversión de
cd
en el estado inicial.
VALOR DEVUELTO¶
La función
iconv devuelve el número de caracteres
convertidos de manera no-recuperable durante la llamada; las conversiones
recuperables no se cuentan. En caso de error, modifica
errno con un
valor apropiado y devuelve (size_t)(-1).
ERRORES¶
Pueden ocurrir los siguientes errores, entre otros:
- E2BIG
- No hay suficiente espacio en *outbuf.
- EILSEQ
- Se encontró una secuencia multibyte inválida a la
entrada.
- EINVAL
- Se encontró una secuencia multibyte incompleta a la entrada.
UNIX98
VÉASE TAMBIÉN¶
iconv_open(3),
iconv_close(3)