ICONV(3)                   POSIX Programmer's Manual                  ICONV(3)



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


NNAAMMEE
       iconv -- codeset conversion function

SSYYNNOOPPSSIISS
       #include <iconv.h>

       size_t iconv(iconv_t _c_d, char **restrict _i_n_b_u_f,
           size_t *restrict _i_n_b_y_t_e_s_l_e_f_t, char **restrict _o_u_t_b_u_f,
           size_t *restrict _o_u_t_b_y_t_e_s_l_e_f_t);

DDEESSCCRRIIPPTTIIOONN
       The _i_c_o_n_v() function shall convert the sequence of characters from one
       codeset, in the array specified by _i_n_b_u_f, into a sequence of
       corresponding characters in another codeset, in the array specified by
       _o_u_t_b_u_f.  The codesets are those specified in the _i_c_o_n_v___o_p_e_n() call that
       returned the conversion descriptor, _c_d.  The _i_n_b_u_f argument points to a
       variable that points to the first character in the input buffer and
       _i_n_b_y_t_e_s_l_e_f_t indicates the number of bytes to the end of the buffer to
       be converted. The _o_u_t_b_u_f argument points to a variable that points to
       the first available byte in the output buffer and _o_u_t_b_y_t_e_s_l_e_f_t
       indicates the number of the available bytes to the end of the buffer.

       For state-dependent encodings, the conversion descriptor _c_d is placed
       into its initial shift state by a call for which _i_n_b_u_f is a null
       pointer, or for which _i_n_b_u_f points to a null pointer. When _i_c_o_n_v() is
       called in this way, and if _o_u_t_b_u_f is not a null pointer or a pointer to
       a null pointer, and _o_u_t_b_y_t_e_s_l_e_f_t points to a positive value, _i_c_o_n_v()
       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, _i_c_o_n_v() shall fail and
       set _e_r_r_n_o to [[EE22BBIIGG]].  Subsequent calls with _i_n_b_u_f 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 _i_n_b_u_f shall be updated to point to
       the byte following the last byte successfully used in the conversion.
       The value pointed to by _i_n_b_y_t_e_s_l_e_f_t shall be decremented to reflect the
       number of bytes still not converted in the input buffer. The variable
       pointed to by _o_u_t_b_u_f shall be updated to point to the byte following
       the last byte of converted output data. The value pointed to by
       _o_u_t_b_y_t_e_s_l_e_f_t 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 _i_c_o_n_v() encounters a character in the input buffer that is valid,
       but for which an identical character does not exist in the target
       codeset, _i_c_o_n_v() shall perform an implementation-defined conversion on
       this character.

RREETTUURRNN VVAALLUUEE
       The _i_c_o_n_v() 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 _i_n_b_y_t_e_s_l_e_f_t shall be
       0. If the input conversion is stopped due to any conditions mentioned
       above, the value pointed to by _i_n_b_y_t_e_s_l_e_f_t shall be non-zero and _e_r_r_n_o
       shall be set to indicate the condition. If an error occurs, _i_c_o_n_v()
       shall return (ssiizzee__tt)-1 and set _e_r_r_n_o to indicate the error.

EERRRROORRSS
       The _i_c_o_n_v() function shall fail if:

       EEIILLSSEEQQ Input conversion stopped due to an input byte that does not
              belong to the input codeset.

       EE22BBIIGG  Input conversion stopped due to lack of space in the output
              buffer.

       EEIINNVVAALL Input conversion stopped due to an incomplete character or shift
              sequence at the end of the input buffer.

       The _i_c_o_n_v() function may fail if:

       EEBBAADDFF  The _c_d argument is not a valid open conversion descriptor.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       None.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       The _i_n_b_u_f argument indirectly points to the memory area which contains
       the conversion input data. The _o_u_t_b_u_f argument indirectly points to the
       memory area which is to contain the result of the conversion. The
       objects indirectly pointed to by _i_n_b_u_f and _o_u_t_b_u_f are not restricted to
       containing data that is directly representable in the ISO C standard
       language cchhaarr data type. The type of _i_n_b_u_f and _o_u_t_b_u_f, cchhaarr ****, 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 _i_n_b_u_f and/or _o_u_t_b_u_f 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 (cchhaarr, sshhoorrtt, lloonngg, 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
       _f_r_o_m_c_o_d_e and _t_o_c_o_d_e arguments of _i_c_o_n_v___o_p_e_n().

       Regardless of the data type inferred by the converter, the size of the
       remaining space in both input and output objects (the _i_n_t_b_y_t_e_s_l_e_f_t and
       _o_u_t_b_y_t_e_s_l_e_f_t 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.

RRAATTIIOONNAALLEE
       None.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _i_c_o_n_v___o_p_e_n(), _i_c_o_n_v___c_l_o_s_e(), _m_b_s_r_t_o_w_c_s()

       The Base Definitions volume of POSIX.1-2008, <<iiccoonnvv..hh>>

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open Group.  (This is
       POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
       event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group Standard
       is the referee document. The original Standard can be obtained online
       at http://www.unix.org/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2013                             ICONV(3)
