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)

GNU                                             15 noviembre 2001                                       ICONV(3)