Add a small amdgpu.4 manual page.
[dragonfly.git] / lib / libc / iconv / iconv.3
1 .\" $FreeBSD: head/lib/libc/iconv/iconv.3 281550 2015-04-15 09:09:20Z tijl $
2 .\" $NetBSD: iconv.3,v 1.12 2004/08/02 13:38:21 tshiozak Exp $
3 .\"
4 .\" Copyright (c) 2003 Citrus Project,
5 .\" Copyright (c) 2009, 2010 Gabor Kovesdan <gabor@FreeBSD.org>,
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 .\"
29 .Dd August 4, 2014
30 .Dt ICONV 3
31 .Os
32 .Sh NAME
33 .Nm iconv_open ,
34 .Nm iconv_open_into ,
35 .Nm iconv_close ,
36 .Nm iconv
37 .Nd codeset conversion functions
38 .Sh LIBRARY
39 .Lb libc
40 .Sh SYNOPSIS
41 .In iconv.h
42 .Ft iconv_t
43 .Fn iconv_open "const char *dstname" "const char *srcname"
44 .Ft int
45 .Fn iconv_open_into "const char *dstname" "const char *srcname" "iconv_allocation_t *ptr"
46 .Ft int
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"
50 .Ft size_t
51 .Fn __iconv "iconv_t cd" "char ** restrict src" "size_t * restrict srcleft" "char ** restrict dst" "size_t * restrict dstleft" "uint32_t flags" "size_t * invalids"
52 .Sh DESCRIPTION
53 The
54 .Fn iconv_open
55 function opens a converter from the codeset
56 .Fa srcname
57 to the codeset
58 .Fa dstname
59 and returns its descriptor.
60 The arguments
61 .Fa srcname
62 and
63 .Fa dstname
64 accept "" and "char", which refer to the current locale encoding.
65 .Pp
66 The
67 .Fn iconv_open_into
68 creates a conversion descriptor on a preallocated space.
69 The
70 .Ft iconv_allocation_t
71 is used as a spaceholder type when allocating such space.
72 The
73 .Fa dstname
74 and
75 .Fa srcname
76 arguments are the same as in the case of
77 .Fn iconv_open .
78 The
79 .Fa ptr
80 argument is a pointer of
81 .Ft iconv_allocation_t
82 to the preallocated space.
83 .Pp
84 The
85 .Fn iconv_close
86 function closes the specified converter
87 .Fa cd .
88 .Pp
89 The
90 .Fn iconv
91 function converts the string in the buffer
92 .Fa *src
93 of length
94 .Fa *srcleft
95 bytes and stores the converted string in the buffer
96 .Fa *dst
97 of size
98 .Fa *dstleft
99 bytes.
100 After calling
101 .Fn iconv ,
102 the values pointed to by
103 .Fa src ,
104 .Fa srcleft ,
105 .Fa dst ,
106 and
107 .Fa dstleft
108 are updated as follows:
109 .Bl -tag -width 01234567
110 .It *src
111 Pointer to the byte just after the last character fetched.
112 .It *srcleft
113 Number of remaining bytes in the source buffer.
114 .It *dst
115 Pointer to the byte just after the last character stored.
116 .It *dstleft
117 Number of remainder bytes in the destination buffer.
118 .El
119 .Pp
120 If the string pointed to by
121 .Fa *src
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
127 .Fa src ,
128 .Fa srcleft ,
129 .Fa dst ,
130 and
131 .Fa dstleft
132 are updated to the state just after the last successful conversion.
133 .Pp
134 If the string pointed to by
135 .Fa *src
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.,
141 .Sq \&? ,
142 and the conversion is continued.
143 .Fn iconv
144 returns the number of such
145 .Dq invalid conversions .
146 .Pp
147 There are two special cases of
148 .Fn iconv :
149 .Bl -tag -width 0123
150 .It "src == NULL || *src == NULL"
151 If the source and/or destination codesets are stateful,
152 .Fn iconv
153 places these into their initial state.
154 .Pp
155 If both
156 .Fa dst
157 and
158 .Fa *dst
159 are
160 .No non- Ns Dv NULL ,
161 .Fn iconv
162 stores the shift sequence for the destination switching to the initial state
163 in the buffer pointed to by
164 .Fa *dst .
165 The buffer size is specified by the value pointed to by
166 .Fa dstleft
167 as above.
168 .Fn iconv
169 will fail if the buffer is too small to store the shift sequence.
170 .Pp
171 On the other hand,
172 .Fa dst
173 or
174 .Fa *dst
175 may be
176 .Dv NULL .
177 In this case, the shift sequence for the destination switching
178 to the initial state is discarded.
179 .El
180 .Pp
181 The
182 .Fn __iconv
183 function works just like
184 .Fn iconv
185 but if
186 .Fn iconv
187 fails, the invalid character count is lost there.
188 This is a not bug rather a limitation of
189 .St -p1003.1-2008 ,
190 so
191 .Fn __iconv
192 is provided as an alternative but non-standard interface.
193 It also has a flags argument, where currently the following
194 flags can be passed:
195 .Bl -tag -width 0123
196 .It Dv __ICONV_F_HIDE_INVALID
197 Skip invalid characters, instead of returning with an error.
198 .El
199 .Sh RETURN VALUES
200 Upon successful completion of
201 .Fn iconv_open ,
202 it returns a conversion descriptor.
203 Otherwise,
204 .Fn iconv_open
205 returns (iconv_t)\-1 and sets errno to indicate the error.
206 .Pp
207 Upon successful completion of
208 .Fn iconv_open_into ,
209 it returns 0.
210 Otherwise,
211 .Fn iconv_open_into
212 returns \-1, and sets errno to indicate the error.
213 .Pp
214 Upon successful completion of
215 .Fn iconv_close ,
216 it returns 0.
217 Otherwise,
218 .Fn iconv_close
219 returns \-1 and sets errno to indicate the error.
220 .Pp
221 Upon successful completion of
222 .Fn iconv ,
223 it returns the number of
224 .Dq invalid
225 conversions.
226 Otherwise,
227 .Fn iconv
228 returns (size_t)\-1 and sets errno to indicate the error.
229 .Sh ERRORS
230 The
231 .Fn iconv_open
232 function may cause an error in the following cases:
233 .Bl -tag -width Er
234 .It Bq Er ENOMEM
235 Memory is exhausted.
236 .It Bq Er EINVAL
237 There is no converter specified by
238 .Fa srcname
239 and
240 .Fa dstname .
241 .El
242 The
243 .Fn iconv_open_into
244 function may cause an error in the following cases:
245 .Bl -tag -width Er
246 .It Bq Er EINVAL
247 There is no converter specified by
248 .Fa srcname
249 and
250 .Fa dstname .
251 .El
252 .Pp
253 The
254 .Fn iconv_close
255 function may cause an error in the following case:
256 .Bl -tag -width Er
257 .It Bq Er EBADF
258 The conversion descriptor specified by
259 .Fa cd
260 is invalid.
261 .El
262 .Pp
263 The
264 .Fn iconv
265 function may cause an error in the following cases:
266 .Bl -tag -width Er
267 .It Bq Er EBADF
268 The conversion descriptor specified by
269 .Fa cd
270 is invalid.
271 .It Bq Er EILSEQ
272 The string pointed to by
273 .Fa *src
274 contains a byte sequence which does not describe a valid character of
275 the source codeset.
276 .It Bq Er E2BIG
277 The output buffer pointed to by
278 .Fa *dst
279 is too small to store the result string.
280 .It Bq Er EINVAL
281 The string pointed to by
282 .Fa *src
283 terminates with an incomplete character or shift sequence.
284 .El
285 .Sh SEE ALSO
286 .Xr iconv 1 ,
287 .Xr mkcsmapper 1 ,
288 .Xr mkesdb 1 ,
289 .Xr __iconv_get_list 3 ,
290 .Xr iconv_canonicalize 3 ,
291 .Xr iconvctl 3 ,
292 .Xr iconvlist 3
293 .Sh STANDARDS
294 The
295 .Fn iconv_open ,
296 .Fn iconv_close ,
297 and
298 .Fn iconv
299 functions conform to
300 .St -p1003.1-2008 .
301 .Pp
302 The
303 .Fn iconv_open_into
304 function is a GNU-specific extension and it is not part of any standard,
305 thus its use may break portability.
306 The
307 .Fn __iconv
308 function is an own extension and it is not part of any standard,
309 thus its use may break portability.