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 2017-09-15 "GNU" "Linux Programmer's Manual"
20 iconv \- perform character set conversion
25 .BI "size_t iconv(iconv_t " cd ,
26 .BI " char **" inbuf ", size_t *" inbytesleft ,
27 .BI " char **" outbuf ", size_t *" 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.
127 In case of error, it sets \fIerrno\fP and returns
130 The following errors can occur, among others:
133 There is not sufficient room at \fI*outbuf\fP.
136 An invalid multibyte sequence has been encountered in the input.
139 An incomplete multibyte sequence has been encountered in the input.
141 This function is available in glibc since version 2.1.
143 For an explanation of the terms used in this section, see
149 Interface Attribute Value
152 T} Thread safety MT-Safe race:cd
157 function is MT-Safe, as long as callers arrange for
158 mutual exclusion on the
162 POSIX.1-2001, POSIX.1-2008.
164 In each series of calls to
166 the last should be one with \fIinbuf\fP or \fI*inbuf\fP equal to NULL,
167 in order to flush out any partially converted input.
175 this does not mean that the objects they point can be interpreted
176 as C strings or as arrays of characters:
177 the interpretation of character byte sequences is
178 handled internally by the conversion functions.
179 In some encodings, a zero byte may be a valid part of a multibyte character.
183 must ensure that the pointers passed to the function are suitable
184 for accessing characters in the appropriate character set.
185 This includes ensuring correct alignment on platforms that have
186 tight restrictions on alignment.