1 .\" $NetBSD: src/lib/libc/iconv/iconv.3,v 1.12 2004/08/02 13:38:21 tshiozak Exp $
2 .\" $DragonFly: src/lib/libc/iconv/iconv.3,v 1.2 2007/06/30 19:03:52 swildner Exp $
4 .\" Copyright (c)2003 Citrus Project,
5 .\" All rights reserved.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31 .\" ----------------------------------------------------------------------
36 .Nd codeset conversion functions
37 .\" ----------------------------------------------------------------------
40 .\" ----------------------------------------------------------------------
44 .Fn iconv_open "const char *dstname" "const char *srcname"
46 .Fn iconv_close "iconv_t cd"
48 .Fn iconv "iconv_t cd" "char ** restrict src" "size_t * restrict srcleft" "char ** restrict dst" "size_t * restrict dstleft"
49 .\" ----------------------------------------------------------------------
53 function opens a converter from the codeset
57 and returns its descriptor.
61 function closes the specified converter
66 function converts the string in the buffer
70 bytes and stores the converted string in the buffer
77 the values pointed to by
83 are updated as follows:
84 .Bl -tag -width 01234567
86 Pointer to the byte just after the last character fetched.
88 Number of remaining bytes in the source buffer.
90 Pointer to the byte just after the last character stored.
92 Number of remainder bytes in the destination buffer.
95 If the string pointed to by
97 contains a byte sequence which is not a valid character in the source
98 codeset, the conversion stops just after the last successful conversion.
99 If the output buffer is too small to store the converted
100 character, the conversion also stops in the same way.
101 In these cases, the values pointed to by
107 are updated to the state just after the last successful conversion.
109 If the string pointed to by
111 contains a character which is valid under the source codeset but
112 can not be converted to the destination codeset,
113 the character is replaced by an
114 .Dq invalid character
115 which depends on the destination codeset, e.g.,
117 and the conversion is continued.
119 returns the number of such
120 .Dq invalid conversions .
122 There are two special cases of
125 .It "src == NULL || *src == NULL"
127 If the source and/or destination codesets are stateful,
129 places these into their initial state.
136 .No non- Ns Dv NULL ,
138 stores the shift sequence for the destination switching to the initial state
139 in the buffer pointed to by
141 The buffer size is specified by the value pointed to by
145 will fail if the buffer is too small to store the shift sequence.
153 In this case, the shift sequence for the destination switching
154 to the initial state is discarded.
156 .\" ----------------------------------------------------------------------
158 Upon successful completion of
160 it returns a conversion descriptor.
163 returns (iconv_t)\-1 and sets
165 to indicate the error.
167 Upon successful completion of
174 to indicate the error.
176 Upon successful completion of
178 it returns the number of
183 returns (size_t)\-1 and sets
185 to indicate the error.
186 .\" ----------------------------------------------------------------------
190 function may cause an error in the following cases:
195 There is no converter specified by
203 function may cause an error in the following case:
206 The conversion descriptor specified by
213 function may cause an error in the following cases:
216 The conversion descriptor specified by
220 The string pointed to by
222 contains a byte sequence which does not describe a valid character of
225 The output buffer pointed to by
227 is too small to store the result string.
229 The string pointed to by
231 terminates with an incomplete character or shift sequence.
233 .\" ----------------------------------------------------------------------
236 .\" ----------------------------------------------------------------------
244 .\" ----------------------------------------------------------------------
248 is aborted due to the occurrence of some error,
250 .Dq invalid conversion
251 count mentioned above is unfortunately lost.