iconv Subroutine
Purpose
Converts a string of characters in one character code set to another character code set.
Library
The iconv Library (libiconv.a)
Syntax
#include <iconv.h>size_t iconv (CD, InBuf, InBytesLeft, OutBuf, OutBytesLeft)
iconv_t CD;
char **OutBuf, **InBuf;
size_t *OutBytesLeft, *InBytesLeft;Description
The iconv subroutine converts the string specified by the InBuf parameter into a different code set and returns the results in the OutBuf parameter. The required conversion method is identified by the CD parameter, which must be valid conversion descriptor returned by a previous, successful call to the iconv_open subroutine.
On calling, the InBytesLeft parameter indicates the number of bytes in the InBuf buffer to be converted, and the OutBytesLeft parameter indicates the number of bytes remaining in the OutBuf buffer that do not contain converted data. These values are updated upon return so they indicate the new state of their associated buffers.
For state-dependent encodings, calling the iconv subroutine with the InBuf buffer set to null will reset the conversion descriptor in the CD parameter to its initial state. Subsequent calls with the InBuf buffer, specifying other than a null pointer, may cause the internal state of the subroutine to be altered a necessary.
Parameters
| Item | Description |
|---|---|
| CD | Specifies the conversion descriptor that points to the correct code set converter. |
| InBuf | Points to a buffer that contains the number of bytes in the InBytesLeft parameter to be converted. |
| InBytesLeft | Points to an integer that contains the number of bytes in the InBuf parameter. |
| OutBuf | Points to a buffer that contains the number of bytes in the OutBytesLeft parameter that has been converted. |
| OutBytesLeft | Points to an integer that contains the number of bytes in the OutBuf parameter. |
Return Values
Upon successful conversion of all the characters in the InBuf buffer and after placing the converted characters in the OutBuf buffer, the iconv subroutine returns 0, updates the InBytesLeft and OutBytesLeft parameters, and increments the InBuf and OutBuf pointers. Otherwise, it updates the varibles pointed to by the parameters to indicate the extent to the conversion, returns the number of bytes still left to be converted in the input buffer, and sets the errno global variable to indicate the error.
Error Codes
If the iconv subroutine is unsuccessful, it updates the variables to reflect the extent of the conversion before it stopped and sets the errno global variable to one of the following values:
| Item | Description |
|---|---|
| EILSEQ | Indicates an unusable character. If an input character does
not belong to the input code set, no conversion is attempted on the
unusable on the character. In InBytesLeft parameters indicates
the bytes left to be converted, including the first byte of the unusable
character. InBuf parameter points to the first byte of the
unusable character sequence. The values of OutBuf and OutBytesLeft are updated according to the number of bytes available in the output buffer that do not contain converted data. |
| E2BIG | Indicates an output buffer overflow. If the OutBuf buffer is too small to contain all the converted characters, the character that causes the overflow is not converted. The InBytesLeft parameter indicates the bytes left to be converted (including the character that caused the overflow). The InBuf parameter points to the first byte of the characters left to convert. |
| EINVAL | Indicates the input buffer was truncated. If the original
value of InBytesLeft is exhausted in the middle of a character
conversion or shift/lock block, the InBytesLeft parameter indicates
the number of bytes undefined in the character being converted. If an input character of shift sequence is truncated by the InBuf buffer, no conversion is attempted on the truncated data, and the InBytesLeft parameter indicates the bytes left to be converted. The InBuf parameter points to the first bytes if the truncated sequence. The OutBuf and OutBytesLeft values are updated according to the number of characters that were previously converted. Because some encoding may have ambiguous data, the EINVAL return value has a special meaning at the end of stream conversion. As such, if a user detects an EOF character on a stream that is being converted and the last return code from the iconv subroutine was EINVAL, the iconv subroutine should be called again, with the same InBytesLeft parameter and the same character string pointed to by the InBuf parameter as when the EINVAL return occurred. As a result, the converter will either convert the string as is or declare it an unusable sequence (EILSEQ). |
Files
| Item | Description |
|---|---|
| /usr/lib/nls/loc/iconv/* | Contains code set converter methods. |