1.\" $NetBSD: iconv.3,v 1.24 2019/10/24 18:17:59 kamil Exp $ 2.\" 3.\" Copyright (c)2003 Citrus Project, 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.Dd October 24, 2019 28.Dt ICONV 3 29.Os 30.\" ---------------------------------------------------------------------- 31.Sh NAME 32.Nm iconv_open , 33.Nm iconv_close , 34.Nm iconv 35.Nd codeset conversion functions 36.\" ---------------------------------------------------------------------- 37.Sh LIBRARY 38.Lb libc 39.\" ---------------------------------------------------------------------- 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_close "iconv_t cd" 46.Ft size_t 47.Fn iconv "iconv_t cd" "char ** restrict src" "size_t * restrict srcleft" "char ** restrict dst" "size_t * restrict dstleft" 48.\" ---------------------------------------------------------------------- 49.Sh DESCRIPTION 50The 51.Fn iconv_open 52function opens a converter from the codeset 53.Fa srcname 54to the codeset 55.Fa dstname 56and returns its descriptor. 57.Pp 58The 59.Fn iconv_close 60function closes the specified converter 61.Fa cd . 62.Pp 63The 64.Fn iconv 65function converts the string in the buffer 66.Fa *src 67of length 68.Fa *srcleft 69bytes and stores the converted string in the buffer 70.Fa *dst 71of size 72.Fa *dstleft 73bytes. 74After calling 75.Fn iconv , 76the values pointed to by 77.Fa src , 78.Fa srcleft , 79.Fa dst , 80and 81.Fa dstleft 82are updated as follows: 83.Bl -tag -width 01234567 -offset indent 84.It Fa *src 85Pointer to the byte just after the last character fetched. 86.It Fa *srcleft 87Number of remaining bytes in the source buffer. 88.It Fa *dst 89Pointer to the byte just after the last character stored. 90.It Fa *dstleft 91Number of remainder bytes in the destination buffer. 92.El 93.Pp 94If the string pointed to by 95.Fa *src 96contains a byte sequence which is not a valid character in the source 97codeset, the conversion stops just after the last successful conversion. 98If the output buffer is too small to store the converted 99character, the conversion also stops in the same way. 100In these cases, the values pointed to by 101.Fa src , 102.Fa srcleft , 103.Fa dst , 104and 105.Fa dstleft 106are updated to the state just after the last successful conversion. 107.Pp 108If the string pointed to by 109.Fa *src 110contains a character which is valid under the source codeset but 111can not be converted to the destination codeset, 112the character is replaced by an 113.Dq invalid character 114which depends on the destination codeset, e.g., 115.Sq \&? , 116and the conversion is continued. 117.Fn iconv 118returns the number of such 119.Dq invalid conversions . 120.Pp 121If 122.Fa src 123or 124.Fa *src 125is 126.Dv NULL 127and the source and/or destination codesets are stateful, 128.Fn iconv 129places these into their initial state. 130.Bl -enum -offset indent 131.It 132If both 133.Fa dst 134and 135.Fa *dst 136are 137.No non- Ns Dv NULL , 138.Fn iconv 139stores the shift sequence for the destination switching to the initial state 140in the buffer pointed to by 141.Fa *dst . 142The buffer size is specified by the value pointed to by 143.Fa dstleft 144as above. 145.Fn iconv 146will fail if the buffer is too small to store the shift sequence. 147.It 148On the other hand, 149.Fa dst 150or 151.Fa *dst 152may be 153.Dv NULL . 154In this case, the shift sequence for the destination switching 155to the initial state is discarded. 156.El 157.\" ---------------------------------------------------------------------- 158.Sh RETURN VALUES 159Upon successful completion of 160.Fn iconv_open , 161it returns a conversion descriptor. 162Otherwise, 163.Fn iconv_open 164returns (iconv_t)\-1 and sets 165.Va errno 166to indicate the error. 167.Pp 168Upon successful completion of 169.Fn iconv_close , 170it returns 0. 171Otherwise, 172.Fn iconv_close 173returns \-1 and sets errno to indicate the error. 174.Pp 175Upon successful completion of 176.Fn iconv , 177it returns the number of 178.Dq invalid 179conversions. 180Otherwise, 181.Fn iconv 182returns (size_t)\-1 and sets errno to indicate the error. 183.\" ---------------------------------------------------------------------- 184.Sh ERRORS 185The 186.Fn iconv_open 187function may cause an error in the following cases: 188.Bl -tag -width Er 189.It Bq Er EINVAL 190There is no converter specified by 191.Fa srcname 192and 193.Fa dstname . 194.It Bq Er ENOMEM 195Memory is exhausted. 196.El 197.Pp 198The 199.Fn iconv_close 200function may cause an error in the following case: 201.Bl -tag -width Er 202.It Bq Er EBADF 203The conversion descriptor specified by 204.Fa cd 205is invalid. 206.El 207.Pp 208The 209.Fn iconv 210function may cause an error in the following cases: 211.Bl -tag -width Er 212.It Bq Er E2BIG 213The output buffer pointed to by 214.Fa *dst 215is too small to store the result string. 216.It Bq Er EBADF 217The conversion descriptor specified by 218.Fa cd 219is invalid. 220.It Bq Er EILSEQ 221The string pointed to by 222.Fa *src 223contains a byte sequence which does not describe a valid character of 224the source codeset. 225.It Bq Er EINVAL 226The string pointed to by 227.Fa *src 228terminates with an incomplete character or shift sequence. 229.El 230.\" ---------------------------------------------------------------------- 231.Sh SEE ALSO 232.Xr iconv 1 233.\" ---------------------------------------------------------------------- 234.Sh STANDARDS 235.Fn iconv_open , 236.Fn iconv_close , 237and 238.Fn iconv 239conform to 240.St -p1003.1-2001 . 241.Pp 242Historically, the definition of 243.Ft iconv 244has not been consistent across operating systems. 245This is due to an unfortunate historical mistake, documented in 246.Lk https://www5.opengroup.org/sophocles2/show_mail.tpl?&source=L&listname=austin-group-l&id=7404 "this e-mail". 247The standards page for the header file 248.In iconv.h 249defined the second argument of 250.Fn iconv 251as 252.Ft char ** , 253but the standards page for the 254.Fn iconv 255implementation defined it as 256.Ft const char ** . 257The standards committee later chose to change the function definition to 258follow the header file definition 259.Pq without const , 260even though the version with const is arguably more correct. 261.Nx 262used initially the const form. 263It was decided to reject the committee's regression and become 264.Pq technically 265incompatible. 266.Pp 267This decision was changed in 268.Nx 10 269and the 270.Fn iconv 271prototype was synchronized with the standard. 272.\" ---------------------------------------------------------------------- 273.Sh BUGS 274If 275.Fn iconv 276is aborted due to the occurrence of some error, 277the 278.Dq invalid conversion 279count mentioned above is unfortunately lost. 280