1<html> 2<head> 3<meta name="generator" content="groff -Thtml, see www.gnu.org"> 4<meta name="Content-Style" content="text/css"> 5<title>ICONV_OPEN</title> 6</head> 7<body> 8 9<h1 align=center>ICONV_OPEN</h1> 10<a href="#NAME">NAME</a><br> 11<a href="#SYNOPSIS">SYNOPSIS</a><br> 12<a href="#DESCRIPTION">DESCRIPTION</a><br> 13<a href="#RETURN VALUE">RETURN VALUE</a><br> 14<a href="#ERRORS">ERRORS</a><br> 15<a href="#CONFORMING TO">CONFORMING TO</a><br> 16<a href="#SEE ALSO">SEE ALSO</a><br> 17 18<hr> 19<!-- Creator : groff version 1.17.2 --> 20<!-- CreationDate: Thu May 18 14:45:31 2006 --> 21<a name="NAME"></a> 22<h2>NAME</h2> 23<table width="100%" border=0 rules="none" frame="void" 24 cols="2" cellspacing="0" cellpadding="0"> 25<tr valign="top" align="left"> 26<td width="10%"></td><td width="90%"> 27iconv_open - allocate descriptor for character set conversion</td></table> 28<a name="SYNOPSIS"></a> 29<h2>SYNOPSIS</h2> 30 31<table width="100%" border=0 rules="none" frame="void" 32 cols="2" cellspacing="0" cellpadding="0"> 33<tr valign="top" align="left"> 34<td width="10%"></td><td width="90%"> 35<pre><b>#include <iconv.h> 36 37iconv_t iconv_open (const char*</b> <i>tocode</i><b>, const char*</b> <i>fromcode</i><b>); 38</b></pre></td></table> 39<a name="DESCRIPTION"></a> 40<h2>DESCRIPTION</h2> 41 42<table width="100%" border=0 rules="none" frame="void" 43 cols="2" cellspacing="0" cellpadding="0"> 44<tr valign="top" align="left"> 45<td width="10%"></td><td width="90%"> 46The <b>iconv_open</b> function allocates a conversion 47descriptor suitable for converting byte sequences from 48character encoding <i>fromcode</i> to character encoding 49<i>tocode</i>.</td></table> 50 51<table width="100%" border=0 rules="none" frame="void" 52 cols="2" cellspacing="0" cellpadding="0"> 53<tr valign="top" align="left"> 54<td width="10%"></td><td width="90%"> 55The values permitted for <i>fromcode</i> and <i>tocode</i> 56and the supported combinations are system dependent. For the 57libiconv library, the following encodings are supported, in 58all combinations.</td></table> 59 60<table width="100%" border=0 rules="none" frame="void" 61 cols="2" cellspacing="0" cellpadding="0"> 62<tr valign="top" align="left"> 63<td width="10%"></td><td width="90%"> 64European languages</td></table> 65 66<table width="100%" border=0 rules="none" frame="void" 67 cols="2" cellspacing="0" cellpadding="0"> 68<tr valign="top" align="left"> 69<td width="21%"></td><td width="79%"> 70ASCII, ISO-8859-{1,2,3,4,5,7,9,10,13,14,15,16}, KOI8-R, 71KOI8-U, KOI8-RU, CP{1250,1251,1252,1253,1254,1257}, 72CP{850,866}, 73Mac{Roman,CentralEurope,Iceland,Croatian,Romania}, 74Mac{Cyrillic,Ukraine,Greek,Turkish}, Macintosh</td></table> 75 76<table width="100%" border=0 rules="none" frame="void" 77 cols="2" cellspacing="0" cellpadding="0"> 78<tr valign="top" align="left"> 79<td width="10%"></td><td width="90%"> 80Semitic languages</td></table> 81 82<table width="100%" border=0 rules="none" frame="void" 83 cols="2" cellspacing="0" cellpadding="0"> 84<tr valign="top" align="left"> 85<td width="21%"></td><td width="79%"> 86ISO-8859-{6,8}, CP{1255,1256}, CP862, 87Mac{Hebrew,Arabic}</td></table> 88 89<table width="100%" border=0 rules="none" frame="void" 90 cols="2" cellspacing="0" cellpadding="0"> 91<tr valign="top" align="left"> 92<td width="10%"></td><td width="90%"> 93Japanese</td></table> 94 95<table width="100%" border=0 rules="none" frame="void" 96 cols="2" cellspacing="0" cellpadding="0"> 97<tr valign="top" align="left"> 98<td width="21%"></td><td width="79%"> 99EUC-JP, SHIFT_JIS, CP932, ISO-2022-JP, ISO-2022-JP-2, 100ISO-2022-JP-1</td></table> 101 102<table width="100%" border=0 rules="none" frame="void" 103 cols="2" cellspacing="0" cellpadding="0"> 104<tr valign="top" align="left"> 105<td width="10%"></td><td width="90%"> 106Chinese</td></table> 107 108<table width="100%" border=0 rules="none" frame="void" 109 cols="2" cellspacing="0" cellpadding="0"> 110<tr valign="top" align="left"> 111<td width="21%"></td><td width="79%"> 112EUC-CN, HZ, GBK, CP936, GB18030, EUC-TW, BIG5, CP950, 113BIG5-HKSCS, BIG5-HKSCS:2001, BIG5-HKSCS:1999, ISO-2022-CN, 114ISO-2022-CN-EXT</td></table> 115 116<table width="100%" border=0 rules="none" frame="void" 117 cols="2" cellspacing="0" cellpadding="0"> 118<tr valign="top" align="left"> 119<td width="10%"></td><td width="90%"> 120Korean</td></table> 121 122<table width="100%" border=0 rules="none" frame="void" 123 cols="2" cellspacing="0" cellpadding="0"> 124<tr valign="top" align="left"> 125<td width="21%"></td><td width="79%"> 126EUC-KR, CP949, ISO-2022-KR, JOHAB</td></table> 127 128<table width="100%" border=0 rules="none" frame="void" 129 cols="2" cellspacing="0" cellpadding="0"> 130<tr valign="top" align="left"> 131<td width="10%"></td><td width="90%"> 132Armenian</td></table> 133 134<table width="100%" border=0 rules="none" frame="void" 135 cols="2" cellspacing="0" cellpadding="0"> 136<tr valign="top" align="left"> 137<td width="21%"></td><td width="79%"> 138ARMSCII-8</td></table> 139 140<table width="100%" border=0 rules="none" frame="void" 141 cols="2" cellspacing="0" cellpadding="0"> 142<tr valign="top" align="left"> 143<td width="10%"></td><td width="90%"> 144Georgian</td></table> 145 146<table width="100%" border=0 rules="none" frame="void" 147 cols="2" cellspacing="0" cellpadding="0"> 148<tr valign="top" align="left"> 149<td width="21%"></td><td width="79%"> 150Georgian-Academy, Georgian-PS</td></table> 151 152<table width="100%" border=0 rules="none" frame="void" 153 cols="2" cellspacing="0" cellpadding="0"> 154<tr valign="top" align="left"> 155<td width="10%"></td><td width="90%"> 156Tajik</td></table> 157 158<table width="100%" border=0 rules="none" frame="void" 159 cols="2" cellspacing="0" cellpadding="0"> 160<tr valign="top" align="left"> 161<td width="21%"></td><td width="79%"> 162KOI8-T</td></table> 163 164<table width="100%" border=0 rules="none" frame="void" 165 cols="2" cellspacing="0" cellpadding="0"> 166<tr valign="top" align="left"> 167<td width="10%"></td><td width="90%"> 168Kazakh</td></table> 169 170<table width="100%" border=0 rules="none" frame="void" 171 cols="2" cellspacing="0" cellpadding="0"> 172<tr valign="top" align="left"> 173<td width="21%"></td><td width="79%"> 174PT154</td></table> 175 176<table width="100%" border=0 rules="none" frame="void" 177 cols="2" cellspacing="0" cellpadding="0"> 178<tr valign="top" align="left"> 179<td width="10%"></td><td width="90%"> 180Thai</td></table> 181 182<table width="100%" border=0 rules="none" frame="void" 183 cols="2" cellspacing="0" cellpadding="0"> 184<tr valign="top" align="left"> 185<td width="21%"></td><td width="79%"> 186TIS-620, CP874, MacThai</td></table> 187 188<table width="100%" border=0 rules="none" frame="void" 189 cols="2" cellspacing="0" cellpadding="0"> 190<tr valign="top" align="left"> 191<td width="10%"></td><td width="90%"> 192Laotian</td></table> 193 194<table width="100%" border=0 rules="none" frame="void" 195 cols="2" cellspacing="0" cellpadding="0"> 196<tr valign="top" align="left"> 197<td width="21%"></td><td width="79%"> 198MuleLao-1, CP1133</td></table> 199 200<table width="100%" border=0 rules="none" frame="void" 201 cols="2" cellspacing="0" cellpadding="0"> 202<tr valign="top" align="left"> 203<td width="10%"></td><td width="90%"> 204Vietnamese</td></table> 205 206<table width="100%" border=0 rules="none" frame="void" 207 cols="2" cellspacing="0" cellpadding="0"> 208<tr valign="top" align="left"> 209<td width="21%"></td><td width="79%"> 210VISCII, TCVN, CP1258</td></table> 211 212<table width="100%" border=0 rules="none" frame="void" 213 cols="2" cellspacing="0" cellpadding="0"> 214<tr valign="top" align="left"> 215<td width="10%"></td><td width="90%"> 216Platform specifics</td></table> 217 218<table width="100%" border=0 rules="none" frame="void" 219 cols="2" cellspacing="0" cellpadding="0"> 220<tr valign="top" align="left"> 221<td width="21%"></td><td width="79%"> 222HP-ROMAN8, NEXTSTEP</td></table> 223 224<table width="100%" border=0 rules="none" frame="void" 225 cols="2" cellspacing="0" cellpadding="0"> 226<tr valign="top" align="left"> 227<td width="10%"></td><td width="90%"> 228Full Unicode</td></table> 229 230<table width="100%" border=0 rules="none" frame="void" 231 cols="2" cellspacing="0" cellpadding="0"> 232<tr valign="top" align="left"> 233<td width="21%"></td><td width="79%"> 234UTF-8</td></table> 235 236<table width="100%" border=0 rules="none" frame="void" 237 cols="2" cellspacing="0" cellpadding="0"> 238<tr valign="top" align="left"> 239<td width="21%"></td><td width="79%"> 240UCS-2, UCS-2BE, UCS-2LE</td></table> 241 242<table width="100%" border=0 rules="none" frame="void" 243 cols="2" cellspacing="0" cellpadding="0"> 244<tr valign="top" align="left"> 245<td width="21%"></td><td width="79%"> 246UCS-4, UCS-4BE, UCS-4LE</td></table> 247 248<table width="100%" border=0 rules="none" frame="void" 249 cols="2" cellspacing="0" cellpadding="0"> 250<tr valign="top" align="left"> 251<td width="21%"></td><td width="79%"> 252UTF-16, UTF-16BE, UTF-16LE</td></table> 253 254<table width="100%" border=0 rules="none" frame="void" 255 cols="2" cellspacing="0" cellpadding="0"> 256<tr valign="top" align="left"> 257<td width="21%"></td><td width="79%"> 258UTF-32, UTF-32BE, UTF-32LE</td></table> 259 260<table width="100%" border=0 rules="none" frame="void" 261 cols="2" cellspacing="0" cellpadding="0"> 262<tr valign="top" align="left"> 263<td width="21%"></td><td width="79%"> 264UTF-7</td></table> 265 266<table width="100%" border=0 rules="none" frame="void" 267 cols="2" cellspacing="0" cellpadding="0"> 268<tr valign="top" align="left"> 269<td width="21%"></td><td width="79%"> 270C99, JAVA</td></table> 271 272<table width="100%" border=0 rules="none" frame="void" 273 cols="2" cellspacing="0" cellpadding="0"> 274<tr valign="top" align="left"> 275<td width="10%"></td><td width="90%"> 276Full Unicode, in terms of <b>uint16_t</b> or 277<b>uint32_t</b></td></table> 278 279<table width="100%" border=0 rules="none" frame="void" 280 cols="2" cellspacing="0" cellpadding="0"> 281<tr valign="top" align="left"> 282<td width="21%"></td><td width="79%"> 283(with machine dependent endianness and 284alignment)</td></table> 285 286<table width="100%" border=0 rules="none" frame="void" 287 cols="2" cellspacing="0" cellpadding="0"> 288<tr valign="top" align="left"> 289<td width="21%"></td><td width="79%"> 290UCS-2-INTERNAL, UCS-4-INTERNAL</td></table> 291 292<table width="100%" border=0 rules="none" frame="void" 293 cols="2" cellspacing="0" cellpadding="0"> 294<tr valign="top" align="left"> 295<td width="10%"></td><td width="90%"> 296Locale dependent, in terms of <b>char</b> or 297<b>wchar_t</b></td></table> 298 299<table width="100%" border=0 rules="none" frame="void" 300 cols="2" cellspacing="0" cellpadding="0"> 301<tr valign="top" align="left"> 302<td width="21%"></td><td width="79%"> 303(with machine dependent endianness and alignment, and with 304semantics depending on the OS and the current LC_CTYPE 305locale facet)</td></table> 306 307<table width="100%" border=0 rules="none" frame="void" 308 cols="2" cellspacing="0" cellpadding="0"> 309<tr valign="top" align="left"> 310<td width="21%"></td><td width="79%"> 311char, wchar_t</td></table> 312 313<table width="100%" border=0 rules="none" frame="void" 314 cols="2" cellspacing="0" cellpadding="0"> 315<tr valign="top" align="left"> 316<td width="10%"></td><td width="90%"> 317When configured with the option 318<b>--enable-extra-encodings</b>, it also provides support 319for a few extra encodings:</td></table> 320 321<table width="100%" border=0 rules="none" frame="void" 322 cols="2" cellspacing="0" cellpadding="0"> 323<tr valign="top" align="left"> 324<td width="10%"></td><td width="90%"> 325European languages</td></table> 326 327<table width="100%" border=0 rules="none" frame="void" 328 cols="2" cellspacing="0" cellpadding="0"> 329<tr valign="top" align="left"> 330<td width="21%"></td><td width="79%"> 331<pre>CP{437,737,775,852,853,855,857,858,860,861,863,865,869,1125} 332</pre></td></table> 333 334<table width="100%" border=0 rules="none" frame="void" 335 cols="2" cellspacing="0" cellpadding="0"> 336<tr valign="top" align="left"> 337<td width="10%"></td><td width="90%"> 338Semitic languages</td></table> 339 340<table width="100%" border=0 rules="none" frame="void" 341 cols="2" cellspacing="0" cellpadding="0"> 342<tr valign="top" align="left"> 343<td width="21%"></td><td width="79%"> 344CP864</td></table> 345 346<table width="100%" border=0 rules="none" frame="void" 347 cols="2" cellspacing="0" cellpadding="0"> 348<tr valign="top" align="left"> 349<td width="10%"></td><td width="90%"> 350Japanese</td></table> 351 352<table width="100%" border=0 rules="none" frame="void" 353 cols="2" cellspacing="0" cellpadding="0"> 354<tr valign="top" align="left"> 355<td width="21%"></td><td width="79%"> 356EUC-JISX0213, Shift_JISX0213, ISO-2022-JP-3</td></table> 357 358<table width="100%" border=0 rules="none" frame="void" 359 cols="2" cellspacing="0" cellpadding="0"> 360<tr valign="top" align="left"> 361<td width="10%"></td><td width="90%"> 362Chinese</td></table> 363 364<table width="100%" border=0 rules="none" frame="void" 365 cols="2" cellspacing="0" cellpadding="0"> 366<tr valign="top" align="left"> 367<td width="21%"></td><td width="79%"> 368BIG5-2003 (experimental)</td></table> 369 370<table width="100%" border=0 rules="none" frame="void" 371 cols="2" cellspacing="0" cellpadding="0"> 372<tr valign="top" align="left"> 373<td width="10%"></td><td width="90%"> 374Turkmen</td></table> 375 376<table width="100%" border=0 rules="none" frame="void" 377 cols="2" cellspacing="0" cellpadding="0"> 378<tr valign="top" align="left"> 379<td width="21%"></td><td width="79%"> 380TDS565</td></table> 381 382<table width="100%" border=0 rules="none" frame="void" 383 cols="2" cellspacing="0" cellpadding="0"> 384<tr valign="top" align="left"> 385<td width="10%"></td><td width="90%"> 386Platform specifics</td></table> 387 388<table width="100%" border=0 rules="none" frame="void" 389 cols="2" cellspacing="0" cellpadding="0"> 390<tr valign="top" align="left"> 391<td width="21%"></td><td width="79%"> 392ATARIST, RISCOS-LATIN1</td></table> 393 394<table width="100%" border=0 rules="none" frame="void" 395 cols="2" cellspacing="0" cellpadding="0"> 396<tr valign="top" align="left"> 397<td width="10%"></td><td width="90%"> 398The empty encoding name "" is equivalent to 399"char": it denotes the locale dependent character 400encoding.</td></table> 401 402<table width="100%" border=0 rules="none" frame="void" 403 cols="2" cellspacing="0" cellpadding="0"> 404<tr valign="top" align="left"> 405<td width="10%"></td><td width="90%"> 406When the string "//TRANSLIT" is appended to 407<i>tocode</i>, transliteration is activated. This means that 408when a character cannot be represented in the target 409character set, it can be approximated through one or several 410similarly looking characters.</td></table> 411 412<table width="100%" border=0 rules="none" frame="void" 413 cols="2" cellspacing="0" cellpadding="0"> 414<tr valign="top" align="left"> 415<td width="10%"></td><td width="90%"> 416When the string "//IGNORE" is appended to 417<i>tocode</i>, characters that cannot be represented in the 418target character set will be silently 419discarded.</td></table> 420 421<table width="100%" border=0 rules="none" frame="void" 422 cols="2" cellspacing="0" cellpadding="0"> 423<tr valign="top" align="left"> 424<td width="10%"></td><td width="90%"> 425The resulting conversion descriptor can be used with 426<b>iconv</b> any number of times. It remains valid until 427deallocated using <b>iconv_close</b>.</td></table> 428 429<table width="100%" border=0 rules="none" frame="void" 430 cols="2" cellspacing="0" cellpadding="0"> 431<tr valign="top" align="left"> 432<td width="10%"></td><td width="90%"> 433A conversion descriptor contains a conversion state. After 434creation using <b>iconv_open</b>, the state is in the 435initial state. Using <b>iconv</b> modifies the descriptor's 436conversion state. (This implies that a conversion descriptor 437can not be used in multiple threads simultaneously.) To 438bring the state back to the initial state, use <b>iconv</b> 439with NULL as <i>inbuf</i> argument.</td></table> 440<a name="RETURN VALUE"></a> 441<h2>RETURN VALUE</h2> 442 443<table width="100%" border=0 rules="none" frame="void" 444 cols="2" cellspacing="0" cellpadding="0"> 445<tr valign="top" align="left"> 446<td width="10%"></td><td width="90%"> 447The <b>iconv_open</b> function returns a freshly allocated 448conversion descriptor. In case of error, it sets 449<b>errno</b> and returns (iconv_t)(-1).</td></table> 450<a name="ERRORS"></a> 451<h2>ERRORS</h2> 452 453<table width="100%" border=0 rules="none" frame="void" 454 cols="2" cellspacing="0" cellpadding="0"> 455<tr valign="top" align="left"> 456<td width="10%"></td><td width="90%"> 457The following error can occur, among others:</td></table> 458 459<table width="100%" border=0 rules="none" frame="void" 460 cols="2" cellspacing="0" cellpadding="0"> 461<tr valign="top" align="left"> 462<td width="10%"></td><td width="90%"> 463<b>EINVAL</b></td></table> 464 465<table width="100%" border=0 rules="none" frame="void" 466 cols="2" cellspacing="0" cellpadding="0"> 467<tr valign="top" align="left"> 468<td width="21%"></td><td width="79%"> 469The conversion from <i>fromcode</i> to <i>tocode</i> is not 470supported by the implementation.</td></table> 471<a name="CONFORMING TO"></a> 472<h2>CONFORMING TO</h2> 473 474<table width="100%" border=0 rules="none" frame="void" 475 cols="2" cellspacing="0" cellpadding="0"> 476<tr valign="top" align="left"> 477<td width="10%"></td><td width="90%"> 478UNIX98</td></table> 479<a name="SEE ALSO"></a> 480<h2>SEE ALSO</h2> 481 482<table width="100%" border=0 rules="none" frame="void" 483 cols="2" cellspacing="0" cellpadding="0"> 484<tr valign="top" align="left"> 485<td width="10%"></td><td width="90%"> 486<b>iconv</b>(3), <b>iconvctl</b>(3), 487<b>iconv_close</b>(3)</td></table> 488<hr> 489</body> 490</html> 491