man3/iconv.3

   1 '\" t
   2 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
   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 <sato@complex.eng.hokudai.ac.jp>
  12 .\" 2000-11-15 aeb, fixed prototype
  13 .\"
  14 .TH iconv 3 (date) "Linux man-pages (unreleased)"
  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 .PP
  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 .PP
  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 .PP
  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 four 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 The input byte sequence has been entirely converted,
  84 that is, \fI*inbytesleft\fP has gone down to 0.
  85 In this case,
  86 .BR iconv ()
  87 returns the number of
  88 nonreversible conversions performed during this call.
  89 .IP \[bu]
  90 An incomplete multibyte sequence is encountered in the input, and the
  91 input byte sequence terminates after it.
  92 In this case, it sets \fIerrno\fP to
  93 \fBEINVAL\fP and returns
  94 .IR (size_t)\ \-1 .
  95 \fI*inbuf\fP is left pointing to the
  96 beginning of the incomplete multibyte sequence.
  97 .IP \[bu]
  98 The output buffer has no more room for the next converted character.
  99 In this case, it sets \fIerrno\fP to \fBE2BIG\fP and returns
 100 .IR (size_t)\ \-1 .
 101 .PP
 102 A different case is when \fIinbuf\fP is NULL or \fI*inbuf\fP is NULL, but
 103 \fIoutbuf\fP is not NULL and \fI*outbuf\fP is not NULL.
 104 In this case, the
 105 .BR iconv ()
 106 function attempts to set \fIcd\fP's conversion state to the
 107 initial state and store a corresponding shift sequence at \fI*outbuf\fP.
 108 At most \fI*outbytesleft\fP bytes, starting at \fI*outbuf\fP, will be written.
 109 If the output buffer has no more room for this reset sequence, it sets
 110 \fIerrno\fP to \fBE2BIG\fP and returns
 111 .IR (size_t)\ \-1 .
 112 Otherwise, it increments
 113 \fI*outbuf\fP and decrements \fI*outbytesleft\fP by the number of bytes
 114 written.
 115 .PP
 116 A third case is when \fIinbuf\fP is NULL or \fI*inbuf\fP is NULL, and
 117 \fIoutbuf\fP is NULL or \fI*outbuf\fP is NULL.
 118 In this case, the
 119 .BR iconv ()
 120 function sets \fIcd\fP's conversion state to the initial state.
 121 .SH RETURN VALUE
 122 The
 123 .BR iconv ()
 124 function returns the number of characters converted in a
 125 nonreversible way during this call; reversible conversions are not counted.
 126 In case of error,
 127 .BR iconv ()
 128 returns
 129 .I (size_t)\ \-1
 130 and sets
 131 .I errno
 132 to indicate the error.
 133 .SH ERRORS
 134 The following errors can occur, among others:
 135 .TP
 136 .B E2BIG
 137 There is not sufficient room at \fI*outbuf\fP.
 138 .TP
 139 .B EILSEQ
 140 An invalid multibyte sequence has been encountered in the input.
 141 .TP
 142 .B EINVAL
 143 An incomplete multibyte sequence has been encountered in the input.
 144 .SH VERSIONS
 145 This function is available since glibc 2.1.
 146 .SH ATTRIBUTES
 147 For an explanation of the terms used in this section, see
 148 .BR attributes (7).
 149 .ad l
 150 .nh
 151 .TS
 152 allbox;
 153 lbx lb lb
 154 l l l.
 155 Interface       Attribute       Value
 156 T{
 157 .BR iconv ()
 158 T}      Thread safety   MT-Safe race:cd
 159 .TE
 160 .hy
 161 .ad
 162 .sp 1
 163 .PP
 164 The
 165 .BR iconv ()
 166 function is MT-Safe, as long as callers arrange for
 167 mutual exclusion on the
 168 .I cd
 169 argument.
 170 .SH STANDARDS
 171 POSIX.1-2001, POSIX.1-2008.
 172 .SH NOTES
 173 In each series of calls to
 174 .BR iconv (),
 175 the last should be one with \fIinbuf\fP or \fI*inbuf\fP equal to NULL,
 176 in order to flush out any partially converted input.
 177 .PP
 178 Although
 179 .I inbuf
 180 and
 181 .I outbuf
 182 are typed as
 183 .IR "char\ **" ,
 184 this does not mean that the objects they point can be interpreted
 185 as C strings or as arrays of characters:
 186 the interpretation of character byte sequences is
 187 handled internally by the conversion functions.
 188 In some encodings, a zero byte may be a valid part of a multibyte character.
 189 .PP
 190 The caller of
 191 .BR iconv ()
 192 must ensure that the pointers passed to the function are suitable
 193 for accessing characters in the appropriate character set.
 194 This includes ensuring correct alignment on platforms that have
 195 tight restrictions on alignment.
 196 .SH SEE ALSO
 197 .BR iconv_close (3),
 198 .BR iconv_open (3),
 199 .BR iconvconfig (8)