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



NAME
       iconvopen - allocate descriptor for character set conversion

SYNOPSIS
       ##include <>

       iconvt iconvopen (const char** tocode,, const char** fromcode);;

DESCRIPTION
       The  iconvopen function allocates a conversion descriptor suitable for
       converting byte sequences from character encoding fromcode to character
       encoding tocode.

       The values permitted for fromcode and tocode and the supported combina-
       tions are system dependent. For the  libiconv  library,  the  following
       encodings are supported, in all combinations.

       European languages
              ASCI,  ISO-8859-{1,2,3,4,5,7,9,10,13,14,15,16}, KOI8-R, KOI8-U,
              KOI8-RU,     CP{1250,1251,1252,1253,1254,1257},     CP{850,866},
              Mac{Roman,CentralEurope,Iceland,Croatian,Romania},    Mac{Cyril-
              lic,Ukraine,Greek,Turkish}, Macintosh

       Semitic languages
              ISO-8859-{6,8}, CP{1255,1256}, CP862, Mac{Hebrew,Arabic}

       Japanese
              EUC-JP,   SHIFTJIS,    CP932,    ISO-2022-JP,    ISO-2022-JP-2,
              ISO-2022-JP-1

       Chinese
              EUC-CN,  HZ,  GBK,  GB18030,  EUC-TW,  BIG5,  CP950, BIG5-HKSCS,
              ISO-2022-CN, ISO-2022-CN-EXT

       Korean
              EUC-KR, CP949, ISO-2022-KR, JOHAB

       Armenian
              ARMSCI-8

       Georgian
              Georgian-Academy, Georgian-PS

       Tajik
              KOI8-T

       Thai
              TIS-620, CP874, MacThai

       Laotian
              MuleLao-1, CP1133

       Vietnamese
              VISCI, TCVN, CP1258

       Platform specifics
              HP-ROMAN8, NEXTSTEP

       Full Unicode
              UTF-8
              UCS-2, UCS-2BE, UCS-2LE
              UCS-4, UCS-4BE, UCS-4LE
              UTF-16, UTF-16BE, UTF-16LE
              UTF-32, UTF-32BE, UTF-32LE
              UTF-7
              C99, JAVA

       Full Unicode, in terms of uint16t or uint32t
              (with machine dependent endianness and alignment)
              UCS-2-INTERNAL, UCS-4-INTERNAL

       Locale dependent, in terms of char or wchart
              (with machine  dependent  endianness  and  alignment,  and  with
              semantics  depending  on  the OS and the current LCTYPE locale
              facet)
              char, wchart

       When configured with the option --enable-extra-encodings, it also  pro-
       vides support for a few extra encodings:

       European languages
              CP{437,737,775,852,853,855,857,858,860,861,863,865,869,1125}

       Semitic languages
              CP864

       Japanese
              EUC-JISX0213, ShiftJISX0213, ISO-2022-JP-3

       Turkmen
              TDS565

       Platform specifics
              RISCOS-LATIN1

       The  empty  encoding  name  ""  is equivalent to "char": it denotes the
       locale dependent character encoding.

       When the string "/TRANSLIT" is appended to tocode, transliteration  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.

       When  the string "/IGNORE" is appended to tocode, characters that can-
       not be represented in the target character set will  be  silently  dis-
       carded.

       The  resulting  conversion descriptor can be used with iconv any number
       of times. It remains valid until deallocated using iconvclose.

       A conversion descriptor contains a  conversion  state.  After  creation
       using  iconvopen, the state is in the initial state. Using iconv modi-
       fies the descriptor's conversion state. (This implies that a conversion
       descriptor  can  not  be  used  in multiple threads simultaneously.) To
       bring the state back to the initial state, use iconv with NUL as inbuf
       argument.

RETURN VALUE
       The iconvopen function returns a freshly allocated conversion descrip-
       tor. In case of error, it sets errno and returns (iconvt)(-1).

ERORS
       The following error can occur, among others:

       EINVAL The conversion from fromcode to tocode is not supported  by  the
              implementation.

CONFORMING TO
       UNIX98

SEE ALSO
       iconv(3), iconvclose(3)



GNU                              May 26, 2002                    ICONVOPEN(3)