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: Wed Jul 6 12:58:07 2005 --> 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, GB18030, EUC-TW, BIG5, CP950, BIG5-HKSCS, 113ISO-2022-CN, ISO-2022-CN-EXT</td></table> 114 115<table width="100%" border=0 rules="none" frame="void" 116 cols="2" cellspacing="0" cellpadding="0"> 117<tr valign="top" align="left"> 118<td width="10%"></td><td width="90%"> 119Korean</td></table> 120 121<table width="100%" border=0 rules="none" frame="void" 122 cols="2" cellspacing="0" cellpadding="0"> 123<tr valign="top" align="left"> 124<td width="21%"></td><td width="79%"> 125EUC-KR, CP949, ISO-2022-KR, JOHAB</td></table> 126 127<table width="100%" border=0 rules="none" frame="void" 128 cols="2" cellspacing="0" cellpadding="0"> 129<tr valign="top" align="left"> 130<td width="10%"></td><td width="90%"> 131Armenian</td></table> 132 133<table width="100%" border=0 rules="none" frame="void" 134 cols="2" cellspacing="0" cellpadding="0"> 135<tr valign="top" align="left"> 136<td width="21%"></td><td width="79%"> 137ARMSCII-8</td></table> 138 139<table width="100%" border=0 rules="none" frame="void" 140 cols="2" cellspacing="0" cellpadding="0"> 141<tr valign="top" align="left"> 142<td width="10%"></td><td width="90%"> 143Georgian</td></table> 144 145<table width="100%" border=0 rules="none" frame="void" 146 cols="2" cellspacing="0" cellpadding="0"> 147<tr valign="top" align="left"> 148<td width="21%"></td><td width="79%"> 149Georgian-Academy, Georgian-PS</td></table> 150 151<table width="100%" border=0 rules="none" frame="void" 152 cols="2" cellspacing="0" cellpadding="0"> 153<tr valign="top" align="left"> 154<td width="10%"></td><td width="90%"> 155Tajik</td></table> 156 157<table width="100%" border=0 rules="none" frame="void" 158 cols="2" cellspacing="0" cellpadding="0"> 159<tr valign="top" align="left"> 160<td width="21%"></td><td width="79%"> 161KOI8-T</td></table> 162 163<table width="100%" border=0 rules="none" frame="void" 164 cols="2" cellspacing="0" cellpadding="0"> 165<tr valign="top" align="left"> 166<td width="10%"></td><td width="90%"> 167Kazakh</td></table> 168 169<table width="100%" border=0 rules="none" frame="void" 170 cols="2" cellspacing="0" cellpadding="0"> 171<tr valign="top" align="left"> 172<td width="21%"></td><td width="79%"> 173PT154</td></table> 174 175<table width="100%" border=0 rules="none" frame="void" 176 cols="2" cellspacing="0" cellpadding="0"> 177<tr valign="top" align="left"> 178<td width="10%"></td><td width="90%"> 179Thai</td></table> 180 181<table width="100%" border=0 rules="none" frame="void" 182 cols="2" cellspacing="0" cellpadding="0"> 183<tr valign="top" align="left"> 184<td width="21%"></td><td width="79%"> 185TIS-620, CP874, MacThai</td></table> 186 187<table width="100%" border=0 rules="none" frame="void" 188 cols="2" cellspacing="0" cellpadding="0"> 189<tr valign="top" align="left"> 190<td width="10%"></td><td width="90%"> 191Laotian</td></table> 192 193<table width="100%" border=0 rules="none" frame="void" 194 cols="2" cellspacing="0" cellpadding="0"> 195<tr valign="top" align="left"> 196<td width="21%"></td><td width="79%"> 197MuleLao-1, CP1133</td></table> 198 199<table width="100%" border=0 rules="none" frame="void" 200 cols="2" cellspacing="0" cellpadding="0"> 201<tr valign="top" align="left"> 202<td width="10%"></td><td width="90%"> 203Vietnamese</td></table> 204 205<table width="100%" border=0 rules="none" frame="void" 206 cols="2" cellspacing="0" cellpadding="0"> 207<tr valign="top" align="left"> 208<td width="21%"></td><td width="79%"> 209VISCII, TCVN, CP1258</td></table> 210 211<table width="100%" border=0 rules="none" frame="void" 212 cols="2" cellspacing="0" cellpadding="0"> 213<tr valign="top" align="left"> 214<td width="10%"></td><td width="90%"> 215Platform specifics</td></table> 216 217<table width="100%" border=0 rules="none" frame="void" 218 cols="2" cellspacing="0" cellpadding="0"> 219<tr valign="top" align="left"> 220<td width="21%"></td><td width="79%"> 221HP-ROMAN8, NEXTSTEP</td></table> 222 223<table width="100%" border=0 rules="none" frame="void" 224 cols="2" cellspacing="0" cellpadding="0"> 225<tr valign="top" align="left"> 226<td width="10%"></td><td width="90%"> 227Full Unicode</td></table> 228 229<table width="100%" border=0 rules="none" frame="void" 230 cols="2" cellspacing="0" cellpadding="0"> 231<tr valign="top" align="left"> 232<td width="21%"></td><td width="79%"> 233UTF-8</td></table> 234 235<table width="100%" border=0 rules="none" frame="void" 236 cols="2" cellspacing="0" cellpadding="0"> 237<tr valign="top" align="left"> 238<td width="21%"></td><td width="79%"> 239UCS-2, UCS-2BE, UCS-2LE</td></table> 240 241<table width="100%" border=0 rules="none" frame="void" 242 cols="2" cellspacing="0" cellpadding="0"> 243<tr valign="top" align="left"> 244<td width="21%"></td><td width="79%"> 245UCS-4, UCS-4BE, UCS-4LE</td></table> 246 247<table width="100%" border=0 rules="none" frame="void" 248 cols="2" cellspacing="0" cellpadding="0"> 249<tr valign="top" align="left"> 250<td width="21%"></td><td width="79%"> 251UTF-16, UTF-16BE, UTF-16LE</td></table> 252 253<table width="100%" border=0 rules="none" frame="void" 254 cols="2" cellspacing="0" cellpadding="0"> 255<tr valign="top" align="left"> 256<td width="21%"></td><td width="79%"> 257UTF-32, UTF-32BE, UTF-32LE</td></table> 258 259<table width="100%" border=0 rules="none" frame="void" 260 cols="2" cellspacing="0" cellpadding="0"> 261<tr valign="top" align="left"> 262<td width="21%"></td><td width="79%"> 263UTF-7</td></table> 264 265<table width="100%" border=0 rules="none" frame="void" 266 cols="2" cellspacing="0" cellpadding="0"> 267<tr valign="top" align="left"> 268<td width="21%"></td><td width="79%"> 269C99, JAVA</td></table> 270 271<table width="100%" border=0 rules="none" frame="void" 272 cols="2" cellspacing="0" cellpadding="0"> 273<tr valign="top" align="left"> 274<td width="10%"></td><td width="90%"> 275Full Unicode, in terms of <b>uint16_t</b> or 276<b>uint32_t</b></td></table> 277 278<table width="100%" border=0 rules="none" frame="void" 279 cols="2" cellspacing="0" cellpadding="0"> 280<tr valign="top" align="left"> 281<td width="21%"></td><td width="79%"> 282(with machine dependent endianness and 283alignment)</td></table> 284 285<table width="100%" border=0 rules="none" frame="void" 286 cols="2" cellspacing="0" cellpadding="0"> 287<tr valign="top" align="left"> 288<td width="21%"></td><td width="79%"> 289UCS-2-INTERNAL, UCS-4-INTERNAL</td></table> 290 291<table width="100%" border=0 rules="none" frame="void" 292 cols="2" cellspacing="0" cellpadding="0"> 293<tr valign="top" align="left"> 294<td width="10%"></td><td width="90%"> 295Locale dependent, in terms of <b>char</b> or 296<b>wchar_t</b></td></table> 297 298<table width="100%" border=0 rules="none" frame="void" 299 cols="2" cellspacing="0" cellpadding="0"> 300<tr valign="top" align="left"> 301<td width="21%"></td><td width="79%"> 302(with machine dependent endianness and alignment, and with 303semantics depending on the OS and the current LC_CTYPE 304locale facet)</td></table> 305 306<table width="100%" border=0 rules="none" frame="void" 307 cols="2" cellspacing="0" cellpadding="0"> 308<tr valign="top" align="left"> 309<td width="21%"></td><td width="79%"> 310char, wchar_t</td></table> 311 312<table width="100%" border=0 rules="none" frame="void" 313 cols="2" cellspacing="0" cellpadding="0"> 314<tr valign="top" align="left"> 315<td width="10%"></td><td width="90%"> 316When configured with the option 317<b>--enable-extra-encodings</b>, it also provides support 318for a few extra encodings:</td></table> 319 320<table width="100%" border=0 rules="none" frame="void" 321 cols="2" cellspacing="0" cellpadding="0"> 322<tr valign="top" align="left"> 323<td width="10%"></td><td width="90%"> 324European languages</td></table> 325 326<table width="100%" border=0 rules="none" frame="void" 327 cols="2" cellspacing="0" cellpadding="0"> 328<tr valign="top" align="left"> 329<td width="21%"></td><td width="79%"> 330<pre>CP{437,737,775,852,853,855,857,858,860,861,863,865,869,1125} 331</pre></td></table> 332 333<table width="100%" border=0 rules="none" frame="void" 334 cols="2" cellspacing="0" cellpadding="0"> 335<tr valign="top" align="left"> 336<td width="10%"></td><td width="90%"> 337Semitic languages</td></table> 338 339<table width="100%" border=0 rules="none" frame="void" 340 cols="2" cellspacing="0" cellpadding="0"> 341<tr valign="top" align="left"> 342<td width="21%"></td><td width="79%"> 343CP864</td></table> 344 345<table width="100%" border=0 rules="none" frame="void" 346 cols="2" cellspacing="0" cellpadding="0"> 347<tr valign="top" align="left"> 348<td width="10%"></td><td width="90%"> 349Japanese</td></table> 350 351<table width="100%" border=0 rules="none" frame="void" 352 cols="2" cellspacing="0" cellpadding="0"> 353<tr valign="top" align="left"> 354<td width="21%"></td><td width="79%"> 355EUC-JISX0213, Shift_JISX0213, ISO-2022-JP-3</td></table> 356 357<table width="100%" border=0 rules="none" frame="void" 358 cols="2" cellspacing="0" cellpadding="0"> 359<tr valign="top" align="left"> 360<td width="10%"></td><td width="90%"> 361Chinese</td></table> 362 363<table width="100%" border=0 rules="none" frame="void" 364 cols="2" cellspacing="0" cellpadding="0"> 365<tr valign="top" align="left"> 366<td width="21%"></td><td width="79%"> 367BIG5-2003 (experimental)</td></table> 368 369<table width="100%" border=0 rules="none" frame="void" 370 cols="2" cellspacing="0" cellpadding="0"> 371<tr valign="top" align="left"> 372<td width="10%"></td><td width="90%"> 373Turkmen</td></table> 374 375<table width="100%" border=0 rules="none" frame="void" 376 cols="2" cellspacing="0" cellpadding="0"> 377<tr valign="top" align="left"> 378<td width="21%"></td><td width="79%"> 379TDS565</td></table> 380 381<table width="100%" border=0 rules="none" frame="void" 382 cols="2" cellspacing="0" cellpadding="0"> 383<tr valign="top" align="left"> 384<td width="10%"></td><td width="90%"> 385Platform specifics</td></table> 386 387<table width="100%" border=0 rules="none" frame="void" 388 cols="2" cellspacing="0" cellpadding="0"> 389<tr valign="top" align="left"> 390<td width="21%"></td><td width="79%"> 391ATARIST, RISCOS-LATIN1</td></table> 392 393<table width="100%" border=0 rules="none" frame="void" 394 cols="2" cellspacing="0" cellpadding="0"> 395<tr valign="top" align="left"> 396<td width="10%"></td><td width="90%"> 397The empty encoding name "" is equivalent to 398"char": it denotes the locale dependent character 399encoding.</td></table> 400 401<table width="100%" border=0 rules="none" frame="void" 402 cols="2" cellspacing="0" cellpadding="0"> 403<tr valign="top" align="left"> 404<td width="10%"></td><td width="90%"> 405When the string "//TRANSLIT" is appended to 406<i>tocode</i>, transliteration is activated. This means that 407when a character cannot be represented in the target 408character set, it can be approximated through one or several 409similarly looking characters.</td></table> 410 411<table width="100%" border=0 rules="none" frame="void" 412 cols="2" cellspacing="0" cellpadding="0"> 413<tr valign="top" align="left"> 414<td width="10%"></td><td width="90%"> 415When the string "//IGNORE" is appended to 416<i>tocode</i>, characters that cannot be represented in the 417target character set will be silently 418discarded.</td></table> 419 420<table width="100%" border=0 rules="none" frame="void" 421 cols="2" cellspacing="0" cellpadding="0"> 422<tr valign="top" align="left"> 423<td width="10%"></td><td width="90%"> 424The resulting conversion descriptor can be used with 425<b>iconv</b> any number of times. It remains valid until 426deallocated using <b>iconv_close</b>.</td></table> 427 428<table width="100%" border=0 rules="none" frame="void" 429 cols="2" cellspacing="0" cellpadding="0"> 430<tr valign="top" align="left"> 431<td width="10%"></td><td width="90%"> 432A conversion descriptor contains a conversion state. After 433creation using <b>iconv_open</b>, the state is in the 434initial state. Using <b>iconv</b> modifies the descriptor's 435conversion state. (This implies that a conversion descriptor 436can not be used in multiple threads simultaneously.) To 437bring the state back to the initial state, use <b>iconv</b> 438with NULL as <i>inbuf</i> argument.</td></table> 439<a name="RETURN VALUE"></a> 440<h2>RETURN VALUE</h2> 441 442<table width="100%" border=0 rules="none" frame="void" 443 cols="2" cellspacing="0" cellpadding="0"> 444<tr valign="top" align="left"> 445<td width="10%"></td><td width="90%"> 446The <b>iconv_open</b> function returns a freshly allocated 447conversion descriptor. In case of error, it sets 448<b>errno</b> and returns (iconv_t)(-1).</td></table> 449<a name="ERRORS"></a> 450<h2>ERRORS</h2> 451 452<table width="100%" border=0 rules="none" frame="void" 453 cols="2" cellspacing="0" cellpadding="0"> 454<tr valign="top" align="left"> 455<td width="10%"></td><td width="90%"> 456The following error can occur, among others:</td></table> 457 458<table width="100%" border=0 rules="none" frame="void" 459 cols="2" cellspacing="0" cellpadding="0"> 460<tr valign="top" align="left"> 461<td width="10%"></td><td width="90%"> 462<b>EINVAL</b></td></table> 463 464<table width="100%" border=0 rules="none" frame="void" 465 cols="2" cellspacing="0" cellpadding="0"> 466<tr valign="top" align="left"> 467<td width="21%"></td><td width="79%"> 468The conversion from <i>fromcode</i> to <i>tocode</i> is not 469supported by the implementation.</td></table> 470<a name="CONFORMING TO"></a> 471<h2>CONFORMING TO</h2> 472 473<table width="100%" border=0 rules="none" frame="void" 474 cols="2" cellspacing="0" cellpadding="0"> 475<tr valign="top" align="left"> 476<td width="10%"></td><td width="90%"> 477UNIX98</td></table> 478<a name="SEE ALSO"></a> 479<h2>SEE ALSO</h2> 480 481<table width="100%" border=0 rules="none" frame="void" 482 cols="2" cellspacing="0" cellpadding="0"> 483<tr valign="top" align="left"> 484<td width="10%"></td><td width="90%"> 485<b>iconv</b>(3), <b>iconvctl</b>(3), 486<b>iconv_close</b>(3)</td></table> 487<hr> 488</body> 489</html> 490