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