Penguin
Recent Changes
Annotated edit history of iconv(3) version 4, including all changes. View license author blame.
Rev Author # Line
1 perry 1 ICONV
2 !!!ICONV
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 RETURN VALUE
7 ERRORS
8 CONFORMING TO
9 SEE ALSO
10 ----
11 !!NAME
12
13
14 iconv - perform character set conversion
15 !!SYNOPSIS
16
17
18 __#include
19 __ ''cd''__,
20 char* *__ ''inbuf''__, size_t *__ ''inbytesleft''__,
21 char* *__ ''outbuf''__, size_t *__ ''outbytesleft''__);
22 __
23 !!DESCRIPTION
24
25
26 The argument ''cd'' must be a conversion descriptor
27 created using the function __iconv_open__.
28
29
30 The main case is when ''inbuf'' is not NULL and
31 ''*inbuf'' is not NULL. In this case, the __iconv__
32 function converts the multibyte sequence starting at
33 ''*inbuf'' to a multibyte sequence starting at
34 ''*outbuf''. At most ''*inbytesleft'' bytes, starting
35 at ''*inbuf'', will be read. At most ''*outbytesleft''
36 bytes, starting at ''*outbuf'', will be
37 written.
38
39
40 The __iconv__ function converts one multibyte character
41 at a time, and for each character conversion it increments
42 ''*inbuf'' and decrements ''*inbytesleft'' by the
43 number of converted input bytes, it increments
44 ''*outbuf'' and decrements ''*outbytesleft'' by the
45 number of converted output bytes, and it updates the
46 conversion state contained in ''cd''. The conversion can
47 stop for four reasons:
48
49
50 1. An invalid multibyte sequence is encountered in the
51 input. In this case it sets __errno__ to __EILSEQ__
52 and returns (size_t)(-1). ''*inbuf'' is left pointing to
53 the beginning of the invalid multibyte
54 sequence.
55
56
57 2. The input byte sequence has been entirely converted, i.e.
58 ''*inbytesleft'' has gone down to 0. In this case
59 __iconv__ returns the number of non-reversible
60 conversions performed during this call.
61
62
63 3. An incomplete multibyte sequence is encountered in the
64 input, and the input byte sequence terminates after it. In
65 this case it sets __errno__ to __EINVAL__ and returns
66 (size_t)(-1). ''*inbuf'' is left pointing to the
67 beginning of the incomplete multibyte sequence.
68
69
70 4. The output buffer has no more room for the next converted
71 character. In this case it sets __errno__ to __E2BIG__
72 and returns (size_t)(-1).
73
74
75 A different case is when ''inbuf'' is NULL or
76 ''*inbuf'' is NULL, but ''outbuf'' is not NULL and
77 ''*outbuf'' is not NULL. In this case, the __iconv__
78 function attempts to set ''cd'''s conversion state to the
79 initial state and store a corresponding shift sequence at
80 ''*outbuf''. At most ''*outbytesleft'' bytes, starting
81 at ''*outbuf'', will be written. If the output buffer has
82 no more room for this reset sequence, it sets __errno__
83 to __E2BIG__ and returns (size_t)(-1). Otherwise it
84 increments ''*outbuf'' and decrements
85 ''*outbytesleft'' by the number of bytes
86 written.
87
88
89 A third case is when ''inbuf'' is NULL or ''*inbuf''
90 is NULL, and ''outbuf'' is NULL or ''*outbuf'' is
91 NULL. In this case, the __iconv__ function sets
92 ''cd'''s conversion state to the initial
93 state.
94 !!RETURN VALUE
95
96
97 The __iconv__ function returns the number of characters
98 converted in a non-reversible way during this call;
99 reversible conversions are not counted. In case of error, it
100 sets __errno__ and returns (iconv_t)(-1).
101 !!ERRORS
102
103
104 The following errors can occur, among others:
105
106
107 __E2BIG__
108
109
110 There is not sufficient room at ''*outbuf''.
111
112
113 __EILSEQ__
114
115
116 An invalid multibyte sequence has been encountered in the
117 input.
118
119
120 __EINVAL__
121
122
123 An incomplete multibyte sequence has been encountered in the
124 input.
125 !!CONFORMING TO
126
127
128 UNIX98
129 !!SEE ALSO
130
131
4 perry 132 iconv_open(3), __iconv_close__(3)
1 perry 133 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.