DragonFly On-Line Manual Pages

Search: Section:  


iconv_open(3)         DragonFly Library Functions Manual         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. 10 Sep 2000 iconv_open(3)

Search: Section: