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