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  iconv()  function  converts  a  sequence  of  characters  in one character encoding to a sequence of
       characters in another character encoding.  The cd argument is a conversion descriptor, previously created
       by  a  call to iconv_open(3); the conversion descriptor defines the character encodings that iconv() uses
       for the conversion.  The inbuf argument is the address of a variable that points to the  first  character
       of  the input sequence; inbytesleft indicates the number of bytes in that buffer.  The outbuf argument is
       the address of a variable that points to the first byte available  in  the  output  buffer;  outbytesleft
       indicates the number of bytes available in the output buffer.

       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 converted input bytes, it increments
       *outbuf and decrements *outbytesleft by the  number  of  converted  output  bytes,  and  it  updates  the
       conversion  state  contained  in  cd.   If  the  character encoding of the input is stateful, the iconv()
       function can also convert a sequence of input  bytes  to  an  update  to  the  conversion  state  without
       producing  any  output  bytes;  such  input is called a shift sequence.  The conversion 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, that is, *inbytesleft has gone down to 0.  In
          this case, iconv() returns the number of nonreversible 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 converted 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, starting 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 converted in a nonreversible way during this call;
       reversible conversions are not counted.  In case of error, it sets errno and returns (size_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 encountered in the input.

VERSIONS

       This function is available in glibc since version 2.1.

ATTRIBUTES

       For an explanation of the terms used in this section, see attributes(7).

       ┌──────────┬───────────────┬─────────────────┐
       │Interface │ Attribute     │ Value           │
       ├──────────┼───────────────┼─────────────────┤
       │iconv()   │ Thread safety │ MT-Safe race:cd │
       └──────────┴───────────────┴─────────────────┘
       The iconv() function is MT-Safe, as long as callers arrange for mutual exclusion on the cd argument.

CONFORMING TO

       POSIX.1-2001, POSIX.1-2008.

NOTES

       In each series of calls to iconv(), the last should be one with inbuf or *inbuf equal to NULL,  in  order
       to flush out any partially converted input.

       Although  inbuf  and  outbuf  are typed as char **, this does not mean that the objects they point can be
       interpreted as C strings or as arrays of characters: the interpretation of character  byte  sequences  is
       handled  internally by the conversion functions.  In some encodings, a zero byte may be a valid part of a
       multibyte character.

       The caller of iconv() must ensure that the pointers passed to the function  are  suitable  for  accessing
       characters  in the appropriate character set.  This includes ensuring correct alignment on platforms that
       have tight restrictions on alignment.

SEE ALSO

       iconv_close(3), iconv_open(3), iconvconfig(8)

COLOPHON

       This page is part of release 4.04 of  the  Linux  man-pages  project.   A  description  of  the  project,
       information   about   reporting   bugs,   and   the  latest  version  of  this  page,  can  be  found  at
       http://www.kernel.org/doc/man-pages/.