ICONV(V)            Linux Programmer's Manual            ICONV(V)



NAME
       iconv - perform character set conversion

SYNOPSIS
       #include <iconv.h>

       size_t iconv(iconv_t cd,
                     char **inbuf, size_t *inbytesleft,
                     char **outbuf, size_t *outbytesleft);

DESCRIPTION
       The  argument  cd  must be a conversion descriptor created
       using the function iconv_open.

       The main case is when inbuf is not NULL and *inbuf is  not
       NULL.   In  this  case,  the  iconv  function converts the
       multibyte sequence  starting  at  *inbuf  to  a  multibyte
       sequence starting at *outbuf.  At most *inbytesleft bytes,
       starting at *inbuf, will be read.  At  most  *outbytesleft
       bytes, starting at *outbuf, will be written.

       The  iconv  function converts one multibyte character at a
       time, and for  each  character  conversion  it  increments
       *inbuf  and  decrements *inbytesleft by the number of con-
       verted input bytes, it increments *outbuf  and  decrements
       *outbytesleft by the number of converted output bytes, and
       it updates the conversion state contained in cd.  The con-
       version can stop for four reasons:

       1.  An  invalid  multibyte  sequence is encountered in the
       input. In this case it sets errno to  EILSEQ  and  returns
       (size_t)(-1).  *inbuf is left pointing to the beginning of
       the invalid multibyte sequence.

       2. The input byte sequence has  been  entirely  converted,
       i.e.  *inbytesleft  has gone down to 0. In this case iconv
       returns the number of non-reversible conversions performed
       during this call.

       3.  An incomplete multibyte sequence is encountered in the
       input, and the input byte sequence terminates after it. In
       this   case   it   sets   errno   to  EINVAL  and  returns
       (size_t)(-1). *inbuf is left pointing to the beginning  of
       the incomplete multibyte sequence.

       4.  The  output  buffer has no more room for the next con-
       verted character. In this case it sets errno to E2BIG  and
       returns (size_t)(-1).

       A  different case is when inbuf is NULL or *inbuf is NULL,
       but outbuf is not NULL and *outbuf is not  NULL.  In  this
       case,  the  iconv function attempts to set cd's conversion
       state to the initial state and store a corresponding shift
       sequence  at *outbuf.  At most *outbytesleft bytes, start-
       ing at *outbuf, will be written.  If the output buffer has
       no  more  room  for  this reset sequence, it sets errno to
       E2BIG and returns (size_t)(-1).  Otherwise  it  increments
       *outbuf  and  decrements  *outbytesleft  by  the number of
       bytes written.

       A third case is when inbuf is NULL or *inbuf is NULL,  and
       outbuf is NULL or *outbuf is NULL. In this case, the iconv
       function sets cd's conversion state to the initial  state.

RETURN VALUE
       The  iconv  function returns the number of characters con-
       verted  in  a  non-reversible  way   during   this   call;
       reversible conversions are not counted.  In case of error,
       it sets errno and returns (iconv_t)(-1).

ERRORS
       The following errors can occur, among others:

       E2BIG  There is not sufficient room at *outbuf.

       EILSEQ An invalid multibyte sequence has been  encountered
              in the input.

       EINVAL An  incomplete  multibyte sequence has been encoun-
              tered in the input.

CONFORMING TO
       UNIX98

SEE ALSO
       iconv_open(n), iconv_close(e)



GNU                         2001-11-15                   ICONV(V)