1.\" $FreeBSD$ 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" "const char ** restrict src" "size_t * restrict srcleft" "char ** restrict dst" "size_t * restrict dstleft" "uint32_t flags" "size_t invalids" 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. 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. 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" 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. 179.Pp 180.El 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. 198.El 199.Sh RETURN VALUES 200Upon successful completion of 201.Fn iconv_open , 202it returns a conversion descriptor. 203Otherwise, 204.Fn iconv_open 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. 213.Pp 214Upon successful completion of 215.Fn iconv_close , 216it returns 0. 217Otherwise, 218.Fn iconv_close 219returns \-1 and sets errno to indicate the error. 220.Pp 221Upon successful completion of 222.Fn iconv , 223it returns the number of 224.Dq invalid 225conversions. 226Otherwise, 227.Fn iconv 228returns (size_t)\-1 and sets errno to indicate the error. 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 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 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 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 294The 295.Fn iconv_open , 296.Fn iconv_close , 297and 298.Fn iconv 299functions conform to 300.St -p1003.1-2008 . 301.Pp 302The 303.Fn iconv_open_into 304function is a GNU-specific extension and it is not part of any standard, 305thus its use may break portability. 306The 307.Fn __iconv 308function is an own extension and it is not part of any standard, 309thus its use may break portability. 310