xref: /dragonfly/lib/libc/iconv/iconv.3 (revision 49781055) 
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.1 2005/03/11 23:33:53 joerg 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 errno to indicate the error.
164.Pp
165Upon successful completion of
166.Fn iconv_close ,
167it returns 0.
168Otherwise,
169.Fn iconv_close
170returns \-1 and sets errno to indicate the error.
171.Pp
172Upon successful completion of
173.Fn iconv ,
174it returns the number of
175.Dq invalid
176conversions.
177Otherwise,
178.Fn iconv
179returns (size_t)\-1 and sets errno to indicate the error.
180.\" ----------------------------------------------------------------------
181.Sh ERRORS
182The
183.Fn iconv_open
184function may cause an error in the following cases:
185.Bl -tag -width Er
186.It Bq Er ENOMEM
187Memory is exhausted.
188.It Bq Er EINVAL
189There is no converter specified by
190.Fa srcname
191and
192.Fa dstname .
193.El
194.Pp
195The
196.Fn iconv_close
197function may cause an error in the following case:
198.Bl -tag -width Er
199.It Bq Er EBADF
200The conversion descriptor specified by
201.Fa cd
202is invalid.
203.El
204.Pp
205The
206.Fn iconv
207function may cause an error in the following cases:
208.Bl -tag -width Er
209.It Bq Er EBADF
210The conversion descriptor specified by
211.Fa cd
212is invalid.
213.It Bq Er EILSEQ
214The string pointed to by
215.Fa *src
216contains a byte sequence which does not describe a valid character of
217the source codeset.
218.It Bq Er E2BIG
219The output buffer pointed to by
220.Fa *dst
221is too small to store the result string.
222.It Bq Er EINVAL
223The string pointed to by
224.Fa *src
225terminates with an incomplete character or shift sequence.
226.El
227.\" ----------------------------------------------------------------------
228.Sh SEE ALSO
229.Xr iconv 1
230.\" ----------------------------------------------------------------------
231.Sh STANDARDS
232.Fn iconv_open ,
233.Fn iconv_close ,
234and
235.Fn iconv
236conform to
237.St -p1003.1-2001 .
238.\" ----------------------------------------------------------------------
239.Sh BUGS
240If
241.Fn iconv
242is aborted due to the occurrence of some error,
243the
244.Dq invalid conversion
245count mentioned above is unfortunately lost.
246