Debian Codegraph @

upstream/debian-trixie/man3/iconv.3

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