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.

CONFORME A

       UNIX98

VÉASE TAMBIÉN

       iconv_open(3), iconv_close(3)