man/iconv_open.3.html - nest-hello/libiconv - Git at Google

 <!-- Creator     : groff version 1.20.1 -->
 <!-- CreationDate: Sun Aug  7 19:49:14 2011 -->
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
 "http://www.w3.org/TR/html4/loose.dtd">
 <html>
 <head>
 <meta name="generator" content="groff -Thtml, see www.gnu.org">
 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
 <meta name="Content-Style" content="text/css">
 <style type="text/css">
        p       { margin-top: 0; margin-bottom: 0; vertical-align: top }
        pre     { margin-top: 0; margin-bottom: 0; vertical-align: top }
        table   { margin-top: 0; margin-bottom: 0; vertical-align: top }
        h1      { text-align: center }
 </style>
 <title>ICONV_OPEN</title>

 </head>
 <body>

 <h1 align="center">ICONV_OPEN</h1>

 <a href="#NAME">NAME</a><br>
 <a href="#SYNOPSIS">SYNOPSIS</a><br>
 <a href="#DESCRIPTION">DESCRIPTION</a><br>
 <a href="#RETURN VALUE">RETURN VALUE</a><br>
 <a href="#ERRORS">ERRORS</a><br>
 <a href="#CONFORMING TO">CONFORMING TO</a><br>
 <a href="#SEE ALSO">SEE ALSO</a><br>

 <hr>


 <h2>NAME
 <a name="NAME"></a>
 </h2>


 <p style="margin-left:11%; margin-top: 1em">iconv_open
 &minus; allocate descriptor for character set conversion</p>

 <h2>SYNOPSIS
 <a name="SYNOPSIS"></a>
 </h2>


 <p style="margin-left:11%; margin-top: 1em"><b>#include
 &lt;iconv.h&gt;</b></p>

 <p style="margin-left:11%; margin-top: 1em"><b>iconv_t
 iconv_open (const char*</b> <i>tocode</i><b>, const
 char*</b> <i>fromcode</i><b>);</b></p>

 <h2>DESCRIPTION
 <a name="DESCRIPTION"></a>
 </h2>


 <p style="margin-left:11%; margin-top: 1em">The
 <b>iconv_open</b> function allocates a conversion descriptor
 suitable for converting byte sequences from character
 encoding <i>fromcode</i> to character encoding
 <i>tocode</i>.</p>

 <p style="margin-left:11%; margin-top: 1em">The values
 permitted for <i>fromcode</i> and <i>tocode</i> and the
 supported combinations are system dependent. For the
 libiconv library, the following encodings are supported, in
 all combinations. <br>
 European languages</p>

 <p style="margin-left:22%;">ASCII,
 ISO&minus;8859&minus;{1,2,3,4,5,7,9,10,13,14,15,16},
 KOI8&minus;R, KOI8&minus;U, KOI8&minus;RU,
 CP{1250,1251,1252,1253,1254,1257}, CP{850,866,1131},
 Mac{Roman,CentralEurope,Iceland,Croatian,Romania},
 Mac{Cyrillic,Ukraine,Greek,Turkish}, Macintosh</p>

 <p style="margin-left:11%;">Semitic languages</p>

 <p style="margin-left:22%;">ISO&minus;8859&minus;{6,8},
 CP{1255,1256}, CP862, Mac{Hebrew,Arabic}</p>

 <p style="margin-left:11%;">Japanese</p>

 <p style="margin-left:22%;">EUC&minus;JP, SHIFT_JIS, CP932,
 ISO&minus;2022&minus;JP, ISO&minus;2022&minus;JP&minus;2,
 ISO&minus;2022&minus;JP&minus;1</p>

 <p style="margin-left:11%;">Chinese</p>

 <p style="margin-left:22%;">EUC&minus;CN, HZ, GBK, CP936,
 GB18030, EUC&minus;TW, BIG5, CP950, BIG5&minus;HKSCS,
 BIG5&minus;HKSCS:2004, BIG5&minus;HKSCS:2001,
 BIG5&minus;HKSCS:1999, ISO&minus;2022&minus;CN,
 ISO&minus;2022&minus;CN&minus;EXT</p>

 <table width="100%" border="0" rules="none" frame="void"
        cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="11%"></td>
 <td width="9%">


 <p>Korean</p></td>
 <td width="2%"></td>
 <td width="50%">


 <p>EUC&minus;KR, CP949, ISO&minus;2022&minus;KR, JOHAB</p></td>
 <td width="28%">
 </td></tr>
 </table>

 <p style="margin-left:11%;">Armenian</p>

 <p style="margin-left:22%;">ARMSCII&minus;8</p>

 <p style="margin-left:11%;">Georgian</p>

 <p style="margin-left:22%;">Georgian&minus;Academy,
 Georgian&minus;PS</p>

 <table width="100%" border="0" rules="none" frame="void"
        cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="11%"></td>
 <td width="9%">


 <p>Tajik</p></td>
 <td width="2%"></td>
 <td width="35%">


 <p>KOI8&minus;T</p></td>
 <td width="43%">
 </td></tr>
 <tr valign="top" align="left">
 <td width="11%"></td>
 <td width="9%">


 <p>Kazakh</p></td>
 <td width="2%"></td>
 <td width="35%">


 <p>PT154, RK1048</p></td>
 <td width="43%">
 </td></tr>
 <tr valign="top" align="left">
 <td width="11%"></td>
 <td width="9%">


 <p>Thai</p></td>
 <td width="2%"></td>
 <td width="35%">


 <p>TIS&minus;620, CP874, MacThai</p></td>
 <td width="43%">
 </td></tr>
 </table>

 <p style="margin-left:11%;">Laotian</p>

 <p style="margin-left:22%;">MuleLao&minus;1, CP1133</p>

 <p style="margin-left:11%;">Vietnamese</p>

 <p style="margin-left:22%;">VISCII, TCVN, CP1258</p>

 <p style="margin-left:11%;">Platform specifics</p>

 <p style="margin-left:22%;">HP&minus;ROMAN8, NEXTSTEP</p>

 <p style="margin-left:11%;">Full Unicode</p>

 <p style="margin-left:22%;">UTF&minus;8 <br>
 UCS&minus;2, UCS&minus;2BE, UCS&minus;2LE <br>
 UCS&minus;4, UCS&minus;4BE, UCS&minus;4LE <br>
 UTF&minus;16, UTF&minus;16BE, UTF&minus;16LE <br>
 UTF&minus;32, UTF&minus;32BE, UTF&minus;32LE <br>
 UTF&minus;7 <br>
 C99, JAVA</p>

 <p style="margin-left:11%;">Full Unicode, in terms of
 <b>uint16_t</b> or <b>uint32_t</b></p>

 <p style="margin-left:22%;">(with machine dependent
 endianness and alignment) <br>
 UCS&minus;2&minus;INTERNAL, UCS&minus;4&minus;INTERNAL</p>

 <p style="margin-left:11%;">Locale dependent, in terms of
 <b>char</b> or <b>wchar_t</b></p>

 <p style="margin-left:22%;">(with machine dependent
 endianness and alignment, and with semantics depending on
 the OS and the current LC_CTYPE locale facet) <br>
 char, wchar_t</p>

 <p style="margin-left:11%; margin-top: 1em">When configured
 with the option
 <b>&minus;&minus;enable&minus;extra&minus;encodings</b>, it
 also provides support for a few extra encodings: <br>
 European languages</p>


 <p style="margin-left:22%;">CP{437,737,775,852,853,855,857,858,860,861,863,865,869,1125}</p>

 <p style="margin-left:11%;">Semitic languages</p>

 <p style="margin-left:22%;">CP864</p>

 <p style="margin-left:11%;">Japanese</p>

 <p style="margin-left:22%;">EUC&minus;JISX0213,
 Shift_JISX0213, ISO&minus;2022&minus;JP&minus;3</p>

 <p style="margin-left:11%;">Chinese</p>

 <p style="margin-left:22%;">BIG5&minus;2003
 (experimental)</p>

 <p style="margin-left:11%;">Turkmen</p>

 <p style="margin-left:22%;">TDS565</p>

 <p style="margin-left:11%;">Platform specifics</p>

 <p style="margin-left:22%;">ATARIST,
 RISCOS&minus;LATIN1</p>

 <p style="margin-left:11%; margin-top: 1em">The empty
 encoding name &quot;&quot; is equivalent to
 &quot;char&quot;: it denotes the locale dependent character
 encoding.</p>

 <p style="margin-left:11%; margin-top: 1em">When the string
 &quot;//TRANSLIT&quot; is appended to <i>tocode</i>,
 transliteration is activated. This means that when a
 character cannot be represented in the target character set,
 it can be approximated through one or several characters
 that look similar to the original character.</p>

 <p style="margin-left:11%; margin-top: 1em">When the string
 &quot;//IGNORE&quot; is appended to <i>tocode</i>,
 characters that cannot be represented in the target
 character set will be silently discarded.</p>

 <p style="margin-left:11%; margin-top: 1em">The resulting
 conversion descriptor can be used with <b>iconv</b> any
 number of times. It remains valid until deallocated using
 <b>iconv_close</b>.</p>

 <p style="margin-left:11%; margin-top: 1em">A conversion
 descriptor contains a conversion state. After creation using
 <b>iconv_open</b>, the state is in the initial state. Using
 <b>iconv</b> modifies the descriptor&rsquo;s conversion
 state. (This implies that a conversion descriptor can not be
 used in multiple threads simultaneously.) To bring the state
 back to the initial state, use <b>iconv</b> with NULL as
 <i>inbuf</i> argument.</p>

 <h2>RETURN VALUE
 <a name="RETURN VALUE"></a>
 </h2>


 <p style="margin-left:11%; margin-top: 1em">The
 <b>iconv_open</b> function returns a freshly allocated
 conversion descriptor. In case of error, it sets
 <b>errno</b> and returns (iconv_t)(&minus;1).</p>

 <h2>ERRORS
 <a name="ERRORS"></a>
 </h2>


 <p style="margin-left:11%; margin-top: 1em">The following
 error can occur, among others:</p>

 <table width="100%" border="0" rules="none" frame="void"
        cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="11%"></td>
 <td width="9%">


 <p><b>EINVAL</b></p></td>
 <td width="2%"></td>
 <td width="78%">


 <p>The conversion from <i>fromcode</i> to <i>tocode</i> is
 not supported by the implementation.</p></td></tr>
 </table>

 <h2>CONFORMING TO
 <a name="CONFORMING TO"></a>
 </h2>


 <p style="margin-left:11%; margin-top: 1em">POSIX:2001</p>

 <h2>SEE ALSO
 <a name="SEE ALSO"></a>
 </h2>


 <p style="margin-left:11%; margin-top: 1em"><b>iconv</b>(3)
 <b>iconvctl</b>(3) <b>iconv_close</b>(3)</p>
 <hr>
 </body>
 </html>
	<!-- Creator : groff version 1.20.1 -->
	<!-- CreationDate: Sun Aug 7 19:49:14 2011 -->
	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
	"http://www.w3.org/TR/html4/loose.dtd">
	<html>
	<head>
	<meta name="generator" content="groff -Thtml, see www.gnu.org">
	<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
	<meta name="Content-Style" content="text/css">
	<style type="text/css">
	p { margin-top: 0; margin-bottom: 0; vertical-align: top }
	pre { margin-top: 0; margin-bottom: 0; vertical-align: top }
	table { margin-top: 0; margin-bottom: 0; vertical-align: top }
	h1 { text-align: center }
	</style>
	<title>ICONV_OPEN</title>

	</head>
	<body>

	<h1 align="center">ICONV_OPEN</h1>

	<a href="#NAME">NAME</a><br>
	<a href="#SYNOPSIS">SYNOPSIS</a><br>
	<a href="#DESCRIPTION">DESCRIPTION</a><br>
	<a href="#RETURN VALUE">RETURN VALUE</a><br>
	<a href="#ERRORS">ERRORS</a><br>
	<a href="#CONFORMING TO">CONFORMING TO</a><br>
	<a href="#SEE ALSO">SEE ALSO</a><br>

	<hr>


	<h2>NAME
	<a name="NAME"></a>
	</h2>


	<p style="margin-left:11%; margin-top: 1em">iconv_open
	− allocate descriptor for character set conversion</p>

	<h2>SYNOPSIS
	<a name="SYNOPSIS"></a>
	</h2>


	<p style="margin-left:11%; margin-top: 1em"><b>#include
	<iconv.h></b></p>

	<p style="margin-left:11%; margin-top: 1em"><b>iconv_t
	iconv_open (const char*</b> <i>tocode</i><b>, const
	char*</b> <i>fromcode</i><b>);</b></p>

	<h2>DESCRIPTION
	<a name="DESCRIPTION"></a>
	</h2>


	<p style="margin-left:11%; margin-top: 1em">The
	<b>iconv_open</b> function allocates a conversion descriptor
	suitable for converting byte sequences from character
	encoding <i>fromcode</i> to character encoding
	<i>tocode</i>.</p>

	<p style="margin-left:11%; margin-top: 1em">The values
	permitted for <i>fromcode</i> and <i>tocode</i> and the
	supported combinations are system dependent. For the
	libiconv library, the following encodings are supported, in
	all combinations. <br>
	European languages</p>

	<p style="margin-left:22%;">ASCII,
	ISO−8859−{1,2,3,4,5,7,9,10,13,14,15,16},
	KOI8−R, KOI8−U, KOI8−RU,
	CP{1250,1251,1252,1253,1254,1257}, CP{850,866,1131},
	Mac{Roman,CentralEurope,Iceland,Croatian,Romania},
	Mac{Cyrillic,Ukraine,Greek,Turkish}, Macintosh</p>

	<p style="margin-left:11%;">Semitic languages</p>

	<p style="margin-left:22%;">ISO−8859−{6,8},
	CP{1255,1256}, CP862, Mac{Hebrew,Arabic}</p>

	<p style="margin-left:11%;">Japanese</p>

	<p style="margin-left:22%;">EUC−JP, SHIFT_JIS, CP932,
	ISO−2022−JP, ISO−2022−JP−2,
	ISO−2022−JP−1</p>

	<p style="margin-left:11%;">Chinese</p>

	<p style="margin-left:22%;">EUC−CN, HZ, GBK, CP936,
	GB18030, EUC−TW, BIG5, CP950, BIG5−HKSCS,
	BIG5−HKSCS:2004, BIG5−HKSCS:2001,
	BIG5−HKSCS:1999, ISO−2022−CN,
	ISO−2022−CN−EXT</p>

	<table width="100%" border="0" rules="none" frame="void"
	cellspacing="0" cellpadding="0">
	<tr valign="top" align="left">
	<td width="11%"></td>
	<td width="9%">


	<p>Korean</p></td>
	<td width="2%"></td>
	<td width="50%">


	<p>EUC−KR, CP949, ISO−2022−KR, JOHAB</p></td>
	<td width="28%">
	</td></tr>
	</table>

	<p style="margin-left:11%;">Armenian</p>

	<p style="margin-left:22%;">ARMSCII−8</p>

	<p style="margin-left:11%;">Georgian</p>

	<p style="margin-left:22%;">Georgian−Academy,
	Georgian−PS</p>

	<table width="100%" border="0" rules="none" frame="void"
	cellspacing="0" cellpadding="0">
	<tr valign="top" align="left">
	<td width="11%"></td>
	<td width="9%">


	<p>Tajik</p></td>
	<td width="2%"></td>
	<td width="35%">


	<p>KOI8−T</p></td>
	<td width="43%">
	</td></tr>
	<tr valign="top" align="left">
	<td width="11%"></td>
	<td width="9%">


	<p>Kazakh</p></td>
	<td width="2%"></td>
	<td width="35%">


	<p>PT154, RK1048</p></td>
	<td width="43%">
	</td></tr>
	<tr valign="top" align="left">
	<td width="11%"></td>
	<td width="9%">


	<p>Thai</p></td>
	<td width="2%"></td>
	<td width="35%">


	<p>TIS−620, CP874, MacThai</p></td>
	<td width="43%">
	</td></tr>
	</table>

	<p style="margin-left:11%;">Laotian</p>

	<p style="margin-left:22%;">MuleLao−1, CP1133</p>

	<p style="margin-left:11%;">Vietnamese</p>

	<p style="margin-left:22%;">VISCII, TCVN, CP1258</p>

	<p style="margin-left:11%;">Platform specifics</p>

	<p style="margin-left:22%;">HP−ROMAN8, NEXTSTEP</p>

	<p style="margin-left:11%;">Full Unicode</p>

	<p style="margin-left:22%;">UTF−8 <br>
	UCS−2, UCS−2BE, UCS−2LE <br>
	UCS−4, UCS−4BE, UCS−4LE <br>
	UTF−16, UTF−16BE, UTF−16LE <br>
	UTF−32, UTF−32BE, UTF−32LE <br>
	UTF−7 <br>
	C99, JAVA</p>

	<p style="margin-left:11%;">Full Unicode, in terms of
	<b>uint16_t</b> or <b>uint32_t</b></p>

	<p style="margin-left:22%;">(with machine dependent
	endianness and alignment) <br>
	UCS−2−INTERNAL, UCS−4−INTERNAL</p>

	<p style="margin-left:11%;">Locale dependent, in terms of
	<b>char</b> or <b>wchar_t</b></p>

	<p style="margin-left:22%;">(with machine dependent
	endianness and alignment, and with semantics depending on
	the OS and the current LC_CTYPE locale facet) <br>
	char, wchar_t</p>

	<p style="margin-left:11%; margin-top: 1em">When configured
	with the option
	<b>−−enable−extra−encodings</b>, it
	also provides support for a few extra encodings: <br>
	European languages</p>


	<p style="margin-left:22%;">CP{437,737,775,852,853,855,857,858,860,861,863,865,869,1125}</p>

	<p style="margin-left:11%;">Semitic languages</p>

	<p style="margin-left:22%;">CP864</p>

	<p style="margin-left:11%;">Japanese</p>

	<p style="margin-left:22%;">EUC−JISX0213,
	Shift_JISX0213, ISO−2022−JP−3</p>

	<p style="margin-left:11%;">Chinese</p>

	<p style="margin-left:22%;">BIG5−2003
	(experimental)</p>

	<p style="margin-left:11%;">Turkmen</p>

	<p style="margin-left:22%;">TDS565</p>

	<p style="margin-left:11%;">Platform specifics</p>

	<p style="margin-left:22%;">ATARIST,
	RISCOS−LATIN1</p>

	<p style="margin-left:11%; margin-top: 1em">The empty
	encoding name "" is equivalent to
	"char": it denotes the locale dependent character
	encoding.</p>

	<p style="margin-left:11%; margin-top: 1em">When the string
	"//TRANSLIT" is appended to <i>tocode</i>,
	transliteration is activated. This means that when a
	character cannot be represented in the target character set,
	it can be approximated through one or several characters
	that look similar to the original character.</p>

	<p style="margin-left:11%; margin-top: 1em">When the string
	"//IGNORE" is appended to <i>tocode</i>,
	characters that cannot be represented in the target
	character set will be silently discarded.</p>

	<p style="margin-left:11%; margin-top: 1em">The resulting
	conversion descriptor can be used with <b>iconv</b> any
	number of times. It remains valid until deallocated using
	<b>iconv_close</b>.</p>

	<p style="margin-left:11%; margin-top: 1em">A conversion
	descriptor contains a conversion state. After creation using
	<b>iconv_open</b>, the state is in the initial state. Using
	<b>iconv</b> modifies the descriptor’s conversion
	state. (This implies that a conversion descriptor can not be
	used in multiple threads simultaneously.) To bring the state
	back to the initial state, use <b>iconv</b> with NULL as
	<i>inbuf</i> argument.</p>

	<h2>RETURN VALUE
	<a name="RETURN VALUE"></a>
	</h2>


	<p style="margin-left:11%; margin-top: 1em">The
	<b>iconv_open</b> function returns a freshly allocated
	conversion descriptor. In case of error, it sets
	<b>errno</b> and returns (iconv_t)(−1).</p>

	<h2>ERRORS
	<a name="ERRORS"></a>
	</h2>


	<p style="margin-left:11%; margin-top: 1em">The following
	error can occur, among others:</p>

	<table width="100%" border="0" rules="none" frame="void"
	cellspacing="0" cellpadding="0">
	<tr valign="top" align="left">
	<td width="11%"></td>
	<td width="9%">


	<p><b>EINVAL</b></p></td>
	<td width="2%"></td>
	<td width="78%">


	<p>The conversion from <i>fromcode</i> to <i>tocode</i> is
	not supported by the implementation.</p></td></tr>
	</table>

	<h2>CONFORMING TO
	<a name="CONFORMING TO"></a>
	</h2>


	<p style="margin-left:11%; margin-top: 1em">POSIX:2001</p>

	<h2>SEE ALSO
	<a name="SEE ALSO"></a>
	</h2>



	<p style="margin-left:11%; margin-top: 1em"><b>iconv</b>(3)
	<b>iconvctl</b>(3) <b>iconv_close</b>(3)</p>
	<hr>
	</body>
	</html>