xref: /dragonfly/lib/libc/iconv/iconv.3 (revision 8e1c6f81) 
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