summaryrefslogtreecommitdiffstats
path: root/lib/libc/iconv/iconv.3
blob: 939d4420a15330fde937c36c0002fe6d16727196 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
.\" $FreeBSD$
.\" $NetBSD: iconv.3,v 1.12 2004/08/02 13:38:21 tshiozak Exp $
.\"
.\" Copyright (c) 2003 Citrus Project,
.\" Copyright (c) 2009, 2010 Gabor Kovesdan <gabor@FreeBSD.org>,
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd June 16, 2010
.Dt ICONV 3
.Os
.Sh NAME
.Nm iconv_open ,
.Nm iconv_open_into ,
.Nm iconv_close ,
.Nm iconv
.Nd codeset conversion functions
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In iconv.h
.Ft iconv_t
.Fn iconv_open "const char *dstname" "const char *srcname"
.Ft int
.Fn iconv_open_into "const char *dstname" "const char *srcname" "iconv_allocation_t *ptr"
.Ft int
.Fn iconv_close "iconv_t cd"
.Ft size_t
.Fn iconv "iconv_t cd" "char ** restrict src" "size_t * restrict srcleft" "char ** restrict dst" "size_t * restrict dstleft"
.Ft size_t
.Fn __iconv "iconv_t cd" "const char ** restrict src" "size_t * restrict srcleft" "char ** restrict dst" "size_t * restrict dstleft" "uint32_t flags" "size_t invalids"
.Sh DESCRIPTION
The
.Fn iconv_open
function opens a converter from the codeset
.Fa srcname
to the codeset
.Fa dstname
and returns its descriptor.
The arguments
.Fa srcname
and
.Fa dstname
accept "" and "char", which refer to the current locale encoding.
.Pp
The
.Fn iconv_open_into
creates a conversion descriptor on a preallocated space.
The
.Ft iconv_allocation_t
is used as a spaceholder type when allocating such space.
The
.Fa dstname
and
.Fa srcname
arguments are the same as in the case of
.Fn iconv_open .
The
.Fa ptr
argument is a pointer of
.Ft iconv_allocation_t
to the preallocated space.
.Pp
The
.Fn iconv_close
function closes the specified converter
.Fa cd .
.Pp
The
.Fn iconv
function converts the string in the buffer
.Fa *src
of length
.Fa *srcleft
bytes and stores the converted string in the buffer
.Fa *dst
of size
.Fa *dstleft
bytes.
After calling
.Fn iconv ,
the values pointed to by
.Fa src ,
.Fa srcleft ,
.Fa dst ,
and
.Fa dstleft
are updated as follows:
.Bl -tag -width 01234567
.It *src
Pointer to the byte just after the last character fetched.
.It *srcleft
Number of remaining bytes in the source buffer.
.It *dst
Pointer to the byte just after the last character stored.
.It *dstleft
Number of remainder bytes in the destination buffer.
.El
.Pp
If the string pointed to by
.Fa *src
contains a byte sequence which is not a valid character in the source
codeset, the conversion stops just after the last successful conversion.
If the output buffer is too small to store the converted
character, the conversion also stops in the same way.
In these cases, the values pointed to by
.Fa src ,
.Fa srcleft ,
.Fa dst ,
and
.Fa dstleft
are updated to the state just after the last successful conversion.
.Pp
If the string pointed to by
.Fa *src
contains a character which is valid under the source codeset but
can not be converted to the destination codeset,
the character is replaced by an
.Dq invalid character
which depends on the destination codeset, e.g.,
.Sq \&? ,
and the conversion is continued.
.Fn iconv
returns the number of such
.Dq invalid conversions .
.Pp
There are two special cases of
.Fn iconv :
.Bl -tag -width 0123
.It "src == NULL || *src == NULL"
If the source and/or destination codesets are stateful,
.Fn iconv
places these into their initial state.
.Pp
If both
.Fa dst
and
.Fa *dst
are
.No non- Ns Dv NULL ,
.Fn iconv
stores the shift sequence for the destination switching to the initial state
in the buffer pointed to by
.Fa *dst .
The buffer size is specified by the value pointed to by
.Fa dstleft
as above.
.Fn iconv
will fail if the buffer is too small to store the shift sequence.
.Pp
On the other hand,
.Fa dst
or
.Fa *dst
may be
.Dv NULL .
In this case, the shift sequence for the destination switching
to the initial state is discarded.
.Pp
.El
The
.Fn __iconv
function works just like
.Fn iconv
but if
.Fn iconv
fails, the invalid character count is lost there.
This is a not bug rather a limitation of
.St -p1003.1-2008 ,
so
.Fn __iconv
is provided as an alternative but non-standard interface.
It also has a flags argument, where currently the following
flags can be passed:
.Bl -tag -width 0123
.It __ICONV_F_HIDE_INVALID
Skip invalid characters, instead of returning with an error.
.El
.Sh RETURN VALUES
Upon successful completion of
.Fn iconv_open ,
it returns a conversion descriptor.
Otherwise,
.Fn iconv_open
returns (iconv_t)\-1 and sets errno to indicate the error.
.Pp
Upon successful completion of
.Fn iconv_open_into ,
it returns 0.
Otherwise,
.Fn iconv_open_into
returns \-1, and sets errno to indicate the error.
.Pp
Upon successful completion of
.Fn iconv_close ,
it returns 0.
Otherwise,
.Fn iconv_close
returns \-1 and sets errno to indicate the error.
.Pp
Upon successful completion of
.Fn iconv ,
it returns the number of
.Dq invalid
conversions.
Otherwise,
.Fn iconv
returns (size_t)\-1 and sets errno to indicate the error.
.Sh ERRORS
The
.Fn iconv_open
function may cause an error in the following cases:
.Bl -tag -width Er
.It Bq Er ENOMEM
Memory is exhausted.
.It Bq Er EINVAL
There is no converter specified by
.Fa srcname
and
.Fa dstname .
.El
The
.Fn iconv_open_into
function may cause an error in the following cases:
.Bl -tag -width Er
.It Bq Er EINVAL
There is no converter specified by
.Fa srcname
and
.Fa dstname .
.El
.Pp
The
.Fn iconv_close
function may cause an error in the following case:
.Bl -tag -width Er
.It Bq Er EBADF
The conversion descriptor specified by
.Fa cd
is invalid.
.El
.Pp
The
.Fn iconv
function may cause an error in the following cases:
.Bl -tag -width Er
.It Bq Er EBADF
The conversion descriptor specified by
.Fa cd
is invalid.
.It Bq Er EILSEQ
The string pointed to by
.Fa *src
contains a byte sequence which does not describe a valid character of
the source codeset.
.It Bq Er E2BIG
The output buffer pointed to by
.Fa *dst
is too small to store the result string.
.It Bq Er EINVAL
The string pointed to by
.Fa *src
terminates with an incomplete character or shift sequence.
.El
.Sh SEE ALSO
.Xr iconv 1 ,
.Xr mkcsmapper 1 ,
.Xr mkesdb 1
.Sh STANDARDS
The
.Fn iconv_open ,
.Fn iconv_close ,
and
.Fn iconv
functions conform to
.St -p1003.1-2008 .
.Pp
The
.Fn iconv_open_into
function is a GNU-specific extension and it is not part of any standard,
thus its use may break portability.
The
.Fn __iconv
function is an own extension and it is not part of any standard,
thus its use may break portability.
OpenPOWER on IntegriCloud