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