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