iconv_open(3)

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

SEE ALSO
dlopen(3), dlsym(3), iconv(3), iconv_close(3), malloc(3)

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.