1iconv(3C) Standard C Library Functions iconv(3C)
2
3
4
6 iconv - code conversion function
7
9 Default
10 #include <iconv.h>
11
12 extern size_t iconv(iconv_t cd, const char **restrict inbuf,
13 size_t *restrict inbytesleft, char **restrict outbuf,
14 size_t *restrict outbytesleft);
15
16
17 SUSv3
18 #include <iconv.h>
19
20 size_t iconv(iconv_t cd, char **restrict inbuf,
21 size_t *restrict inbytesleft, char **restrict outbuf,
22 size_t *restrict outbytesleft);
23
24
26 The iconv() function converts the sequence of characters from one code
27 set, in the array specified by inbuf, into a sequence of corresponding
28 characters in another code set, in the array specified by outbuf. The
29 code sets are those specified in the iconv_open() call that returned
30 the conversion descriptor, cd. The inbuf argument points to a variable
31 that points to the first character in the input buffer and inbytesleft
32 indicates the number of bytes to the end of the buffer to be converted.
33 The outbuf argument points to a variable that points to the first
34 available byte in the output buffer and outbytesleft indicates the num‐
35 ber of the available bytes to the end of the buffer.
36
37
38 For state-dependent encodings, the conversion descriptor cd is placed
39 into its initial shift state by a call for which inbuf is a null
40 pointer, or for which inbuf points to a null pointer. When iconv() is
41 called in this way, and if outbuf is not a null pointer or a pointer
42 to a null pointer, and outbytesleft points to a positive value, iconv()
43 will place, into the output buffer, the byte sequence to change the
44 output buffer to its initial shift state. If the output buffer is not
45 large enough to hold the entire reset sequence, iconv() will fail and
46 set errno to E2BIG. Subsequent calls with inbuf as other than a null
47 pointer or a pointer to a null pointer cause the conversion to take
48 place from the current state of the conversion descriptor.
49
50
51 If a sequence of input bytes does not form a valid character in the
52 specified code set, conversion stops after the previous successfully
53 converted character. If the input buffer ends with an incomplete char‐
54 acter or shift sequence, conversion stops after the previous success‐
55 fully converted bytes. If the output buffer is not large enough to hold
56 the entire converted input, conversion stops just prior to the input
57 bytes that would cause the output buffer to overflow. The variable
58 pointed to by inbuf is updated to point to the byte following the last
59 byte successfully used in the conversion. The value pointed to by
60 inbytesleft is decremented to reflect the number of bytes still not
61 converted in the input buffer. The variable pointed to by outbuf is
62 updated to point to the byte following the last byte of converted out‐
63 put data. The value pointed to by outbytesleft is decremented to
64 reflect the number of bytes still available in the output buffer. For
65 state-dependent encodings, the conversion descriptor is updated to
66 reflect the shift state in effect at the end of the last successfully
67 converted byte sequence.
68
69
70 If iconv() encounters a character in the input buffer that is legal,
71 but for which an identical character does not exist in the target code
72 set, iconv() performs an implementation-defined conversion on this
73 character.
74
76 The iconv() function updates the variables pointed to by the arguments
77 to reflect the extent of the conversion and returns the number of non-
78 identical conversions performed. If the entire string in the input
79 buffer is converted, the value pointed to by inbytesleft will be 0. If
80 the input conversion is stopped due to any conditions mentioned above,
81 the value pointed to by inbytesleft will be non-zero and errno is set
82 to indicate the condition. If an error occurs iconv() returns (size_t)
83 −1 and sets errno to indicate the error.
84
86 The iconv() function will fail if:
87
88 EILSEQ Input conversion stopped due to an input byte that does not
89 belong to the input code set.
90
91
92 E2BIG Input conversion stopped due to lack of space in the output
93 buffer.
94
95
96 EINVAL Input conversion stopped due to an incomplete character or
97 shift sequence at the end of the input buffer.
98
99
100
101 The iconv() function may fail if:
102
103 EBADF The cd argument is not a valid open conversion descriptor.
104
105
107 Example 1 Using the iconv() Functions
108
109
110 The following example uses the iconv() functions:
111
112
113 #include <stdio.h>
114 #include <errno.h>
115 #include <string.h>
116 #include <iconv.h>
117 #include <stdlib.h>
118
119 /*
120 * For state-dependent encodings, changes the state of the
121 * conversion descriptor to initial shift state. Also, outputs
122 * the byte sequence to change the state to initial state.
123 * This code is assuming the iconv call for initializing the
124 * state will not fail due to lack of space in the output buffer.
125 */
126 #define INIT_SHIFT_STATE(cd, fptr, ileft, tptr, oleft) \
127 { \
128 fptr = NULL; \
129 ileft = 0; \
130 tptr = to; \
131 oleft = BUFSIZ; \
132 (void) iconv(cd, &fptr, &ileft, &tptr, &oleft); \
133 (void) fwrite(to, 1, BUFSIZ - oleft, stdout); \
134 }
135
136 int
137 main(int argc, char **argv)
138 {
139 iconv_t cd;
140 char from[BUFSIZ], to[BUFSIZ];
141 char *from_code, *to_code;
142 char *tptr;
143 const char *fptr;
144 size_t ileft, oleft, num, ret;
145
146
147 if (argc != 3) {
148 (void) fprintf(stderr,
149 "Usage: %s from_codeset to_codeset\\n", argv[0]);
150 return (1);
151 }
152
153 from_code = argv[1];
154 to_code = argv[2];
155
156 cd = iconv_open((const char *)to_code, (const char *)from_code);
157 if (cd == (iconv_t)-1) {
158 /*
159 * iconv_open failed
160 */
161 (void) fprintf(stderr,
162 "iconv_open(%s, %s) failed\\n", to_code, from_code);
163 return (1);
164 }
165
166 ileft = 0;
167 while ((ileft +=
168 (num = fread(from + ileft, 1, BUFSIZ - ileft, stdin))) > 0) {
169 if (num == 0) {
170 /*
171 * Input buffer still contains incomplete character
172 * or sequence. However, no more input character.
173 */
174
175 /*
176 * Initializes the conversion descriptor and outputs
177 * the sequence to change the state to initial state.
178 */
179 INIT_SHIFT_STATE(cd, fptr, ileft, tptr, oleft);
180 (void) iconv_close(cd);
181
182 (void) fprintf(stderr, "Conversion error\\n");
183 return (1);
184 }
185
186 fptr = from;
187 for (;;) {
188 tptr = to;
189 oleft = BUFSIZ;
190
191 ret = iconv(cd, &fptr, &ileft, &tptr, &oleft);
192 if (ret != (size_t)-1) {
193 /*
194 * iconv succeeded
195 */
196
197 /*
198 * Outputs converted characters
199 */
200 (void) fwrite(to, 1, BUFSIZ - oleft, stdout);
201 break;
202 }
203
204 /*
205 * iconv failed
206 */
207 if (errno == EINVAL) {
208 /*
209 * Incomplete character or shift sequence
210 */
211
212 /*
213 * Outputs converted characters
214 */
215 (void) fwrite(to, 1, BUFSIZ - oleft, stdout);
216 /*
217 * Copies remaining characters in input buffer
218 * to the top of the input buffer.
219 */
220 (void) memmove(from, fptr, ileft);
221 /*
222 * Tries to fill input buffer from stdin
223 */
224 break;
225 } else if (errno == E2BIG) {
226 /*
227 * Lack of space in output buffer
228 */
229
230 /*
231 * Outputs converted characters
232 */
233 (void) fwrite(to, 1, BUFSIZ - oleft, stdout);
234 /*
235 * Tries to convert remaining characters in
236 * input buffer with emptied output buffer
237 */
238 continue;
239 } else if (errno == EILSEQ) {
240 /*
241 * Illegal character or shift sequence
242 */
243
244 /*
245 * Outputs converted characters
246 */
247 (void) fwrite(to, 1, BUFSIZ - oleft, stdout);
248 /*
249 * Initializes the conversion descriptor and
250 * outputs the sequence to change the state to
251 * initial state.
252 */
253 INIT_SHIFT_STATE(cd, fptr, ileft, tptr, oleft);
254 (void) iconv_close(cd);
255
256 (void) fprintf(stderr,
257 "Illegal character or sequence\\n");
258 return (1);
259 } else if (errno == EBADF) {
260 /*
261 * Invalid conversion descriptor.
262 * Actually, this shouldn't happen here.
263 */
264 (void) fprintf(stderr, "Conversion error\\n");
265 return (1);
266 } else {
267 /*
268 * This errno is not defined
269 */
270 (void) fprintf(stderr, "iconv error\\n");
271 return (1);
272 }
273 }
274 }
275
276 /*
277 * Initializes the conversion descriptor and outputs
278 * the sequence to change the state to initial state.
279 */
280 INIT_SHIFT_STATE(cd, fptr, ileft, tptr, oleft);
281
282 (void) iconv_close(cd);
283 return (0);
284 }
285
286
288 /usr/lib/iconv/*.so
289
290 conversion modules for 32-bit
291
292
293 /usr/lib/iconv/sparcv9/*.so
294
295 conversion modules for 64-bit sparc
296
297
298 /usr/lib/iconv/amd64/*.so
299
300 conversion modules for 64-bit amd64
301
302
303 /usr/lib/iconv/geniconvtbl/binarytables/*.bt
304
305 conversion binary tables
306
307
309 See attributes(5) for descriptions of the following attributes:
310
311
312
313
314 ┌─────────────────────────────┬─────────────────────────────┐
315 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
316 ├─────────────────────────────┼─────────────────────────────┤
317 │Interface Stability │Standard │
318 ├─────────────────────────────┼─────────────────────────────┤
319 │MT-Level │MT-Safe │
320 └─────────────────────────────┴─────────────────────────────┘
321
323 geniconvtbl(1), iconv(1), iconv_close(3C), iconv_open(3C), genicon‐
324 vtbl(4), attributes(5), iconv(5), iconv_unicode(5), standards(5)
325
326
327
328SunOS 5.11 6 Oct 2004 iconv(3C)