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 Jun  6 20:34:24 2001 -->
  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 Thai</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 TIS-620, CP874, MacThai</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 Laotian</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 MuleLao-1, CP1133</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 Vietnamese</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 VISCII, TCVN, CP1258</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 Platform specifics</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 HP-ROMAN8, NEXTSTEP</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 Full Unicode</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 <pre>UTF-8
 210 UCS-2, UCS-2BE, UCS-2LE
 211 UCS-4, UCS-4BE, UCS-4LE
 212 UTF-16, UTF-16BE, UTF-16LE
 213 UTF-32, UTF-32BE, UTF-32LE
 214 UTF-7
 215 JAVA
 216 </pre></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="10%"></td><td width="90%">
 222 Full Unicode, in terms of <b>uint16_t</b> or
 223 <b>uint32_t</b></td></table>
 224
 225 <table width="100%" border=0 rules="none" frame="void"
 226        cols="2" cellspacing="0" cellpadding="0">
 227 <tr valign="top" align="left">
 228 <td width="21%"></td><td width="79%">
 229 (with machine dependent endianness and alignment)
 230 UCS-2-INTERNAL, UCS-4-INTERNAL</td></table>
 231
 232 <table width="100%" border=0 rules="none" frame="void"
 233        cols="2" cellspacing="0" cellpadding="0">
 234 <tr valign="top" align="left">
 235 <td width="10%"></td><td width="90%">
 236 Locale dependent, in terms of <b>char</b> or
 237 <b>wchar_t</b></td></table>
 238
 239 <table width="100%" border=0 rules="none" frame="void"
 240        cols="2" cellspacing="0" cellpadding="0">
 241 <tr valign="top" align="left">
 242 <td width="21%"></td><td width="79%">
 243 (with machine dependent endianness and alignment, and with
 244 semantics depending on the OS and the current LC_CTYPE
 245 locale facet) char, wchar_t</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="10%"></td><td width="90%">
 251 When the string &quot;//TRANSLIT&quot; is appended to
 252 <i>tocode</i>, transliteration is activated. This means that
 253 when a character cannot be represented in the target
 254 character set, it can be approximated through one or several
 255 similarly looking characters.</td></table>
 256
 257 <table width="100%" border=0 rules="none" frame="void"
 258        cols="2" cellspacing="0" cellpadding="0">
 259 <tr valign="top" align="left">
 260 <td width="10%"></td><td width="90%">
 261 The resulting conversion descriptor can be used with
 262 <b>iconv</b> any number of times. It remains valid until
 263 deallocated using <b>iconv_close</b>.</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="10%"></td><td width="90%">
 269 A conversion descriptor contains a conversion state. After
 270 creation using <b>iconv_open</b>, the state is in the
 271 initial state. Using <b>iconv</b> modifies the descriptor's
 272 conversion state. (This implies that a conversion descriptor
 273 can not be used in multiple threads simultaneously.) To
 274 bring the state back to the initial state, use <b>iconv</b>
 275 with NULL as <i>inbuf</i> argument.</td></table>
 276 <a name="RETURN VALUE"></a>
 277 <h2>RETURN VALUE</h2>
 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 The <b>iconv_open</b> function returns a freshly allocated
 284 conversion descriptor. In case of error, it sets
 285 <b>errno</b> and returns (iconv_t)(-1).</td></table>
 286 <a name="ERRORS"></a>
 287 <h2>ERRORS</h2>
 288
 289 <table width="100%" border=0 rules="none" frame="void"
 290        cols="2" cellspacing="0" cellpadding="0">
 291 <tr valign="top" align="left">
 292 <td width="10%"></td><td width="90%">
 293 The following error can occur, among others:</td></table>
 294
 295 <table width="100%" border=0 rules="none" frame="void"
 296        cols="2" cellspacing="0" cellpadding="0">
 297 <tr valign="top" align="left">
 298 <td width="10%"></td><td width="90%">
 299 <b>EINVAL</b></td></table>
 300
 301 <table width="100%" border=0 rules="none" frame="void"
 302        cols="2" cellspacing="0" cellpadding="0">
 303 <tr valign="top" align="left">
 304 <td width="21%"></td><td width="79%">
 305 The conversion from <i>fromcode</i> to <i>tocode</i> is not
 306 supported by the implementation.</td></table>
 307 <a name="CONFORMING TO"></a>
 308 <h2>CONFORMING TO</h2>
 309
 310 <table width="100%" border=0 rules="none" frame="void"
 311        cols="2" cellspacing="0" cellpadding="0">
 312 <tr valign="top" align="left">
 313 <td width="10%"></td><td width="90%">
 314 UNIX98</td></table>
 315 <a name="SEE ALSO"></a>
 316 <h2>SEE ALSO</h2>
 317
 318 <table width="100%" border=0 rules="none" frame="void"
 319        cols="2" cellspacing="0" cellpadding="0">
 320 <tr valign="top" align="left">
 321 <td width="10%"></td><td width="90%">
 322 <b>iconv</b>(3), <b>iconv_close</b>(3)</td></table>
 323 <hr>
 324 </body>
 325 </html>