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 $
4 .\" Copyright (c) 2003 Citrus Project,
5 .\" Copyright (c) 2009, 2010 Gabor Kovesdan <gabor@FreeBSD.org>,
6 .\" All rights reserved.
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
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.
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
29 .Dd September 19, 2013
37 .Nd codeset conversion functions
43 .Fn iconv_open "const char *dstname" "const char *srcname"
45 .Fn iconv_open_into "const char *dstname" "const char *srcname" "iconv_allocation_t *ptr"
47 .Fn iconv_close "iconv_t cd"
49 .Fn iconv "iconv_t cd" "char ** restrict src" "size_t * restrict srcleft" "char ** restrict dst" "size_t * restrict dstleft"
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"
55 function opens a converter from the codeset
59 and returns its descriptor.
64 accept "" and "char", which refer to the current locale encoding.
68 creates a conversion descriptor on a preallocated space.
70 .Ft iconv_allocation_t
71 is used as a spaceholder type when allocating such space.
76 arguments are the same as in the case of
80 argument is a pointer of
81 .Ft iconv_allocation_t
82 to the preallocated space.
86 function closes the specified converter
91 function converts the string in the buffer
95 bytes and stores the converted string in the buffer
102 the values pointed to by
108 are updated as follows:
109 .Bl -tag -width 01234567
111 Pointer to the byte just after the last character fetched.
113 Number of remaining bytes in the source buffer.
115 Pointer to the byte just after the last character stored.
117 Number of remainder bytes in the destination buffer.
120 If the string pointed to by
122 contains a byte sequence which is not a valid character in the source
123 codeset, the conversion stops just after the last successful conversion.
124 If the output buffer is too small to store the converted
125 character, the conversion also stops in the same way.
126 In these cases, the values pointed to by
132 are updated to the state just after the last successful conversion.
134 If the string pointed to by
136 contains a character which is valid under the source codeset but
137 can not be converted to the destination codeset,
138 the character is replaced by an
139 .Dq invalid character
140 which depends on the destination codeset, e.g.,
142 and the conversion is continued.
144 returns the number of such
145 .Dq invalid conversions .
147 There are two special cases of
150 .It "src == NULL || *src == NULL"
151 If the source and/or destination codesets are stateful,
153 places these into their initial state.
160 .No non- Ns Dv NULL ,
162 stores the shift sequence for the destination switching to the initial state
163 in the buffer pointed to by
165 The buffer size is specified by the value pointed to by
169 will fail if the buffer is too small to store the shift sequence.
177 In this case, the shift sequence for the destination switching
178 to the initial state is discarded.
183 function works just like
187 fails, the invalid character count is lost there.
188 This is a not bug rather a limitation of
192 is provided as an alternative but non-standard interface.
193 It also has a flags argument, where currently the following
196 .It __ICONV_F_HIDE_INVALID
197 Skip invalid characters, instead of returning with an error.
200 Upon successful completion of
202 it returns a conversion descriptor.
205 returns (iconv_t)\-1 and sets errno to indicate the error.
207 Upon successful completion of
208 .Fn iconv_open_into ,
212 returns \-1, and sets errno to indicate the error.
214 Upon successful completion of
219 returns \-1 and sets errno to indicate the error.
221 Upon successful completion of
223 it returns the number of
228 returns (size_t)\-1 and sets errno to indicate the error.
232 function may cause an error in the following cases:
237 There is no converter specified by
244 function may cause an error in the following cases:
247 There is no converter specified by
255 function may cause an error in the following case:
258 The conversion descriptor specified by
265 function may cause an error in the following cases:
268 The conversion descriptor specified by
272 The string pointed to by
274 contains a byte sequence which does not describe a valid character of
277 The output buffer pointed to by
279 is too small to store the result string.
281 The string pointed to by
283 terminates with an incomplete character or shift sequence.
300 function is a GNU-specific extension and it is not part of any standard,
301 thus its use may break portability.
304 function is an own extension and it is not part of any standard,
305 thus its use may break portability.