| blob | 2a5ff771a8ed9cb9b4132376fe572a193db6a59b |
1 '\" te
2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH UCONV_U16TOU32 9F "Sep 18, 2007"
7 .SH NAME
8 uconv_u16tou32, uconv_u16tou8, uconv_u32tou16, uconv_u32tou8, uconv_u8tou16,
9 uconv_u8tou32 \- Unicode encoding conversion functions
10 .SH SYNOPSIS
11 .LP
12 .nf
13 #include <sys/types.h>
14 #include <sys/errno.h>
15 #include <sys/sunddi.h>
17 \fBint\fR \fBuconv_u16tou32\fR(const \fBuint16_t *\fR\fIutf16str\fR, \fBsize_t *\fR\fIutf16len\fR,
18 \fBuint32_t *\fR\fIutf32str\fR, \fBsize_t *\fR\fIutf32len\fR, \fBint\fR \fIflag\fR);
19 .fi
21 .LP
22 .nf
23 \fBint\fR \fBuconv_u16tou8\fR(const \fBuint16_t *\fR\fIutf16str\fR, \fBsize_t *\fR\fIutf16len\fR,
24 \fBuchar_t *\fR\fIutf8str\fR, \fBsize_t *\fR\fIutf8len\fR, \fBint\fR \fIflag\fR);
25 .fi
27 .LP
28 .nf
29 \fBint\fR \fBuconv_u32tou16\fR(const \fBuint32_t *\fR\fIutf32str\fR, \fBsize_t *\fR\fIutf32len\fR,
30 \fBuint16_t *\fR\fIutf16str\fR, \fBsize_t *\fR\fIutf16len\fR, \fBint\fR \fIflag\fR);
31 .fi
33 .LP
34 .nf
35 \fBint\fR \fBuconv_u32tou8\fR(const \fBuint32_t *\fR\fIutf32str\fR, \fBsize_t *\fR\fIutf32len\fR,
36 \fBuchar_t *\fR\fIutf8str\fR, \fBsize_t *\fR\fIutf8len\fR, \fBint\fR \fIflag\fR);
37 .fi
39 .LP
40 .nf
41 \fBint\fR \fBuconv_u8tou16\fR(const \fBuchar_t *\fR\fIutf8str\fR, \fBsize_t *\fR\fIutf8len\fR,
42 \fBuint16_t *\fR\fIutf16str\fR, \fBsize_t *\fR\fIutf16len\fR, \fBint\fR \fIflag\fR);
43 .fi
45 .LP
46 .nf
47 \fBint\fR \fBuconv_u8tou32\fR(const \fBuchar_t *\fR\fIutf8str\fR, \fBsize_t *\fR\fIutf8len\fR,
48 \fBuint32_t *\fR\fIutf32str\fR, \fBsize_t *\fR\fIutf32len\fR, \fBint\fR \fIflag\fR);
49 .fi
51 .SH INTERFACE LEVEL
52 .sp
53 .LP
54 Solaris DDI specific (Solaris DDI).
55 .SH PARAMETERS
56 .sp
57 .ne 2
58 .na
59 \fB\fIutf16str\fR\fR
60 .ad
61 .RS 12n
62 A pointer to a \fBUTF-16\fR character string.
63 .RE
65 .sp
66 .ne 2
67 .na
68 \fB\fIutf16len\fR\fR
69 .ad
70 .RS 12n
71 As an input parameter, the number of 16-bit unsigned integers in \fIutf16str\fR
72 as \fBUTF-16\fR characters to be converted or saved.
73 .sp
74 As an output parameter, the number of 16-bit unsigned integers in
75 \fIutf16str\fR consumed or saved during conversion.
76 .RE
78 .sp
79 .ne 2
80 .na
81 \fB\fIutf32str\fR\fR
82 .ad
83 .RS 12n
84 A pointer to a \fBUTF-32\fR character string.
85 .RE
87 .sp
88 .ne 2
89 .na
90 \fB\fIutf32len\fR\fR
91 .ad
92 .RS 12n
93 As an input parameter, the number of 32-bit unsigned integers in \fIutf32str\fR
94 as \fBUTF-32\fR characters to be converted or saved.
95 .sp
96 As an output parameter, the number of 32-bit unsigned integers in
97 \fIutf32str\fR consumed or saved during conversion.
98 .RE
100 .sp
101 .ne 2
102 .na
103 \fB\fIutf8str\fR\fR
104 .ad
105 .RS 12n
106 A pointer to a \fBUTF-8\fR character string.
107 .RE
109 .sp
110 .ne 2
111 .na
112 \fB\fIutf8len\fR\fR
113 .ad
114 .RS 12n
115 As an input parameter, the number of bytes in \fIutf8str\fR as \fBUTF-8\fR
116 characters to be converted or saved.
117 .sp
118 As an output parameter, the number of bytes in \fIutf8str\fR consumed or saved
119 during conversion.
120 .RE
122 .sp
123 .ne 2
124 .na
125 \fB\fIflag\fR\fR
126 .ad
127 .RS 12n
128 The possible conversion options that are constructed by a bitwise-inclusive-OR
129 of the following values:
130 .sp
131 .ne 2
132 .na
133 \fB\fBUCONV_IN_BIG_ENDIAN\fR\fR
134 .ad
135 .sp .6
136 .RS 4n
137 The input parameter is in big endian byte ordering.
138 .RE
140 .sp
141 .ne 2
142 .na
143 \fB\fBUCONV_OUT_BIG_ENDIAN\fR\fR
144 .ad
145 .sp .6
146 .RS 4n
147 The output parameter should be in big endian byte ordering.
148 .RE
150 .sp
151 .ne 2
152 .na
153 \fB\fBUCONV_IN_SYSTEM_ENDIAN\fR\fR
154 .ad
155 .sp .6
156 .RS 4n
157 The input parameter is in the default byte ordering of the current system.
158 .RE
160 .sp
161 .ne 2
162 .na
163 \fB\fBUCONV_OUT_SYSTEM_ENDIAN\fR\fR
164 .ad
165 .sp .6
166 .RS 4n
167 The output parameter should be in the default byte ordering of the current
168 system.
169 .RE
171 .sp
172 .ne 2
173 .na
174 \fB\fBUCONV_IN_LITTLE_ENDIAN\fR\fR
175 .ad
176 .sp .6
177 .RS 4n
178 The input parameter is in little endian byte ordering.
179 .RE
181 .sp
182 .ne 2
183 .na
184 \fB\fBUCONV_OUT_LITTLE_ENDIAN\fR\fR
185 .ad
186 .sp .6
187 .RS 4n
188 The output parameter should be in little endian byte ordering.
189 .RE
191 .sp
192 .ne 2
193 .na
194 \fB\fBUCONV_IGNORE_NULL\fR\fR
195 .ad
196 .sp .6
197 .RS 4n
198 The null or \fBU+0000\fR character should not stop the conversion.
199 .RE
201 .sp
202 .ne 2
203 .na
204 \fB\fBUCONV_IN_ACCEPT_BOM\fR\fR
205 .ad
206 .sp .6
207 .RS 4n
208 If the Byte Order Mark (\fBBOM\fR, \fBU+FEFF\fR) character exists as the first
209 character of the input parameter, interpret it as the \fBBOM\fR character.
210 .RE
212 .sp
213 .ne 2
214 .na
215 \fB\fBUCONV_OUT_EMIT_BOM\fR\fR
216 .ad
217 .sp .6
218 .RS 4n
219 Start the output parameter with Byte Order Mark (\fBBOM\fR, \fBU+FEFF\fR)
220 character to indicate the byte ordering if the output parameter is in
221 \fBUTF-16\fR or \fBUTF-32\fR.
222 .RE
224 .RE
226 .SH DESCRIPTION
227 .sp
228 .LP
229 The \fBuconv_u16tou32()\fR function reads the given \fIutf16str\fR in
230 \fBUTF-16\fR until \fBU+0000\fR (zero) in \fIutf16str\fR is encountered as a
231 character or until the number of 16-bit unsigned integers specified in
232 \fIutf16len\fR is read. The \fBUTF-16\fR characters that are read are converted
233 into \fBUTF-32\fR and the result is saved at \fIutf32str\fR. After the
234 successful conversion, \fIutf32len\fR contains the number of 32-bit unsigned
235 integers saved at \fIutf32str\fR as \fBUTF-32\fR characters.
236 .sp
237 .LP
238 The \fBuconv_u16tou8()\fR function reads the given \fIutf16str\fR in
239 \fBUTF-16\fR until \fBU+0000\fR (zero) in \fIutf16str\fR is encountered as a
240 character or until the number of 16-bit unsigned integers specified in
241 \fIutf16len\fR is read. The \fBUTF-16\fR characters that are read are converted
242 into \fBUTF-8\fR and the result is saved at \fIutf8str\fR. After the successful
243 conversion, \fIutf8len\fR contains the number of bytes saved at \fIutf8str\fR
244 as \fBUTF-8\fR characters.
245 .sp
246 .LP
247 The \fBuconv_u32tou16()\fR function reads the given \fIutf32str\fR in
248 \fBUTF-32\fR until \fBU+0000\fR (zero) in \fIutf32str\fR is encountered as a
249 character or until the number of 32-bit unsigned integers specified in
250 \fIutf32len\fR is read. The \fBUTF-32\fR characters that are read are converted
251 into \fBUTF-16\fR and the result is saved at \fIutf16str\fR. After the
252 successful conversion, \fIutf16len\fR contains the number of 16-bit unsigned
253 integers saved at \fIutf16str\fR as \fBUTF-16\fR characters.
254 .sp
255 .LP
256 The \fBuconv_u32tou8()\fR function reads the given \fIutf32str\fR in
257 \fBUTF-32\fR until \fBU+0000\fR (zero) in \fIutf32str\fR is encountered as a
258 character or until the number of 32-bit unsigned integers specified in
259 \fIutf32len\fR is read. The \fBUTF-32\fR characters that are read are converted
260 into \fBUTF-8\fR and the result is saved at \fIutf8str\fR. After the successful
261 conversion, \fIutf8len\fR contains the number of bytes saved at \fIutf8str\fR
262 as \fBUTF-8\fR characters.
263 .sp
264 .LP
265 The \fBuconv_u8tou16()\fR function reads the given \fIutf8str\fR in \fBUTF-8\fR
266 until the null ('\fB\e0\fR\&') byte in \fIutf8str\fR is encountered or until
267 the number of bytes specified in \fIutf8len\fR is read. The \fBUTF-8\fR
268 characters that are read are converted into \fBUTF-16\fR and the result is
269 saved at \fIutf16str\fR. After the successful conversion, \fIutf16len\fR
270 contains the number of 16-bit unsigned integers saved at \fIutf16str\fR as
271 \fBUTF-16\fR characters.
272 .sp
273 .LP
274 The \fBuconv_u8tou32()\fR function reads the given \fIutf8str\fR in \fBUTF-8\fR
275 until the null ('\fB\e0\fR\&') byte in \fIutf8str\fR is encountered or until
276 the number of bytes specified in \fIutf8len\fR is read. The \fBUTF-8\fR
277 characters that are read are converted into \fBUTF-32\fR and the result is
278 saved at \fIutf32str\fR. After the successful conversion, \fIutf32len\fR
279 contains the number of 32-bit unsigned integers saved at \fIutf32str\fR as
280 \fBUTF-32\fR characters.
281 .sp
282 .LP
283 During the conversion, the input and the output parameters are treated with
284 byte orderings specified in the \fIflag\fR parameter. When not specified, the
285 default byte ordering of the system is used. The byte ordering \fIflag\fR value
286 that is specified for \fBUTF-8\fR is ignored.
287 .sp
288 .LP
289 When \fBUCONV_IN_ACCEPT_BOM\fR is specified as the \fIflag\fR and the first
290 character of the string pointed to by the input parameter is the \fBBOM\fR
291 character, the value of the \fBBOM\fR character dictates the byte ordering of
292 the subsequent characters in the string pointed to by the input parameter,
293 regardless of the supplied input parameter byte ordering option \fIflag\fR
294 values. If the \fBUCONV_IN_ACCEPT_BOM\fR is not specified, the \fBBOM\fR as the
295 first character is treated as a regular Unicode character: Zero Width No Break
296 Space (\fBZWNBSP\fR) character.
297 .sp
298 .LP
299 When \fBUCONV_IGNORE_NULL\fR is specified, regardless of whether the input
300 parameter contains \fBU+0000\fR or null byte, the conversion continues until
301 the specified number of input parameter elements at \fIutf16len\fR,
302 \fIutf32len\fR, or \fIutf8len\fR are entirely consumed during the conversion.
303 .sp
304 .LP
305 As output parameters, \fIutf16len\fR, \fIutf32len\fR, and \fIutf8len\fR are not
306 changed if conversion fails for any reason.
307 .SH CONTEXT
308 .sp
309 .LP
310 The \fBuconv_u16tou32()\fR, \fBuconv_u16tou8()\fR, \fBuconv_u32tou16()\fR,
311 \fBuconv_u32tou8()\fR, \fBuconv_u8tou16()\fR, and \fBuconv_u8tou32()\fR
312 functions can be called from user or interrupt context.
313 .SH RETURN VALUES
314 .sp
315 .LP
316 Upon successful conversion, the functions return \fB0\fR. Upon failure, the
317 functions return one of the following \fBerrno\fR values:
318 .sp
319 .ne 2
320 .na
321 \fB\fBEILSEQ\fR\fR
322 .ad
323 .RS 10n
324 The conversion detected an illegal or out of bound character value in the input
325 parameter.
326 .RE
328 .sp
329 .ne 2
330 .na
331 \fB\fBE2BIG\fR\fR
332 .ad
333 .RS 10n
334 The conversion cannot finish because the size specified in the output parameter
335 is too small.
336 .RE
338 .sp
339 .ne 2
340 .na
341 \fB\fBEINVAL\fR\fR
342 .ad
343 .RS 10n
344 The conversion stops due to an incomplete character at the end of the input
345 string.
346 .RE
348 .sp
349 .ne 2
350 .na
351 \fB\fBEBADF\fR\fR
352 .ad
353 .RS 10n
354 Conflicting byte-ordering option \fIflag\fR values are detected.
355 .RE
357 .SH EXAMPLES
358 .LP
359 \fBExample 1 \fRConvert a \fBUTF-16\fR string in little-endian byte ordering
360 into \fBUTF-8\fR string.
361 .sp
362 .in +2
363 .nf
364 #include <sys/types.h>
365 #include <sys/errno.h>
366 #include <sys/sunddi.h>
367 \&.
368 \&.
369 \&.
370 uint16_t u16s[MAXNAMELEN + 1];
371 uchar_t u8s[MAXNAMELEN + 1];
372 size_t u16len, u8len;
373 int ret;
374 \&.
375 \&.
376 \&.
377 u16len = u8len = MAXNAMELEN;
378 ret = uconv_u16tou8(u16s, &u16len, u8s, &u8len,
379 UCONV_IN_LITTLE_ENDIAN);
380 if (ret != 0) {
381 /* Conversion error occurred. */
382 return (ret);
383 }
384 \&.
385 \&.
386 \&.
387 .fi
388 .in -2
390 .LP
391 \fBExample 2 \fRConvert a \fBUTF-32\fR string in big endian byte ordering into
392 little endian \fBUTF-16\fR.
393 .sp
394 .in +2
395 .nf
396 #include <sys/types.h>
397 #include <sys/errno.h>
398 #include <sys/sunddi.h>
399 \&.
400 \&.
401 \&.
402 /*
403 * An UTF-32 character can be mapped to an UTF-16 character with
404 * two 16-bit integer entities as a "surrogate pair."
405 */
406 uint32_t u32s[101];
407 uint16_t u16s[101];
408 int ret;
409 size_t u32len, u16len;
410 \&.
411 \&.
412 \&.
413 u32len = u16len = 100;
414 ret = uconv_u32tou16(u32s, &u32len, u16s, &u16len,
415 UCONV_IN_BIG_ENDIAN | UCONV_OUT_LITTLE_ENDIAN);
416 if (ret == 0) {
417 return (0);
418 } else if (ret == E2BIG) {
419 /* Use bigger output parameter and try just one more time. */
420 uint16_t u16s2[201];
422 u16len = 200;
423 ret = uconv_u32tou16(u32s, &u32len, u16s2, &u16len,
424 UCONV_IN_BIG_ENDIAN | UCONV_OUT_LITTLE_ENDIAN);
425 if (ret == 0)
426 return (0);
427 }
429 /* Otherwise, return -1 to indicate an error condition. */
430 return (-1);
431 .fi
432 .in -2
434 .LP
435 \fBExample 3 \fRConvert a \fBUTF-8\fR string into \fBUTF-16\fR in little-endian
436 byte ordering.
437 .sp
438 .LP
439 Convert a \fBUTF-8\fR string into \fBUTF-16\fR in little-endian byte ordering
440 with a Byte Order Mark (BOM) character at the beginning of the output
441 parameter.
443 .sp
444 .in +2
445 .nf
446 #include <sys/types.h>
447 #include <sys/errno.h>
448 #include <sys/sunddi.h>
449 \&.
450 \&.
451 \&.
452 uchar_t u8s[MAXNAMELEN + 1];
453 uint16_t u16s[MAXNAMELEN + 1];
454 size_t u8len, u16len;
455 int ret;
456 \&.
457 \&.
458 \&.
459 u8len = u16len = MAXNAMELEN;
460 ret = uconv_u8tou16(u8s, &u8len, u16s, &u16len,
461 UCONV_IN_LITTLE_ENDIAN | UCONV_EMIT_BOM);
462 if (ret != 0) {
463 /* Conversion error occurred. */
464 return (ret);
465 }
466 \&.
467 \&.
468 \&.
469 .fi
470 .in -2
472 .SH ATTRIBUTES
473 .sp
474 .LP
475 See \fBattributes\fR(5) for descriptions of the following attributes:
476 .sp
478 .sp
479 .TS
480 box;
481 c | c
482 l | l .
483 ATTRIBUTE TYPE ATTRIBUTE VALUE
484 _
485 Interface Stability Committed
486 .TE
488 .SH SEE ALSO
489 .sp
490 .LP
491 \fBuconv_u16tou32\fR(3C), \fBattributes\fR(5)
492 .sp
493 .LP
494 The Unicode Standard (http://www.unicode.org)
495 .SH NOTES
496 .sp
497 .LP
498 Each \fBUTF-16\fR or \fBUTF-32\fR character maps to an \fBUTF-8\fR character
499 that might need one to maximum of four bytes.
500 .sp
501 .LP
502 One \fBUTF-32\fR or \fBUTF-8\fR character can yield two 16-bit unsigned
503 integers as a \fBUTF-16\fR character, which is a surrogate pair if the Unicode
504 scalar value is bigger than \fBU+FFFF\fR.
505 .sp
506 .LP
507 Ill-formed \fBUTF-16\fR surrogate pairs are seen as illegal characters during
508 the conversion.