NAME

iconv_open - charset converter allocation function

SYNOPSIS

#include <iconv.h>

iconv_t iconv_open(const char *to_charset, const char *from_charset);

DESCRIPTION

The iconv_open() function returns a conversion descriptor that describes a conversion from the charset specified by the string pointed to by the from_charset argument to the charset specified by the string pointed to by the to_charset argument. For state-dependent encodings, the conversion descriptor will be in a charset-dependent initial shift state, ready for immediate use with the iconv(3) function.

Settings of from_charset and to_charset and their permitted combinations are implementation-dependent.

A conversion descriptor remains valid in a process until that process closes it.

RETURN VALUES

Upon successful completion iconv_open() returns a conversion descriptor for use on subsequent calls to iconv(). Otherwise, iconv_open() returns (iconv_t)-1 and sets errno to indicate the error.

ERRORS

The iconv_open function may fail if:

EMFILE: {OPEN_MAX} file descriptors are currently open in the calling process.
ENFILE: Too many files are currently open in the system.
ENOMEM: Insufficient storage space is available.
EINVAL: The conversion specified by from_charset and/or to_charset is not supported by the implementation.

IMPLEMENTATION DETAILS

Names of from_charset and to_charset are case insensitive. A charset is valid if there is a corresponding charset.so shared module in one of the module directories (see ENVIRONMENT below). The "x-" prefix, is ignored when looking for a module in a directory. Any combination of from_charset and to_charset is permitted, although not all of them will produce the correct output text. See iconv(3) for incompatibility between source and target charsets.

ENVIRONMENT

ICONV_PATH is the colon-separated list of the directories where iconv_open() looks for the to_charset and from_charset charset modules. If the environment variable is not set, modules are looked for in /usr/local/libexec/iconv. Security note: ICONV_PATH is ignored if iconv_open() is called from setuid/setgid executables.

FILES

/usr/local/share/iconv/charset.aliases: Charset aliases file
/usr/local/share/iconv/*.cct: CCS conversion tables
/usr/local/libexec/iconv/*.so: CES conversion modules

NOTES

iconv_open() uses malloc(3) to allocate space for internal buffer areas, as well as dlopen(3) and dlsym(3) to load the appropriate conversion modules. iconv_open() may fail if there is insufficient storage space to accommodate the buffers and in case of dynamic linker errors.