Debian Codegraph @

upstream/debian-unstable/man3/iconv.3

raw
1 '\" t
2 .\" Copyright, Bruno Haible <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: GPL-2.0-or-later
6 .\"
7 .TH iconv 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 iconv \- perform character set conversion
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <iconv.h>
16 .P
17 .BI "size_t iconv(iconv_t " cd ,
18 .BI " char **restrict " inbuf ", size_t *restrict " inbytesleft ,
19 .BI " char **restrict " outbuf ", size_t *restrict " outbytesleft );
20 .fi
21 .SH DESCRIPTION
22 The
23 .BR iconv ()
24 function converts a sequence of characters in one character encoding
25 to a sequence of characters in another character encoding.
26 The
27 .I cd
28 argument is a conversion descriptor,
29 previously created by a call to
30 .BR iconv_open (3);
31 the conversion descriptor defines the character encodings that
32 .BR iconv ()
33 uses for the conversion.
34 The
35 .I inbuf
36 argument is the address of a variable that points to
37 the first character of the input sequence;
38 .I inbytesleft
39 indicates the number of bytes in that buffer.
40 The
41 .I outbuf
42 argument is the address of a variable that points to
43 the first byte available in the output buffer;
44 .I outbytesleft
45 indicates the number of bytes available in the output buffer.
46 .P
47 The main case is when
48 .I inbuf
49 is not NULL and
50 .I *inbuf
51 is not NULL.
52 In this case, the
53 .BR iconv ()
54 function converts the multibyte sequence
55 starting at
56 .I *inbuf
57 to a multibyte sequence starting at
58 .IR *outbuf .
59 At most
60 .I *inbytesleft
61 bytes, starting at
62 .IR *inbuf ,
63 will be read.
64 At most
65 .I *outbytesleft
66 bytes, starting at
67 .IR *outbuf ,
68 will be written.
69 .P
70 The
71 .BR iconv ()
72 function converts one multibyte character at a time,
73 and for each character conversion it increments
74 .I *inbuf
75 and decrements
76 .I *inbytesleft
77 by the number of converted input bytes,
78 it increments
79 .I *outbuf
80 and decrements
81 .I *outbytesleft
82 by the number of converted output bytes,
83 and it updates the conversion state contained in
84 .IR cd .
85 If the character encoding of the input is stateful, the
86 .BR iconv ()
87 function can also convert a sequence of input bytes
88 to an update to the conversion state without producing any output bytes;
89 such input is called a
90 .IR shift\~sequence .
91 The conversion can stop for five reasons:
92 .IP \[bu] 3
93 An invalid multibyte sequence is encountered in the input.
94 In this case,
95 it sets
96 .I errno
97 to
98 .B EILSEQ
99 and returns
100 .IR "(size_t)\ \-1" .
101 .I *inbuf
102 is left pointing to the beginning of the invalid multibyte sequence.
103 .IP \[bu]
104 A multibyte sequence is encountered that is valid but that
105 cannot be translated to the character encoding of the output.
106 This condition depends on the implementation and on the conversion descriptor.
107 In the GNU C library and GNU libiconv, if
108 .I cd
109 was created without the suffix
110 .B //TRANSLIT
111 or
112 .BR //IGNORE ,
113 the conversion is strict:
114 lossy conversions produce this condition.
115 If the suffix
116 .B //TRANSLIT
117 was specified,
118 transliteration can avoid this condition in some cases.
119 In the musl C library,
120 this condition cannot occur because a conversion to
121 .B \[aq]*\[aq]
122 is used as a fallback.
123 In the FreeBSD, NetBSD, and Solaris implementations of
124 .BR iconv (),
125 this condition cannot occur either,
126 because a conversion to
127 .B \[aq]?\[aq]
128 is used as a fallback.
129 When this condition is met,
130 .BR iconv ()
131 sets
132 .I errno
133 to
134 .B EILSEQ
135 and returns
136 .IR "(size_t)\ \-1" .
137 .I *inbuf
138 is left pointing to the beginning of the unconvertible multibyte sequence.
139 .IP \[bu]
140 The input byte sequence has been entirely converted,
141 that is,
142 .I *inbytesleft
143 has gone down to 0.
144 In this case,
145 .BR iconv ()
146 returns the number of
147 nonreversible conversions performed during this call.
148 .IP \[bu]
149 An incomplete multibyte sequence is encountered in the input, and the
150 input byte sequence terminates after it.
151 In this case, it sets
152 .I errno
153 to
154 .B EINVAL
155 and returns
156 .IR "(size_t)\ \-1" .
157 .I *inbuf
158 is left pointing to the
159 beginning of the incomplete multibyte sequence.
160 .IP \[bu]
161 The output buffer has no more room for the next converted character.
162 In this case, it sets
163 .I errno
164 to
165 .B E2BIG
166 and returns
167 .IR "(size_t)\ \-1" .
168 .P
169 A different case is when
170 .I inbuf
171 is NULL or
172 .I *inbuf
173 is NULL, but
174 .I outbuf
175 is not NULL and
176 .I *outbuf
177 is not NULL.
178 In this case, the
179 .BR iconv ()
180 function attempts to set
181 .IR cd 's
182 conversion state to the
183 initial state and store a corresponding shift sequence at
184 .IR *outbuf .
185 At most
186 .I *outbytesleft
187 bytes, starting at
188 .IR *outbuf ,
189 will be written.
190 If the output buffer has no more room for this reset sequence, it sets
191 .I errno
192 to
193 .B E2BIG
194 and returns
195 .IR "(size_t)\ \-1" .
196 Otherwise, it increments
197 .I *outbuf
198 and decrements
199 .I *outbytesleft
200 by the number of bytes
201 written.
202 .P
203 A third case is when
204 .I inbuf
205 is NULL or
206 .I *inbuf
207 is NULL, and
208 .I outbuf
209 is NULL or
210 .I *outbuf
211 is NULL.
212 In this case, the
213 .BR iconv ()
214 function sets
215 .IR cd 's
216 conversion state to the initial state.
217 .SH RETURN VALUE
218 The
219 .BR iconv ()
220 function returns the number of characters
221 converted in a nonreversible way
222 during this call;
223 reversible conversions are not counted.
224 In case of error,
225 .BR iconv ()
226 returns
227 .I (size_t)\ \-1
228 and sets
229 .I errno
230 to indicate the error.
231 .SH ERRORS
232 The following errors can occur, among others:
233 .TP
234 .B E2BIG
235 There is not sufficient room at
236 .IR *outbuf .
237 .TP
238 .B EILSEQ
239 An invalid multibyte sequence has been encountered in the input.
240 .TP
241 .B EINVAL
242 An incomplete multibyte sequence has been encountered in the input.
243 .SH ATTRIBUTES
244 For an explanation of the terms used in this section, see
245 .BR attributes (7).
246 .TS
247 allbox;
248 lbx lb lb
249 l l l.
250 Interface Attribute Value
251 T{
252 .na
253 .nh
254 .BR iconv ()
255 T} Thread safety MT-Safe race:cd
256 .TE
257 .P
258 The
259 .BR iconv ()
260 function is MT-Safe, as long as callers arrange for
261 mutual exclusion on the
262 .I cd
263 argument.
264 .SH STANDARDS
265 POSIX.1-2008.
266 .SH HISTORY
267 glibc 2.1.
268 POSIX.1-2001.
269 .SH NOTES
270 In each series of calls to
271 .BR iconv (),
272 the last should be one with
273 .I inbuf
274 or
275 .I *inbuf
276 equal to NULL,
277 in order to flush out any partially converted input.
278 .P
279 Although
280 .I inbuf
281 and
282 .I outbuf
283 are typed as
284 .IR "char\ **" ,
285 this does not mean that the objects they point can be interpreted
286 as C strings or as arrays of characters:
287 the interpretation of character byte sequences is
288 handled internally by the conversion functions.
289 In some encodings, a zero byte may be a valid part of a multibyte character.
290 .P
291 The caller of
292 .BR iconv ()
293 must ensure that the pointers passed to the function are suitable
294 for accessing characters in the appropriate character set.
295 This includes ensuring correct alignment on platforms that have
296 tight restrictions on alignment.
297 .SH SEE ALSO
298 .BR iconv_close (3),
299 .BR iconv_open (3),
300 .BR iconvconfig (8)