1.\" $NetBSD: src/lib/libc/iconv/iconv.3,v 1.12 2004/08/02 13:38:21 tshiozak Exp $ 2.\" $DragonFly: src/lib/libc/iconv/iconv.3,v 1.2 2007/06/30 19:03:52 swildner Exp $ 3.\" 4.\" Copyright (c)2003 Citrus Project, 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 1, 2004 29.Dt ICONV 3 30.Os 31.\" ---------------------------------------------------------------------- 32.Sh NAME 33.Nm iconv_open , 34.Nm iconv_close , 35.Nm iconv 36.Nd codeset conversion functions 37.\" ---------------------------------------------------------------------- 38.Sh LIBRARY 39.Lb libc 40.\" ---------------------------------------------------------------------- 41.Sh SYNOPSIS 42.In iconv.h 43.Ft iconv_t 44.Fn iconv_open "const char *dstname" "const char *srcname" 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.\" ---------------------------------------------------------------------- 50.Sh DESCRIPTION 51The 52.Fn iconv_open 53function opens a converter from the codeset 54.Fa srcname 55to the codeset 56.Fa dstname 57and returns its descriptor. 58.Pp 59The 60.Fn iconv_close 61function closes the specified converter 62.Fa cd . 63.Pp 64The 65.Fn iconv 66function converts the string in the buffer 67.Fa *src 68of length 69.Fa *srcleft 70bytes and stores the converted string in the buffer 71.Fa *dst 72of size 73.Fa *dstleft 74bytes. 75After calling 76.Fn iconv , 77the values pointed to by 78.Fa src , 79.Fa srcleft , 80.Fa dst , 81and 82.Fa dstleft 83are updated as follows: 84.Bl -tag -width 01234567 85.It *src 86Pointer to the byte just after the last character fetched. 87.It *srcleft 88Number of remaining bytes in the source buffer. 89.It *dst 90Pointer to the byte just after the last character stored. 91.It *dstleft 92Number of remainder bytes in the destination buffer. 93.El 94.Pp 95If the string pointed to by 96.Fa *src 97contains a byte sequence which is not a valid character in the source 98codeset, the conversion stops just after the last successful conversion. 99If the output buffer is too small to store the converted 100character, the conversion also stops in the same way. 101In these cases, the values pointed to by 102.Fa src , 103.Fa srcleft , 104.Fa dst , 105and 106.Fa dstleft 107are updated to the state just after the last successful conversion. 108.Pp 109If the string pointed to by 110.Fa *src 111contains a character which is valid under the source codeset but 112can not be converted to the destination codeset, 113the character is replaced by an 114.Dq invalid character 115which depends on the destination codeset, e.g., 116.Sq \&? , 117and the conversion is continued. 118.Fn iconv 119returns the number of such 120.Dq invalid conversions . 121.Pp 122There are two special cases of 123.Fn iconv : 124.Bl -tag -width 0123 125.It "src == NULL || *src == NULL" 126.\" 127If the source and/or destination codesets are stateful, 128.Fn iconv 129places these into their initial state. 130.Pp 131If both 132.Fa dst 133and 134.Fa *dst 135are 136.No non- Ns Dv NULL , 137.Fn iconv 138stores the shift sequence for the destination switching to the initial state 139in the buffer pointed to by 140.Fa *dst . 141The buffer size is specified by the value pointed to by 142.Fa dstleft 143as above. 144.Fn iconv 145will fail if the buffer is too small to store the shift sequence. 146.Pp 147On the other hand, 148.Fa dst 149or 150.Fa *dst 151may be 152.Dv NULL . 153In this case, the shift sequence for the destination switching 154to the initial state is discarded. 155.El 156.\" ---------------------------------------------------------------------- 157.Sh RETURN VALUES 158Upon successful completion of 159.Fn iconv_open , 160it returns a conversion descriptor. 161Otherwise, 162.Fn iconv_open 163returns (iconv_t)\-1 and sets 164.Va errno 165to indicate the error. 166.Pp 167Upon successful completion of 168.Fn iconv_close , 169it returns 0. 170Otherwise, 171.Fn iconv_close 172returns \-1 and sets 173.Va errno 174to indicate the error. 175.Pp 176Upon successful completion of 177.Fn iconv , 178it returns the number of 179.Dq invalid 180conversions. 181Otherwise, 182.Fn iconv 183returns (size_t)\-1 and sets 184.Va errno 185to indicate the error. 186.\" ---------------------------------------------------------------------- 187.Sh ERRORS 188The 189.Fn iconv_open 190function may cause an error in the following cases: 191.Bl -tag -width Er 192.It Bq Er ENOMEM 193Memory is exhausted. 194.It Bq Er EINVAL 195There is no converter specified by 196.Fa srcname 197and 198.Fa dstname . 199.El 200.Pp 201The 202.Fn iconv_close 203function may cause an error in the following case: 204.Bl -tag -width Er 205.It Bq Er EBADF 206The conversion descriptor specified by 207.Fa cd 208is invalid. 209.El 210.Pp 211The 212.Fn iconv 213function may cause an error in the following cases: 214.Bl -tag -width Er 215.It Bq Er EBADF 216The conversion descriptor specified by 217.Fa cd 218is invalid. 219.It Bq Er EILSEQ 220The string pointed to by 221.Fa *src 222contains a byte sequence which does not describe a valid character of 223the source codeset. 224.It Bq Er E2BIG 225The output buffer pointed to by 226.Fa *dst 227is too small to store the result string. 228.It Bq Er EINVAL 229The string pointed to by 230.Fa *src 231terminates with an incomplete character or shift sequence. 232.El 233.\" ---------------------------------------------------------------------- 234.Sh SEE ALSO 235.Xr iconv 1 236.\" ---------------------------------------------------------------------- 237.Sh STANDARDS 238.Fn iconv_open , 239.Fn iconv_close , 240and 241.Fn iconv 242conform to 243.St -p1003.1-2001 . 244.\" ---------------------------------------------------------------------- 245.Sh BUGS 246If 247.Fn iconv 248is aborted due to the occurrence of some error, 249the 250.Dq invalid conversion 251count mentioned above is unfortunately lost. 252