1: .\" Copyright (c) Bruno Haible <bruno@clisp.org>
2: .\"
3: .\" This is free documentation; you can redistribute it and/or
4: .\" modify it under the terms of the GNU General Public License as
5: .\" published by the Free Software Foundation; either version 3 of
6: .\" the License, or (at your option) any later version.
7: .\"
8: .\" References consulted:
9: .\" GNU glibc-2 source code and manual
10: .\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html
11: .\"
12: .TH ICONV_OPEN 3 "November 23, 2010" "GNU" "Linux Programmer's Manual"
13: .SH NAME
14: iconv_open \- allocate descriptor for character set conversion
15: .SH SYNOPSIS
16: .nf
17: .B #include <iconv.h>
18: .sp
19: .BI "iconv_t iconv_open (const char* " tocode ", const char* " fromcode );
20: .fi
21: .SH DESCRIPTION
22: The \fBiconv_open\fP function allocates a conversion descriptor suitable
23: for converting byte sequences from character encoding \fIfromcode\fP to
24: character encoding \fItocode\fP.
25: .PP
26: The values permitted for \fIfromcode\fP and \fItocode\fP and the supported
27: combinations are system dependent. For the libiconv library, the following
28: encodings are supported, in all combinations.
29: .TP
30: European languages
31: .nf
32: .fi
33: ASCII, ISO\-8859\-{1,2,3,4,5,7,9,10,13,14,15,16},
34: KOI8\-R, KOI8\-U, KOI8\-RU,
35: CP{1250,1251,1252,1253,1254,1257}, CP{850,866,1131},
36: Mac{Roman,CentralEurope,Iceland,Croatian,Romania},
37: Mac{Cyrillic,Ukraine,Greek,Turkish},
38: Macintosh
39: .TP
40: Semitic languages
41: .nf
42: .fi
43: ISO\-8859\-{6,8}, CP{1255,1256}, CP862, Mac{Hebrew,Arabic}
44: .TP
45: Japanese
46: .nf
47: .fi
48: EUC\-JP, SHIFT_JIS, CP932, ISO\-2022\-JP, ISO\-2022\-JP\-2, ISO\-2022\-JP\-1
49: .TP
50: Chinese
51: .nf
52: .fi
53: EUC\-CN, HZ, GBK, CP936, GB18030, EUC\-TW, BIG5, CP950, BIG5\-HKSCS,
54: BIG5\-HKSCS:2004, BIG5\-HKSCS:2001, BIG5\-HKSCS:1999, ISO\-2022\-CN,
55: ISO\-2022\-CN\-EXT
56: .TP
57: Korean
58: .nf
59: .fi
60: EUC\-KR, CP949, ISO\-2022\-KR, JOHAB
61: .TP
62: Armenian
63: .nf
64: .fi
65: ARMSCII\-8
66: .TP
67: Georgian
68: .nf
69: .fi
70: Georgian\-Academy, Georgian\-PS
71: .TP
72: Tajik
73: .nf
74: .fi
75: KOI8\-T
76: .TP
77: Kazakh
78: .nf
79: .fi
80: PT154, RK1048
81: .TP
82: Thai
83: .nf
84: .fi
85: TIS\-620, CP874, MacThai
86: .TP
87: Laotian
88: .nf
89: .fi
90: MuleLao\-1, CP1133
91: .TP
92: Vietnamese
93: .nf
94: .fi
95: VISCII, TCVN, CP1258
96: .TP
97: Platform specifics
98: .nf
99: .fi
100: HP\-ROMAN8, NEXTSTEP
101: .TP
102: Full Unicode
103: .nf
104: .fi
105: UTF\-8
106: .nf
107: .fi
108: UCS\-2, UCS\-2BE, UCS\-2LE
109: .nf
110: .fi
111: UCS\-4, UCS\-4BE, UCS\-4LE
112: .nf
113: .fi
114: UTF\-16, UTF\-16BE, UTF\-16LE
115: .nf
116: .fi
117: UTF\-32, UTF\-32BE, UTF\-32LE
118: .nf
119: .fi
120: UTF\-7
121: .nf
122: .fi
123: C99, JAVA
124: .TP
125: Full Unicode, in terms of \fBuint16_t\fP or \fBuint32_t\fP
126: (with machine dependent endianness and alignment)
127: .nf
128: .fi
129: UCS\-2\-INTERNAL, UCS\-4\-INTERNAL
130: .TP
131: Locale dependent, in terms of \fBchar\fP or \fBwchar_t\fP
132: (with machine dependent endianness and alignment, and with semantics
133: depending on the OS and the current LC_CTYPE locale facet)
134: .nf
135: .fi
136: char, wchar_t
137: .PP
138: When configured with the option \fB\-\-enable\-extra\-encodings\fP, it also
139: provides support for a few extra encodings:
140: .TP
141: European languages
142: .nf
143: CP{437,737,775,852,853,855,857,858,860,861,863,865,869,1125}
144: .fi
145: .TP
146: Semitic languages
147: .nf
148: .fi
149: CP864
150: .TP
151: Japanese
152: .nf
153: .fi
154: EUC\-JISX0213, Shift_JISX0213, ISO\-2022\-JP\-3
155: .TP
156: Chinese
157: .nf
158: .fi
159: BIG5\-2003 (experimental)
160: .TP
161: Turkmen
162: .nf
163: .fi
164: TDS565
165: .TP
166: Platform specifics
167: .nf
168: .fi
169: ATARIST, RISCOS\-LATIN1
170: .PP
171: The empty encoding name "" is equivalent to "char": it denotes the
172: locale dependent character encoding.
173: .PP
174: When the string "//TRANSLIT" is appended to \fItocode\fP, transliteration
175: is activated. This means that when a character cannot be represented in the
176: target character set, it can be approximated through one or several characters
177: that look similar to the original character.
178: .PP
179: When the string "//IGNORE" is appended to \fItocode\fP, characters that
180: cannot be represented in the target character set will be silently discarded.
181: .PP
182: The resulting conversion descriptor can be used with \fBiconv\fP any number
183: of times. It remains valid until deallocated using \fBiconv_close\fP.
184: .PP
185: A conversion descriptor contains a conversion state. After creation using
186: \fBiconv_open\fP, the state is in the initial state. Using \fBiconv\fP
187: modifies the descriptor's conversion state. (This implies that a conversion
188: descriptor can not be used in multiple threads simultaneously.) To bring the
189: state back to the initial state, use \fBiconv\fP with NULL as \fIinbuf\fP
190: argument.
191: .SH "RETURN VALUE"
192: The \fBiconv_open\fP function returns a freshly allocated conversion
193: descriptor. In case of error, it sets \fBerrno\fP and returns (iconv_t)(\-1).
194: .SH ERRORS
195: The following error can occur, among others:
196: .TP
197: .B EINVAL
198: The conversion from \fIfromcode\fP to \fItocode\fP is not supported by the
199: implementation.
200: .SH "CONFORMING TO"
201: POSIX:2001
202: .SH "SEE ALSO"
203: .BR iconv (3)
204: .BR iconvctl (3)
205: .BR iconv_close (3)
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to iconv_open.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libiconv / man