huschi.net

ICONV_OPEN(3)              Linux Programmer's Manual             ICONV_OPEN(3)

NAME
       iconv_open - allocate descriptor for character set conversion
SYNOPSIS
       #include <iconv.h>
       iconv_t iconv_open(const char *tocode, const char *fromcode);
DESCRIPTION
       The  iconv_open()  function  allocates a conversion descriptor suitable
       for converting byte sequences from character encoding fromcode to char-
       acter encoding tocode.
       The values permitted for fromcode and tocode and the supported combina-
       tions are system-dependent.  For the GNU C library, the permitted  val-
       ues are listed by the iconv --list command, and all combinations of the
       listed values are supported.  Furthermore the GNU C library and the GNU
       libiconv library support the following two suffixes:
       //TRANSLIT
              When the string "//TRANSLIT" is appended to tocode, translitera-
              tion is activated.  This means that when a character  cannot  be
              represented  in the target character set, it can be approximated
              through one or several similarly looking characters.
       //IGNORE
              When the string "//IGNORE" is  appended  to  tocode,  characters
              that  cannot  be represented in the target character set will be
              silently discarded.
       The resulting conversion descriptor can be used with iconv(3) any  num-
       ber of times.  It remains valid until deallocated using iconv_close(3).
       A  conversion  descriptor  contains a conversion state.  After creation
       using iconv_open(), the state is in the initial state.  Using  iconv(3)
       modifies  the descriptor's conversion state.  (This implies that a con-
       version descriptor can not be used in multiple threads simultaneously.)
       To bring the state back to the initial state, use iconv(3) with NULL as
       inbuf argument.
RETURN VALUE
       The  iconv_open()  function  returns  a  freshly  allocated  conversion
       descriptor.  In case of error, it sets errno and returns (iconv_t) -1.
ERRORS
       The following error can occur, among others:
       EINVAL The  conversion  from fromcode to tocode is not supported by the
              implementation.
VERSIONS
       This function is available in glibc since version 2.1.
CONFORMING TO
       UNIX98, POSIX.1-2001.
SEE ALSO
       iconv(1), iconv(3), iconv_close(3)
COLOPHON
       This page is part of release 3.53 of the Linux  man-pages  project.   A
       description  of  the project, and information about reporting bugs, can
       be found at http://www.kernel.org/doc/man-pages/.

GNU                               2008-08-11                     ICONV_OPEN(3)