iconv_open(3)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 combina‐
tions 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 ALSOdlopen(3), dlsym(3), iconv(3), iconv_close(3), malloc(3)NOTESiconv_open() uses malloc(3) to allocate space for internal buf‐
fer areas, as well as dlopen(3) and dlsym(3) to load the appro‐
priate 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)
