Technical Reference: Base Operating System and Extensions, Volume 1

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 available bytes in the OutBuf buffer. 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

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:

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 that were previously converted.
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 previously0 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

/usr/lib/nls/loc/iconv/*

Contains code set converter methods.

Related Information

The iconv command, genxlt command.

The iconv_close (iconv_close Subroutine) subroutine, iconv_open (iconv_open Subroutine) subroutine.