source: trunk/third/libiconv/man/iconv_open.3.html @ 18195

Revision 18195, 16.0 KB checked in by ghudson, 22 years ago (diff)
This commit was generated by cvs2svn to compensate for changes in r18194, which included commits to RCS files with non-trunk default branches.
Line 
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%">
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 &lt;iconv.h&gt;
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%">
167Thai</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%">
173TIS-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%">
179Laotian</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%">
185MuleLao-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%">
191Vietnamese</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%">
197VISCII, 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%">
203Platform 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%">
209HP-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%">
215Full 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%">
221UTF-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%">
227UCS-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%">
233UCS-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%">
239UTF-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%">
245UTF-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%">
251UTF-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%">
257C99, 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%">
263Full 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
271alignment)</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%">
277UCS-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%">
283Locale 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
291semantics depending on the OS and the current LC_CTYPE
292locale 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%">
298char, 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%">
304When configured with the option
305<b>--enable-extra-encodings</b>, it also provides support
306for 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%">
312European 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%">
325Semitic 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%">
331CP864</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%">
337Japanese</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%">
343EUC-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%">
349Turkmen</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%">
355TDS565</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%">
361Platform 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%">
367RISCOS-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%">
373The empty encoding name &quot;&quot; is equivalent to
374&quot;char&quot;: it denotes the locale dependent character
375encoding.</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%">
381When the string &quot;//TRANSLIT&quot; is appended to
382<i>tocode</i>, transliteration is activated. This means that
383when a character cannot be represented in the target
384character set, it can be approximated through one or several
385similarly 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%">
391When the string &quot;//IGNORE&quot; is appended to
392<i>tocode</i>, characters that cannot be represented in the
393target character set will be silently
394discarded.</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%">
400The resulting conversion descriptor can be used with
401<b>iconv</b> any number of times. It remains valid until
402deallocated 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%">
408A conversion descriptor contains a conversion state. After
409creation using <b>iconv_open</b>, the state is in the
410initial state. Using <b>iconv</b> modifies the descriptor's
411conversion state. (This implies that a conversion descriptor
412can not be used in multiple threads simultaneously.) To
413bring the state back to the initial state, use <b>iconv</b>
414with 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%">
422The <b>iconv_open</b> function returns a freshly allocated
423conversion 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%">
432The 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%">
444The conversion from <i>fromcode</i> to <i>tocode</i> is not
445supported 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%">
453UNIX98</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>
Note: See TracBrowser for help on using the repository browser.