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 "January 24, 2009" "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:2001, BIG5\-HKSCS:1999, ISO\-2022\-CN, ISO\-2022\-CN\-EXT
55: .TP
56: Korean
57: .nf
58: .fi
59: EUC\-KR, CP949, ISO\-2022\-KR, JOHAB
60: .TP
61: Armenian
62: .nf
63: .fi
64: ARMSCII\-8
65: .TP
66: Georgian
67: .nf
68: .fi
69: Georgian\-Academy, Georgian\-PS
70: .TP
71: Tajik
72: .nf
73: .fi
74: KOI8\-T
75: .TP
76: Kazakh
77: .nf
78: .fi
79: PT154, RK1048
80: .TP
81: Thai
82: .nf
83: .fi
84: TIS\-620, CP874, MacThai
85: .TP
86: Laotian
87: .nf
88: .fi
89: MuleLao\-1, CP1133
90: .TP
91: Vietnamese
92: .nf
93: .fi
94: VISCII, TCVN, CP1258
95: .TP
96: Platform specifics
97: .nf
98: .fi
99: HP\-ROMAN8, NEXTSTEP
100: .TP
101: Full Unicode
102: .nf
103: .fi
104: UTF\-8
105: .nf
106: .fi
107: UCS\-2, UCS\-2BE, UCS\-2LE
108: .nf
109: .fi
110: UCS\-4, UCS\-4BE, UCS\-4LE
111: .nf
112: .fi
113: UTF\-16, UTF\-16BE, UTF\-16LE
114: .nf
115: .fi
116: UTF\-32, UTF\-32BE, UTF\-32LE
117: .nf
118: .fi
119: UTF\-7
120: .nf
121: .fi
122: C99, JAVA
123: .TP
124: Full Unicode, in terms of \fBuint16_t\fP or \fBuint32_t\fP
125: (with machine dependent endianness and alignment)
126: .nf
127: .fi
128: UCS\-2\-INTERNAL, UCS\-4\-INTERNAL
129: .TP
130: Locale dependent, in terms of \fBchar\fP or \fBwchar_t\fP
131: (with machine dependent endianness and alignment, and with semantics
132: depending on the OS and the current LC_CTYPE locale facet)
133: .nf
134: .fi
135: char, wchar_t
136: .PP
137: When configured with the option \fB\-\-enable\-extra\-encodings\fP, it also
138: provides support for a few extra encodings:
139: .TP
140: European languages
141: .nf
142: CP{437,737,775,852,853,855,857,858,860,861,863,865,869,1125}
143: .fi
144: .TP
145: Semitic languages
146: .nf
147: .fi
148: CP864
149: .TP
150: Japanese
151: .nf
152: .fi
153: EUC\-JISX0213, Shift_JISX0213, ISO\-2022\-JP\-3
154: .TP
155: Chinese
156: .nf
157: .fi
158: BIG5\-2003 (experimental)
159: .TP
160: Turkmen
161: .nf
162: .fi
163: TDS565
164: .TP
165: Platform specifics
166: .nf
167: .fi
168: ATARIST, RISCOS\-LATIN1
169: .PP
170: The empty encoding name "" is equivalent to "char": it denotes the
171: locale dependent character encoding.
172: .PP
173: When the string "//TRANSLIT" is appended to \fItocode\fP, transliteration
174: is activated. This means that when a character cannot be represented in the
175: target character set, it can be approximated through one or several characters
176: that look similar to the original character.
177: .PP
178: When the string "//IGNORE" is appended to \fItocode\fP, characters that
179: cannot be represented in the target character set will be silently discarded.
180: .PP
181: The resulting conversion descriptor can be used with \fBiconv\fP any number
182: of times. It remains valid until deallocated using \fBiconv_close\fP.
183: .PP
184: A conversion descriptor contains a conversion state. After creation using
185: \fBiconv_open\fP, the state is in the initial state. Using \fBiconv\fP
186: modifies the descriptor's conversion state. (This implies that a conversion
187: descriptor can not be used in multiple threads simultaneously.) To bring the
188: state back to the initial state, use \fBiconv\fP with NULL as \fIinbuf\fP
189: argument.
190: .SH "RETURN VALUE"
191: The \fBiconv_open\fP function returns a freshly allocated conversion
192: descriptor. In case of error, it sets \fBerrno\fP and returns (iconv_t)(\-1).
193: .SH ERRORS
194: The following error can occur, among others:
195: .TP
196: .B EINVAL
197: The conversion from \fIfromcode\fP to \fItocode\fP is not supported by the
198: implementation.
199: .SH "CONFORMING TO"
200: POSIX:2001
201: .SH "SEE ALSO"
202: .BR iconv (3)
203: .BR iconvctl (3)
204: .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