iconv(3) — Subroutines
NAME
iconv − Converts a string of characters from one codeset to another codeset
LIBRARY
The iconv Library (libiconv.a)
SYNOPSIS
#include <iconv.h>
size_t iconv(
iconv_t cd,
char ∗∗inbuf,
size_t ∗inbytesleft,
char ∗∗outbuf,
size_t ∗outbytesleft);
PARAMETERS
cdSpecifies the conversion descriptor that points to the correct codeset converter
inbufPoints to a variable that points to the beginning of a buffer that contains the characters to be converted
inbytesleftPoints to an integer that contains the number of bytes in inbuf still to be converted
outbufPoints to a variable that points to the buffer that contains the characters that have been converted
outbytesleftPoints to an integer that contains the number of free bytes in outbuf
DESCRIPTION
The iconv() function converts a string of characters in inbuf into a different codeset and returns the the results in outbuf. The required converter is identified by cd, which must be a valid descriptor returned by a previous successful call to the iconv_open() function.
On calling, the inbytesleft parameter indicates the number of bytes in inbuf to be converted and outbytesleft indicates the number of available bytes in outbuf. These values are updated upon return so they indicate the new state of their associated buffers.
If a sequence of input bytes does not form a character that is valid in the input codeset, conversion stops after the previous successfully converted character.
It is possible for input data to include a character that is valid in the input codeset but for which an identical character does not exist in the output codeset. The output character for such cases is defined by the converter that iconv() applies when converting from one particular codeset to another. In other words, the output character in this case can vary from one codeset converter to another.
RETURN VALUES
The iconv() function updates the variables pointed to by the call arguments to reflect the extent of the conversion and returns the number of non-identical conversions performed. If the function is successful and converts the entire input string, the value pointed to by inbytesleft will be zero. If an error occurs, the function returns (size_t)-1 and sets errno to indicate the condition. When an error condition prevents conversion of the entire input string, the value pointed to by inbytesleft will be a non-zero value that indicates the number of input bytes not converted.
ERRORS
If any of the following conditions occur, the iconv() function sets errno to the corresponding value.
[E2BIG]The outbuf buffer is too small to contain all the converted characters. The character that causes the overflow is not converted and inbytesleft 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.
[EBADF]The cd parameter does not specify a valid converter descriptor.
[EILSEQ]An input character does not belong to the input codeset. No conversion is attempted on the invalid character and inbytesleft indicates the bytes left to be converted, including the first byte of the invalid character. The inbuf parameter points to the first byte of the invalid character sequence.
The values of outbuf and outbytesleft are updated according to the number of characters that were previously converted.
[EINVAL]The last character in the inbuf parameter was not complete. The inbytesleft parameter indicates the number of bytes undefined in the character being converted.
RELATED INFORMATION
Functions: iconv_close(3), iconv_open(3).