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

NAME
       iconvopen - allocate descriptor for character set conversion

SYNOPSIS
       ##iinncclluuddee <>

       iiccoonnvvtt iiccoonnvvooppeenn ((ccoonnsstt cchhaarr** tocode,, ccoonnsstt cchhaarr** fromcode));;

DESCRIPTION
       The  iiccoonnvvooppeenn 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
              ASCII,  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
              ARMSCII-8

       Georgian
              Georgian-Academy, Georgian-PS

       Tajik
              KOI8-T

       Thai
              TIS-620, CP874, MacThai

       Laotian
              MuleLao-1, CP1133

       Vietnamese
              VISCII, 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 uuiinntt1166tt or uuiinntt3322tt
              (with machine dependent endianness and alignment)
              UCS-2-INTERNAL, UCS-4-INTERNAL

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

       When configured with the option --eennaabbllee-eexxttrraa-eennccooddiinnggss, 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 iiccoonnvv any number
       of times. It remains valid until deallocated using iiccoonnvvcclloossee.

       A conversion descriptor contains a  conversion  state.  After  creation
       using  iiccoonnvvooppeenn, the state is in the initial state. Using iiccoonnvv 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 iiccoonnvv with NULL as inbuf
       argument.

RREETTUURRNN VVAALLUUEE
       The iiccoonnvvooppeenn function returns a freshly allocated conversion descrip-
       tor. In case of error, it sets eerrrrnnoo and returns (iconvt)(-1).

EERRRROORRSS
       The following error can occur, among others:

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

CCOONNFFOORRMMIINNGG TTOO
       UNIX98

SEE ALSO
       iiccoonnvv(3), iiccoonnvvcclloossee(3)



GNU                              May 26, 2002                    ICONVOPEN(3)