1<!-- Creator : groff version 1.20.1 --> 2<!-- CreationDate: Sun Aug 7 19:49:14 2011 --> 3<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 4"http://www.w3.org/TR/html4/loose.dtd"> 5<html> 6<head> 7<meta name="generator" content="groff -Thtml, see www.gnu.org"> 8<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> 9<meta name="Content-Style" content="text/css"> 10<style type="text/css"> 11 p { margin-top: 0; margin-bottom: 0; vertical-align: top } 12 pre { margin-top: 0; margin-bottom: 0; vertical-align: top } 13 table { margin-top: 0; margin-bottom: 0; vertical-align: top } 14 h1 { text-align: center } 15</style> 16<title>ICONV_OPEN</title> 17 18</head> 19<body> 20 21<h1 align="center">ICONV_OPEN</h1> 22 23<a href="#NAME">NAME</a><br> 24<a href="#SYNOPSIS">SYNOPSIS</a><br> 25<a href="#DESCRIPTION">DESCRIPTION</a><br> 26<a href="#RETURN VALUE">RETURN VALUE</a><br> 27<a href="#ERRORS">ERRORS</a><br> 28<a href="#CONFORMING TO">CONFORMING TO</a><br> 29<a href="#SEE ALSO">SEE ALSO</a><br> 30 31<hr> 32 33 34<h2>NAME 35<a name="NAME"></a> 36</h2> 37 38 39<p style="margin-left:11%; margin-top: 1em">iconv_open 40− allocate descriptor for character set conversion</p> 41 42<h2>SYNOPSIS 43<a name="SYNOPSIS"></a> 44</h2> 45 46 47<p style="margin-left:11%; margin-top: 1em"><b>#include 48<iconv.h></b></p> 49 50<p style="margin-left:11%; margin-top: 1em"><b>iconv_t 51iconv_open (const char*</b> <i>tocode</i><b>, const 52char*</b> <i>fromcode</i><b>);</b></p> 53 54<h2>DESCRIPTION 55<a name="DESCRIPTION"></a> 56</h2> 57 58 59<p style="margin-left:11%; margin-top: 1em">The 60<b>iconv_open</b> function allocates a conversion descriptor 61suitable for converting byte sequences from character 62encoding <i>fromcode</i> to character encoding 63<i>tocode</i>.</p> 64 65<p style="margin-left:11%; margin-top: 1em">The values 66permitted for <i>fromcode</i> and <i>tocode</i> and the 67supported combinations are system dependent. For the 68libiconv library, the following encodings are supported, in 69all combinations. <br> 70European languages</p> 71 72<p style="margin-left:22%;">ASCII, 73ISO−8859−{1,2,3,4,5,7,9,10,13,14,15,16}, 74KOI8−R, KOI8−U, KOI8−RU, 75CP{1250,1251,1252,1253,1254,1257}, CP{850,866,1131}, 76Mac{Roman,CentralEurope,Iceland,Croatian,Romania}, 77Mac{Cyrillic,Ukraine,Greek,Turkish}, Macintosh</p> 78 79<p style="margin-left:11%;">Semitic languages</p> 80 81<p style="margin-left:22%;">ISO−8859−{6,8}, 82CP{1255,1256}, CP862, Mac{Hebrew,Arabic}</p> 83 84<p style="margin-left:11%;">Japanese</p> 85 86<p style="margin-left:22%;">EUC−JP, SHIFT_JIS, CP932, 87ISO−2022−JP, ISO−2022−JP−2, 88ISO−2022−JP−1</p> 89 90<p style="margin-left:11%;">Chinese</p> 91 92<p style="margin-left:22%;">EUC−CN, HZ, GBK, CP936, 93GB18030, EUC−TW, BIG5, CP950, BIG5−HKSCS, 94BIG5−HKSCS:2004, BIG5−HKSCS:2001, 95BIG5−HKSCS:1999, ISO−2022−CN, 96ISO−2022−CN−EXT</p> 97 98<table width="100%" border="0" rules="none" frame="void" 99 cellspacing="0" cellpadding="0"> 100<tr valign="top" align="left"> 101<td width="11%"></td> 102<td width="9%"> 103 104 105<p>Korean</p></td> 106<td width="2%"></td> 107<td width="50%"> 108 109 110<p>EUC−KR, CP949, ISO−2022−KR, JOHAB</p></td> 111<td width="28%"> 112</td></tr> 113</table> 114 115<p style="margin-left:11%;">Armenian</p> 116 117<p style="margin-left:22%;">ARMSCII−8</p> 118 119<p style="margin-left:11%;">Georgian</p> 120 121<p style="margin-left:22%;">Georgian−Academy, 122Georgian−PS</p> 123 124<table width="100%" border="0" rules="none" frame="void" 125 cellspacing="0" cellpadding="0"> 126<tr valign="top" align="left"> 127<td width="11%"></td> 128<td width="9%"> 129 130 131<p>Tajik</p></td> 132<td width="2%"></td> 133<td width="35%"> 134 135 136<p>KOI8−T</p></td> 137<td width="43%"> 138</td></tr> 139<tr valign="top" align="left"> 140<td width="11%"></td> 141<td width="9%"> 142 143 144<p>Kazakh</p></td> 145<td width="2%"></td> 146<td width="35%"> 147 148 149<p>PT154, RK1048</p></td> 150<td width="43%"> 151</td></tr> 152<tr valign="top" align="left"> 153<td width="11%"></td> 154<td width="9%"> 155 156 157<p>Thai</p></td> 158<td width="2%"></td> 159<td width="35%"> 160 161 162<p>TIS−620, CP874, MacThai</p></td> 163<td width="43%"> 164</td></tr> 165</table> 166 167<p style="margin-left:11%;">Laotian</p> 168 169<p style="margin-left:22%;">MuleLao−1, CP1133</p> 170 171<p style="margin-left:11%;">Vietnamese</p> 172 173<p style="margin-left:22%;">VISCII, TCVN, CP1258</p> 174 175<p style="margin-left:11%;">Platform specifics</p> 176 177<p style="margin-left:22%;">HP−ROMAN8, NEXTSTEP</p> 178 179<p style="margin-left:11%;">Full Unicode</p> 180 181<p style="margin-left:22%;">UTF−8 <br> 182UCS−2, UCS−2BE, UCS−2LE <br> 183UCS−4, UCS−4BE, UCS−4LE <br> 184UTF−16, UTF−16BE, UTF−16LE <br> 185UTF−32, UTF−32BE, UTF−32LE <br> 186UTF−7 <br> 187C99, JAVA</p> 188 189<p style="margin-left:11%;">Full Unicode, in terms of 190<b>uint16_t</b> or <b>uint32_t</b></p> 191 192<p style="margin-left:22%;">(with machine dependent 193endianness and alignment) <br> 194UCS−2−INTERNAL, UCS−4−INTERNAL</p> 195 196<p style="margin-left:11%;">Locale dependent, in terms of 197<b>char</b> or <b>wchar_t</b></p> 198 199<p style="margin-left:22%;">(with machine dependent 200endianness and alignment, and with semantics depending on 201the OS and the current LC_CTYPE locale facet) <br> 202char, wchar_t</p> 203 204<p style="margin-left:11%; margin-top: 1em">When configured 205with the option 206<b>−−enable−extra−encodings</b>, it 207also provides support for a few extra encodings: <br> 208European languages</p> 209 210 211<p style="margin-left:22%;">CP{437,737,775,852,853,855,857,858,860,861,863,865,869,1125}</p> 212 213<p style="margin-left:11%;">Semitic languages</p> 214 215<p style="margin-left:22%;">CP864</p> 216 217<p style="margin-left:11%;">Japanese</p> 218 219<p style="margin-left:22%;">EUC−JISX0213, 220Shift_JISX0213, ISO−2022−JP−3</p> 221 222<p style="margin-left:11%;">Chinese</p> 223 224<p style="margin-left:22%;">BIG5−2003 225(experimental)</p> 226 227<p style="margin-left:11%;">Turkmen</p> 228 229<p style="margin-left:22%;">TDS565</p> 230 231<p style="margin-left:11%;">Platform specifics</p> 232 233<p style="margin-left:22%;">ATARIST, 234RISCOS−LATIN1</p> 235 236<p style="margin-left:11%; margin-top: 1em">The empty 237encoding name "" is equivalent to 238"char": it denotes the locale dependent character 239encoding.</p> 240 241<p style="margin-left:11%; margin-top: 1em">When the string 242"//TRANSLIT" is appended to <i>tocode</i>, 243transliteration is activated. This means that when a 244character cannot be represented in the target character set, 245it can be approximated through one or several characters 246that look similar to the original character.</p> 247 248<p style="margin-left:11%; margin-top: 1em">When the string 249"//IGNORE" is appended to <i>tocode</i>, 250characters that cannot be represented in the target 251character set will be silently discarded.</p> 252 253<p style="margin-left:11%; margin-top: 1em">The resulting 254conversion descriptor can be used with <b>iconv</b> any 255number of times. It remains valid until deallocated using 256<b>iconv_close</b>.</p> 257 258<p style="margin-left:11%; margin-top: 1em">A conversion 259descriptor contains a conversion state. After creation using 260<b>iconv_open</b>, the state is in the initial state. Using 261<b>iconv</b> modifies the descriptor’s conversion 262state. (This implies that a conversion descriptor can not be 263used in multiple threads simultaneously.) To bring the state 264back to the initial state, use <b>iconv</b> with NULL as 265<i>inbuf</i> argument.</p> 266 267<h2>RETURN VALUE 268<a name="RETURN VALUE"></a> 269</h2> 270 271 272<p style="margin-left:11%; margin-top: 1em">The 273<b>iconv_open</b> function returns a freshly allocated 274conversion descriptor. In case of error, it sets 275<b>errno</b> and returns (iconv_t)(−1).</p> 276 277<h2>ERRORS 278<a name="ERRORS"></a> 279</h2> 280 281 282<p style="margin-left:11%; margin-top: 1em">The following 283error can occur, among others:</p> 284 285<table width="100%" border="0" rules="none" frame="void" 286 cellspacing="0" cellpadding="0"> 287<tr valign="top" align="left"> 288<td width="11%"></td> 289<td width="9%"> 290 291 292<p><b>EINVAL</b></p></td> 293<td width="2%"></td> 294<td width="78%"> 295 296 297<p>The conversion from <i>fromcode</i> to <i>tocode</i> is 298not supported by the implementation.</p></td></tr> 299</table> 300 301<h2>CONFORMING TO 302<a name="CONFORMING TO"></a> 303</h2> 304 305 306<p style="margin-left:11%; margin-top: 1em">POSIX:2001</p> 307 308<h2>SEE ALSO 309<a name="SEE ALSO"></a> 310</h2> 311 312 313 314<p style="margin-left:11%; margin-top: 1em"><b>iconv</b>(3) 315<b>iconvctl</b>(3) <b>iconv_close</b>(3)</p> 316<hr> 317</body> 318</html> 319