libiconv/man/iconv_open.3.html

   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 -->
  20 <!-- CreationDate: Wed May 29 16:17:03 2002 -->
  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%">
  27 iconv_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 &lt;iconv.h&gt;
  36
  37 iconv_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%">
  46 The <b>iconv_open</b> function allocates a conversion
  47 descriptor suitable for converting byte sequences from
  48 character 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%">
  55 The values permitted for <i>fromcode</i> and <i>tocode</i>
  56 and the supported combinations are system dependent. For the
  57 libiconv library, the following encodings are supported, in
  58 all 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%">
  64 European 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%">
  70 ASCII, ISO-8859-{1,2,3,4,5,7,9,10,13,14,15,16}, KOI8-R,
  71 KOI8-U, KOI8-RU, CP{1250,1251,1252,1253,1254,1257},
  72 CP{850,866},
  73 Mac{Roman,CentralEurope,Iceland,Croatian,Romania},
  74 Mac{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%">
  80 Semitic 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%">
  86 ISO-8859-{6,8}, CP{1255,1256}, CP862,
  87 Mac{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%">
  93 Japanese</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%">
  99 EUC-JP, SHIFT_JIS, CP932, ISO-2022-JP, ISO-2022-JP-2,
 100 ISO-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%">
 106 Chinese</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%">
 112 EUC-CN, HZ, GBK, GB18030, EUC-TW, BIG5, CP950, BIG5-HKSCS,
 113 ISO-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%">
 119 Korean</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%">
 125 EUC-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%">
 131 Armenian</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%">
 137 ARMSCII-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%">
 143 Georgian</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%">
 149 Georgian-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%">
 155 Tajik</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%">
 161 KOI8-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%">
 167 Thai</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%">
 173 TIS-620, CP874, MacThai</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%">
 179 Laotian</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%">
 185 MuleLao-1, CP1133</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%">
 191 Vietnamese</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%">
 197 VISCII, TCVN, CP1258</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%">
 203 Platform specifics</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%">
 209 HP-ROMAN8, NEXTSTEP</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%">
 215 Full Unicode</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%">
 221 UTF-8</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="21%"></td><td width="79%">
 227 UCS-2, UCS-2BE, UCS-2LE</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%">
 233 UCS-4, UCS-4BE, UCS-4LE</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%">
 239 UTF-16, UTF-16BE, UTF-16LE</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%">
 245 UTF-32, UTF-32BE, UTF-32LE</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%">
 251 UTF-7</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%">
 257 C99, JAVA</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="10%"></td><td width="90%">
 263 Full Unicode, in terms of <b>uint16_t</b> or
 264 <b>uint32_t</b></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%">
 270 (with machine dependent endianness and
 271 alignment)</td></table>
 272
 273 <table width="100%" border=0 rules="none" frame="void"
 274        cols="2" cellspacing="0" cellpadding="0">
 275 <tr valign="top" align="left">
 276 <td width="21%"></td><td width="79%">
 277 UCS-2-INTERNAL, UCS-4-INTERNAL</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="10%"></td><td width="90%">
 283 Locale dependent, in terms of <b>char</b> or
 284 <b>wchar_t</b></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%">
 290 (with machine dependent endianness and alignment, and with
 291 semantics depending on the OS and the current LC_CTYPE
 292 locale facet)</td></table>
 293
 294 <table width="100%" border=0 rules="none" frame="void"
 295        cols="2" cellspacing="0" cellpadding="0">
 296 <tr valign="top" align="left">
 297 <td width="21%"></td><td width="79%">
 298 char, wchar_t</td></table>
 299
 300 <table width="100%" border=0 rules="none" frame="void"
 301        cols="2" cellspacing="0" cellpadding="0">
 302 <tr valign="top" align="left">
 303 <td width="10%"></td><td width="90%">
 304 When configured with the option
 305 <b>--enable-extra-encodings</b>, it also provides support
 306 for a few extra encodings:</td></table>
 307
 308 <table width="100%" border=0 rules="none" frame="void"
 309        cols="2" cellspacing="0" cellpadding="0">
 310 <tr valign="top" align="left">
 311 <td width="10%"></td><td width="90%">
 312 European languages</td></table>
 313
 314 <table width="100%" border=0 rules="none" frame="void"
 315        cols="2" cellspacing="0" cellpadding="0">
 316 <tr valign="top" align="left">
 317 <td width="21%"></td><td width="79%">
 318 <pre>CP{437,737,775,852,853,855,857,858,860,861,863,865,869,1125}
 319 </pre></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%">
 325 Semitic 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 CP864</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%">
 337 Japanese</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%">
 343 EUC-JISX0213, Shift_JISX0213, ISO-2022-JP-3</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%">
 349 Turkmen</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%">
 355 TDS565</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%">
 361 Platform specifics</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%">
 367 RISCOS-LATIN1</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%">
 373 The empty encoding name &quot;&quot; is equivalent to
 374 &quot;char&quot;: it denotes the locale dependent character
 375 encoding.</td></table>
 376
 377 <table width="100%" border=0 rules="none" frame="void"
 378        cols="2" cellspacing="0" cellpadding="0">
 379 <tr valign="top" align="left">
 380 <td width="10%"></td><td width="90%">
 381 When the string &quot;//TRANSLIT&quot; is appended to
 382 <i>tocode</i>, transliteration is activated. This means that
 383 when a character cannot be represented in the target
 384 character set, it can be approximated through one or several
 385 similarly looking characters.</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="10%"></td><td width="90%">
 391 When the string &quot;//IGNORE&quot; is appended to
 392 <i>tocode</i>, characters that cannot be represented in the
 393 target character set will be silently
 394 discarded.</td></table>
 395
 396 <table width="100%" border=0 rules="none" frame="void"
 397        cols="2" cellspacing="0" cellpadding="0">
 398 <tr valign="top" align="left">
 399 <td width="10%"></td><td width="90%">
 400 The resulting conversion descriptor can be used with
 401 <b>iconv</b> any number of times. It remains valid until
 402 deallocated using <b>iconv_close</b>.</td></table>
 403
 404 <table width="100%" border=0 rules="none" frame="void"
 405        cols="2" cellspacing="0" cellpadding="0">
 406 <tr valign="top" align="left">
 407 <td width="10%"></td><td width="90%">
 408 A conversion descriptor contains a conversion state. After
 409 creation using <b>iconv_open</b>, the state is in the
 410 initial state. Using <b>iconv</b> modifies the descriptor's
 411 conversion state. (This implies that a conversion descriptor
 412 can not be used in multiple threads simultaneously.) To
 413 bring the state back to the initial state, use <b>iconv</b>
 414 with NULL as <i>inbuf</i> argument.</td></table>
 415 <a name="RETURN VALUE"></a>
 416 <h2>RETURN VALUE</h2>
 417
 418 <table width="100%" border=0 rules="none" frame="void"
 419        cols="2" cellspacing="0" cellpadding="0">
 420 <tr valign="top" align="left">
 421 <td width="10%"></td><td width="90%">
 422 The <b>iconv_open</b> function returns a freshly allocated
 423 conversion descriptor. In case of error, it sets
 424 <b>errno</b> and returns (iconv_t)(-1).</td></table>
 425 <a name="ERRORS"></a>
 426 <h2>ERRORS</h2>
 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%">
 432 The following error can occur, among others:</td></table>
 433
 434 <table width="100%" border=0 rules="none" frame="void"
 435        cols="2" cellspacing="0" cellpadding="0">
 436 <tr valign="top" align="left">
 437 <td width="10%"></td><td width="90%">
 438 <b>EINVAL</b></td></table>
 439
 440 <table width="100%" border=0 rules="none" frame="void"
 441        cols="2" cellspacing="0" cellpadding="0">
 442 <tr valign="top" align="left">
 443 <td width="21%"></td><td width="79%">
 444 The conversion from <i>fromcode</i> to <i>tocode</i> is not
 445 supported by the implementation.</td></table>
 446 <a name="CONFORMING TO"></a>
 447 <h2>CONFORMING TO</h2>
 448
 449 <table width="100%" border=0 rules="none" frame="void"
 450        cols="2" cellspacing="0" cellpadding="0">
 451 <tr valign="top" align="left">
 452 <td width="10%"></td><td width="90%">
 453 UNIX98</td></table>
 454 <a name="SEE ALSO"></a>
 455 <h2>SEE ALSO</h2>
 456
 457 <table width="100%" border=0 rules="none" frame="void"
 458        cols="2" cellspacing="0" cellpadding="0">
 459 <tr valign="top" align="left">
 460 <td width="10%"></td><td width="90%">
 461 <b>iconv</b>(3), <b>iconv_close</b>(3)</td></table>
 462 <hr>
 463 </body>
 464 </html>