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