# iconv

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           iconv — codeset conversion function
    


## 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 shall convert the sequence of characters from
           one codeset, in the array specified by _inbuf_ , into a sequence of
           corresponding characters in another codeset, in the array
           specified by _outbuf_.  The codesets are those specified in the
           _iconv_open_() call that returned the conversion descriptor, _cd_.
           The _inbuf_ argument points to a variable that points to the first
           character in the input buffer and _inbytesleft_ indicates the number
           of bytes to the end of the buffer to be converted. The _outbuf_
           argument points to a variable that points to the first available
           byte in the output buffer and _outbytesleft_ indicates the number of
           the available bytes to the end of the buffer.
    
           For state-dependent encodings, the conversion descriptor _cd_ is
           placed into its initial shift state by a call for which _inbuf_ is a
           null pointer, or for which _inbuf_ points to a null pointer. When
           _iconv_() is called in this way, and if _outbuf_ is not a null pointer
           or a pointer to a null pointer, and _outbytesleft_ points to a
           positive value, _iconv_() shall place, into the output buffer, the
           byte sequence to change the output buffer to its initial shift
           state. If the output buffer is not large enough to hold the entire
           reset sequence, _iconv_() shall fail and set _errno_ to **[E2BIG]**.
           Subsequent calls with _inbuf_ as other than a null pointer or a
           pointer to a null pointer cause the conversion to take place from
           the current state of the conversion descriptor.
    
           If a sequence of input bytes does not form a valid character in
           the specified codeset, conversion shall stop after the previous
           successfully converted character. If the input buffer ends with an
           incomplete character or shift sequence, conversion shall stop
           after the previous successfully converted bytes. If the output
           buffer is not large enough to hold the entire converted input,
           conversion shall stop just prior to the input bytes that would
           cause the output buffer to overflow. The variable pointed to by
           _inbuf_ shall be updated to point to the byte following the last
           byte successfully used in the conversion. The value pointed to by
           _inbytesleft_ shall be decremented to reflect the number of bytes
           still not converted in the input buffer. The variable pointed to
           by _outbuf_ shall be updated to point to the byte following the last
           byte of converted output data. The value pointed to by
           _outbytesleft_ shall be decremented to reflect the number of bytes
           still available in the output buffer. For state-dependent
           encodings, the conversion descriptor shall be updated to reflect
           the shift state in effect at the end of the last successfully
           converted byte sequence.
    
           If _iconv_() encounters a character in the input buffer that is
           valid, but for which an identical character does not exist in the
           target codeset, _iconv_() shall perform an implementation-defined
           conversion on this character.
    


## RETURN VALUE



           The _iconv_() function shall update the variables pointed to by the
           arguments to reflect the extent of the conversion and return the
           number of non-identical conversions performed. If the entire
           string in the input buffer is converted, the value pointed to by
           _inbytesleft_ shall be 0. If the input conversion is stopped due to
           any conditions mentioned above, the value pointed to by
           _inbytesleft_ shall be non-zero and _errno_ shall be set to indicate
           the condition. If an error occurs, _iconv_() shall return (**size_t**)-1
           and set _errno_ to indicate the error.
    


## ERRORS



           The _iconv_() function shall fail if:
    
           **EILSEQ** Input conversion stopped due to an input byte that does not
                  belong to the input codeset.
    
           **E2BIG** Input conversion stopped due to lack of space in the output
                  buffer.
    
           **EINVAL** Input conversion stopped due to an incomplete character or
                  shift sequence at the end of the input buffer.
    
           The _iconv_() function may fail if:
    
           **EBADF** The _cd_ argument is not a valid open conversion descriptor.
    
           _The following sections are informative._
    


## EXAMPLES



           None.
    


## APPLICATION USAGE



           The _inbuf_ argument indirectly points to the memory area which
           contains the conversion input data. The _outbuf_ argument indirectly
           points to the memory area which is to contain the result of the
           conversion. The objects indirectly pointed to by _inbuf_ and _outbuf_
           are not restricted to containing data that is directly
           representable in the ISO C standard language **char** data type. The
           type of _inbuf_ and _outbuf_ , **char **** , does not imply that the objects
           pointed to are interpreted as null-terminated C strings or arrays
           of characters. Any interpretation of a byte sequence that
           represents a character in a given character set encoding scheme is
           done internally within the codeset converters. For example, the
           area pointed to indirectly by _inbuf_ and/or _outbuf_ can contain all
           zero octets that are not interpreted as string terminators but as
           coded character data according to the respective codeset encoding
           scheme. The type of the data (**char** , **short** , **long** , and so on) read
           or stored in the objects is not specified, but may be inferred for
           both the input and output data by the converters determined by the
           _fromcode_ and _tocode_ arguments of _iconv_open_().
    
           Regardless of the data type inferred by the converter, the size of
           the remaining space in both input and output objects (the
           _intbytesleft_ and _outbytesleft_ arguments) is always measured in
           bytes.
    
           For implementations that support the conversion of state-dependent
           encodings, the conversion descriptor must be able to accurately
           reflect the shift-state in effect at the end of the last
           successful conversion. It is not required that the conversion
           descriptor itself be updated, which would require it to be a
           pointer type. Thus, implementations are free to implement the
           descriptor as a handle (other than a pointer type) by which the
           conversion information can be accessed and updated.
    


## RATIONALE



           None.
    


## FUTURE DIRECTIONS



           None.
    


* * *