1.\" $NetBSD: iconv.3,v 1.14 2010/05/05 22:07:58 wiz 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 May 5, 2010 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" "const 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 the source and/or destination codesets are stateful, 122.Fn iconv 123places these into their initial state. 124There are two special cases of 125.Fn iconv : 126.Bl -enum -offset indent 127.It 128If both 129.Fa dst 130and 131.Fa *dst 132are 133.No non- Ns Dv NULL , 134.Fn iconv 135stores the shift sequence for the destination switching to the initial state 136in the buffer pointed to by 137.Fa *dst . 138The buffer size is specified by the value pointed to by 139.Fa dstleft 140as above. 141.Fn iconv 142will fail if the buffer is too small to store the shift sequence. 143.It 144On the other hand, 145.Fa dst 146or 147.Fa *dst 148may be 149.Dv NULL . 150In this case, the shift sequence for the destination switching 151to the initial state is discarded. 152.El 153.\" ---------------------------------------------------------------------- 154.Sh RETURN VALUES 155Upon successful completion of 156.Fn iconv_open , 157it returns a conversion descriptor. 158Otherwise, 159.Fn iconv_open 160returns (iconv_t)\-1 and sets 161.Va errno 162to indicate the error. 163.Pp 164Upon successful completion of 165.Fn iconv_close , 166it returns 0. 167Otherwise, 168.Fn iconv_close 169returns \-1 and sets errno to indicate the error. 170.Pp 171Upon successful completion of 172.Fn iconv , 173it returns the number of 174.Dq invalid 175conversions. 176Otherwise, 177.Fn iconv 178returns (size_t)\-1 and sets errno to indicate the error. 179.\" ---------------------------------------------------------------------- 180.Sh ERRORS 181The 182.Fn iconv_open 183function may cause an error in the following cases: 184.Bl -tag -width Er 185.It Bq Er EINVAL 186There is no converter specified by 187.Fa srcname 188and 189.Fa dstname . 190.It Bq Er ENOMEM 191Memory is exhausted. 192.El 193.Pp 194The 195.Fn iconv_close 196function may cause an error in the following case: 197.Bl -tag -width Er 198.It Bq Er EBADF 199The conversion descriptor specified by 200.Fa cd 201is invalid. 202.El 203.Pp 204The 205.Fn iconv 206function may cause an error in the following cases: 207.Bl -tag -width Er 208.It Bq Er E2BIG 209The output buffer pointed to by 210.Fa *dst 211is too small to store the result string. 212.It Bq Er EBADF 213The conversion descriptor specified by 214.Fa cd 215is invalid. 216.It Bq Er EILSEQ 217The string pointed to by 218.Fa *src 219contains a byte sequence which does not describe a valid character of 220the source codeset. 221.It Bq Er EINVAL 222The string pointed to by 223.Fa *src 224terminates with an incomplete character or shift sequence. 225.El 226.\" ---------------------------------------------------------------------- 227.Sh SEE ALSO 228.Xr iconv 1 229.\" ---------------------------------------------------------------------- 230.Sh STANDARDS 231.Fn iconv_open , 232.Fn iconv_close , 233and 234.Fn iconv 235conform to 236.St -p1003.1-2001 . 237.\" ---------------------------------------------------------------------- 238.Sh BUGS 239If 240.Fn iconv 241is aborted due to the occurrence of some error, 242the 243.Dq invalid conversion 244count mentioned above is unfortunately lost. 245