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: