| ICONV(3) Linux Programmer's Manual ICONV(3) |
| |
| |
| |
| |
| |
| NAME |
| iconv - perform character set conversion |
| |
| SYNOPSIS |
| #include <iconv.h> |
| |
| size_t iconv (iconv_t cd, |
| const char* * inbuf, size_t * inbytesleft, |
| char* * outbuf, size_t * outbytesleft); |
| |
| DESCRIPTION |
| The argument cd must be a conversion descriptor created |
| using the function iconv_open. |
| |
| 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 *out- |
| bytesleft 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 con- |
| verted input bytes, it increments *outbuf and decrements |
| *outbytesleft by the number of converted output bytes, |
| and it updates the conversion state contained in cd. |
| 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, |
| i.e. *inbytesleft has gone down to 0. In this case iconv |
| returns the number of non-reversible conversions per- |
| formed 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 con- |
| verted 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 con- |
| version state to the initial state and store a corre- |
| sponding shift sequence at *outbuf. At most *out- |
| bytesleft 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 decre- |
| ments *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 con- |
| verted in a non-reversible 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 encoun- |
| tered in the input. |
| |
| EINVAL An incomplete multibyte sequence has been encoun- |
| tered in the input. |
| |
| CONFORMING TO |
| UNIX98 |
| |
| SEE ALSO |
| iconv_open(3), iconv_close(3) |
| |
| |
| |
| GNU January 21, 2004 ICONV(3) |