ICONV(3) Linux Programmer's Manual ICONV(3) NNAAMMEE iconv - perform character set conversion SSYYNNOOPPSSIISS ##iinncclluuddee <> ssiizzee__tt iiccoonnvv ((iiccoonnvv__tt _c_d,, ccoonnsstt cchhaarr** ** _i_n_b_u_f,, ssiizzee__tt ** _i_n_b_y_t_e_s_l_e_f_t,, cchhaarr** ** _o_u_t_b_u_f,, ssiizzee__tt ** _o_u_t_b_y_t_e_s_l_e_f_t));; DDEESSCCRRIIPPTTIIOONN The argument _c_d must be a conversion descriptor created using the func- tion iiccoonnvv__ooppeenn. The main case is when _i_n_b_u_f is not NULL and _*_i_n_b_u_f is not NULL. In this case, the iiccoonnvv function converts the multibyte sequence starting at _*_i_n_b_u_f to a multibyte sequence starting at _*_o_u_t_b_u_f. At most _*_i_n_b_y_t_e_s_l_e_f_t bytes, starting at _*_i_n_b_u_f, will be read. At most _*_o_u_t_- _b_y_t_e_s_l_e_f_t bytes, starting at _*_o_u_t_b_u_f, will be written. The iiccoonnvv function converts one multibyte character at a time, and for each character conversion it increments _*_i_n_b_u_f and decrements _*_i_n_b_y_t_e_s_l_e_f_t by the number of converted input bytes, it increments _*_o_u_t_b_u_f and decrements _*_o_u_t_b_y_t_e_s_l_e_f_t by the number of converted output bytes, and it updates the conversion state contained in _c_d. If the character encoding of the input is stateful, the iiccoonnvv function can also convert a sequence of input bytes to an update of the conversion state without producing any output bytes; such input is called a _s_h_i_f_t _s_e_q_u_e_n_c_e. The conversion can stop for four reasons: 1. An invalid multibyte sequence is encountered in the input. In this case it sets eerrrrnnoo to EEIILLSSEEQQ and returns (size_t)(-1). _*_i_n_b_u_f is left pointing to the beginning of the invalid multibyte sequence. 2. The input byte sequence has been entirely converted, i.e. _*_i_n_b_y_t_e_s_l_e_f_t has gone down to 0. In this case iiccoonnvv 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 eerrrrnnoo to EEIINNVVAALL and returns (size_t)(-1). _*_i_n_b_u_f 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 eerrrrnnoo to EE22BBIIGG and returns (size_t)(-1). A different case is when _i_n_b_u_f is NULL or _*_i_n_b_u_f is NULL, but _o_u_t_b_u_f is not NULL and _*_o_u_t_b_u_f is not NULL. In this case, the iiccoonnvv function attempts to set _c_d's conversion state to the initial state and store a corresponding shift sequence at _*_o_u_t_b_u_f. At most _*_o_u_t_b_y_t_e_s_l_e_f_t bytes, starting at _*_o_u_t_b_u_f, will be written. If the output buffer has no more room for this reset sequence, it sets eerrrrnnoo to EE22BBIIGG and returns (size_t)(-1). Otherwise it increments _*_o_u_t_b_u_f and decrements _*_o_u_t_- _b_y_t_e_s_l_e_f_t by the number of bytes written. A third case is when _i_n_b_u_f is NULL or _*_i_n_b_u_f is NULL, and _o_u_t_b_u_f is NULL or _*_o_u_t_b_u_f is NULL. In this case, the iiccoonnvv function sets _c_d's conversion state to the initial state. RREETTUURRNN VVAALLUUEE The iiccoonnvv function returns the number of characters converted in a non- reversible way during this call; reversible conversions are not counted. In case of error, it sets eerrrrnnoo and returns (size_t)(-1). EERRRROORRSS The following errors can occur, among others: EE22BBIIGG There is not sufficient room at _*_o_u_t_b_u_f. EEIILLSSEEQQ An invalid multibyte sequence has been encountered in the input. EEIINNVVAALL An incomplete multibyte sequence has been encountered in the input. CCOONNFFOORRMMIINNGG TTOO POSIX:2001 SSEEEE AALLSSOO iiccoonnvv__ooppeenn(3), iiccoonnvvccttll(3) iiccoonnvv__cclloossee(3) GNU September 7, 2008 ICONV(3)