# iconv

## NAME



           iconv - perform character set conversion
    


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## SYNOPSIS



           **#include <iconv.h>**
    
           **size_t iconv(iconv_t** _cd_**,**
                        **char **restrict** _inbuf_**, size_t *restrict** _inbytesleft_**,**
                        **char **restrict** _outbuf_**, size_t *restrict** _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 five reasons:
    
           •  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.
    
           •  A multibyte sequence is encountered that is valid but that
              cannot be translated to the character encoding of the output.
              This condition depends on the implementation and on the
              conversion descriptor.  In the GNU C library and GNU libiconv,
              if _cd_ was created without the suffix **//TRANSLIT** or **//IGNORE** ,
              the conversion is strict: lossy conversions produce this
              condition.  If the suffix **//TRANSLIT** was specified,
              transliteration can avoid this condition in some cases.  In the
              musl C library, this condition cannot occur because a
              conversion to **'*'** is used as a fallback.  In the FreeBSD,
              NetBSD, and Solaris implementations of **iconv**(), this condition
              cannot occur either, because a conversion to **'?'** is used as a
              fallback.  When this condition is met, **iconv**() sets _errno_ to
              **EILSEQ** and returns _(size_t) -1_.  _*inbuf_ is left pointing to the
              beginning of the unconvertible multibyte sequence.
    
           •  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.
    
           •  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.
    
           •  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, **iconv**() returns _(size_t) -1_ and
           sets _errno_ to indicate the error.
    


## 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.
    


## 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.
    


## STANDARDS



           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.
    


* * *