1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
3 .\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA)
4 .\" This is free documentation; you can redistribute it and/or
5 .\" modify it under the terms of the GNU General Public License as
6 .\" published by the Free Software Foundation; either version 2 of
7 .\" the License, or (at your option) any later version.
10 .\" References consulted:
11 .\" GNU glibc-2 source code and manual
12 .\" OpenGroup's Single UNIX specification
13 .\" http://www.UNIX-systems.org/online.html
15 .\" 2000-06-30 correction by Yuichi SATO <sato@complex.eng.hokudai.ac.jp>
16 .\" 2000-11-15 aeb, fixed prototype
18 .TH ICONV 3 2021-03-22 "GNU" "Linux Programmer's Manual"
20 iconv \- perform character set conversion
25 .BI "size_t iconv(iconv_t " cd ,
26 .BI " char **restrict " inbuf ", size_t *restrict " inbytesleft ,
27 .BI " char **restrict " outbuf ", size_t *restrict " outbytesleft );
32 function converts a sequence of characters in one character encoding
33 to a sequence of characters in another character encoding.
36 argument is a conversion descriptor,
37 previously created by a call to
39 the conversion descriptor defines the character encodings that
41 uses for the conversion.
44 argument is the address of a variable that points to
45 the first character of the input sequence;
47 indicates the number of bytes in that buffer.
50 argument is the address of a variable that points to
51 the first byte available in the output buffer;
53 indicates the number of bytes available in the output buffer.
55 The main case is when \fIinbuf\fP is not NULL and \fI*inbuf\fP is not NULL.
58 function converts the multibyte sequence
59 starting at \fI*inbuf\fP to a multibyte sequence starting at \fI*outbuf\fP.
60 At most \fI*inbytesleft\fP bytes, starting at \fI*inbuf\fP, will be read.
61 At most \fI*outbytesleft\fP bytes, starting at \fI*outbuf\fP, will be written.
65 function converts one multibyte character at a time, and for
66 each character conversion it increments \fI*inbuf\fP and decrements
67 \fI*inbytesleft\fP by the number of converted input bytes, it increments
68 \fI*outbuf\fP and decrements \fI*outbytesleft\fP by the number of converted
69 output bytes, and it updates the conversion state contained in \fIcd\fP.
70 If the character encoding of the input is stateful, the
72 function can also convert a sequence of input bytes
73 to an update to the conversion state without producing any output bytes;
74 such input is called a \fIshift sequence\fP.
75 The conversion can stop for four reasons:
77 An invalid multibyte sequence is encountered in the input.
79 it sets \fIerrno\fP to \fBEILSEQ\fP and returns
82 is left pointing to the beginning of the invalid multibyte sequence.
84 The input byte sequence has been entirely converted,
85 that is, \fI*inbytesleft\fP has gone down to 0.
89 nonreversible conversions performed during this call.
91 An incomplete multibyte sequence is encountered in the input, and the
92 input byte sequence terminates after it.
93 In this case, it sets \fIerrno\fP to
94 \fBEINVAL\fP and returns
96 \fI*inbuf\fP is left pointing to the
97 beginning of the incomplete multibyte sequence.
99 The output buffer has no more room for the next converted character.
100 In this case, it sets \fIerrno\fP to \fBE2BIG\fP and returns
103 A different case is when \fIinbuf\fP is NULL or \fI*inbuf\fP is NULL, but
104 \fIoutbuf\fP is not NULL and \fI*outbuf\fP is not NULL.
107 function attempts to set \fIcd\fP's conversion state to the
108 initial state and store a corresponding shift sequence at \fI*outbuf\fP.
109 At most \fI*outbytesleft\fP bytes, starting at \fI*outbuf\fP, will be written.
110 If the output buffer has no more room for this reset sequence, it sets
111 \fIerrno\fP to \fBE2BIG\fP and returns
113 Otherwise, it increments
114 \fI*outbuf\fP and decrements \fI*outbytesleft\fP by the number of bytes
117 A third case is when \fIinbuf\fP is NULL or \fI*inbuf\fP is NULL, and
118 \fIoutbuf\fP is NULL or \fI*outbuf\fP is NULL.
121 function sets \fIcd\fP's conversion state to the initial state.
125 function returns the number of characters converted in a
126 nonreversible way during this call; reversible conversions are not counted.
133 to indicate the error.
135 The following errors can occur, among others:
138 There is not sufficient room at \fI*outbuf\fP.
141 An invalid multibyte sequence has been encountered in the input.
144 An incomplete multibyte sequence has been encountered in the input.
146 This function is available in glibc since version 2.1.
148 For an explanation of the terms used in this section, see
156 Interface Attribute Value
159 T} Thread safety MT-Safe race:cd
167 function is MT-Safe, as long as callers arrange for
168 mutual exclusion on the
172 POSIX.1-2001, POSIX.1-2008.
174 In each series of calls to
176 the last should be one with \fIinbuf\fP or \fI*inbuf\fP equal to NULL,
177 in order to flush out any partially converted input.
185 this does not mean that the objects they point can be interpreted
186 as C strings or as arrays of characters:
187 the interpretation of character byte sequences is
188 handled internally by the conversion functions.
189 In some encodings, a zero byte may be a valid part of a multibyte character.
193 must ensure that the pointers passed to the function are suitable
194 for accessing characters in the appropriate character set.
195 This includes ensuring correct alignment on platforms that have
196 tight restrictions on alignment.