]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) Bruno Haible <haible@clisp.cons.org> |
2 | .\" | |
89e3ffe9 | 3 | .\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) |
fea681da MK |
4 | .\" This is free documentation; you can redistribute it and/or |
5 | .\" modify it under the terms of the GNU General Public License as | |
6 | .\" published by the Free Software Foundation; either version 2 of | |
7 | .\" the License, or (at your option) any later version. | |
fe382ebf | 8 | .\" %%%LICENSE_END |
fea681da MK |
9 | .\" |
10 | .\" References consulted: | |
11 | .\" GNU glibc-2 source code and manual | |
12 | .\" Dinkumware C library reference http://www.dinkumware.com/ | |
008f1ecc | 13 | .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html |
fea681da MK |
14 | .\" ISO/IEC 9899:1999 |
15 | .\" | |
460495ca | 16 | .TH WCTOMB 3 2015-08-08 "GNU" "Linux Programmer's Manual" |
fea681da MK |
17 | .SH NAME |
18 | wctomb \- convert a wide character to a multibyte sequence | |
19 | .SH SYNOPSIS | |
20 | .nf | |
21 | .B #include <stdlib.h> | |
68e4db0a | 22 | .PP |
fea681da MK |
23 | .BI "int wctomb(char *" s ", wchar_t " wc ); |
24 | .fi | |
25 | .SH DESCRIPTION | |
35cfd378 MK |
26 | If |
27 | .I s | |
28 | is not NULL, | |
60a90ecd MK |
29 | the |
30 | .BR wctomb () | |
31 | function converts the wide character | |
35cfd378 MK |
32 | .I wc |
33 | to its multibyte representation and stores it at the beginning of | |
34 | the character array pointed to by | |
35 | .IR s . | |
c13182ef MK |
36 | It updates the shift state, which |
37 | is stored in a static anonymous variable | |
33a0ccb2 | 38 | known only to the |
8c917f5c MK |
39 | .BR wctomb () |
40 | function, | |
c13182ef | 41 | and returns the length of said multibyte representation, |
75b94dc3 | 42 | that is, the number of |
35cfd378 MK |
43 | bytes written at |
44 | .IR s . | |
fea681da | 45 | .PP |
c13182ef | 46 | The programmer must ensure that there is |
35cfd378 MK |
47 | room for at least |
48 | .B MB_CUR_MAX | |
49 | bytes at | |
50 | .IR s . | |
fea681da | 51 | .PP |
35cfd378 MK |
52 | If |
53 | .I s | |
54 | is NULL, the | |
60a90ecd MK |
55 | .BR wctomb () |
56 | function | |
008f1ecc | 57 | .\" The Dinkumware doc and the Single UNIX specification say this, but |
fea681da | 58 | .\" glibc doesn't implement this. |
33a0ccb2 | 59 | resets the shift state, known only to this function, |
c13182ef | 60 | to the initial state, and |
c7094399 | 61 | returns nonzero if the encoding has nontrivial shift state, |
c13182ef | 62 | or zero if the encoding is stateless. |
47297adb | 63 | .SH RETURN VALUE |
35cfd378 MK |
64 | If |
65 | .I s | |
66 | is not NULL, the | |
60a90ecd MK |
67 | .BR wctomb () |
68 | function | |
c13182ef | 69 | returns the number of bytes |
35cfd378 MK |
70 | that have been written to the byte array at |
71 | .IR s . | |
72 | If | |
73 | .I wc | |
74 | can not be | |
c13182ef MK |
75 | represented as a multibyte sequence (according |
76 | to the current locale), \-1 is returned. | |
fea681da | 77 | .PP |
35cfd378 MK |
78 | If |
79 | .I s | |
80 | is NULL, the | |
60a90ecd | 81 | .BR wctomb () |
c7094399 | 82 | function returns nonzero if the |
c382a365 | 83 | encoding has nontrivial shift state, or zero if the encoding is stateless. |
69e8f02f | 84 | .SH ATTRIBUTES |
bcd70a87 PH |
85 | For an explanation of the terms used in this section, see |
86 | .BR attributes (7). | |
87 | .TS | |
88 | allbox; | |
89 | lb lb lb | |
90 | l l l. | |
91 | Interface Attribute Value | |
92 | T{ | |
69e8f02f | 93 | .BR wctomb () |
8ff1e928 | 94 | T} Thread safety MT-Unsafe race |
bcd70a87 | 95 | .TE |
47297adb | 96 | .SH CONFORMING TO |
f6221652 | 97 | POSIX.1-2001, POSIX.1-2008, C99. |
fea681da | 98 | .SH NOTES |
d9bfdb9c | 99 | The behavior of |
60a90ecd | 100 | .BR wctomb () |
1274071a MK |
101 | depends on the |
102 | .B LC_CTYPE | |
103 | category of the | |
fea681da MK |
104 | current locale. |
105 | .PP | |
60a90ecd MK |
106 | The function |
107 | .BR wcrtomb (3) | |
108 | provides | |
fea681da | 109 | a better interface to the same functionality. |
47297adb | 110 | .SH SEE ALSO |
e37e3282 | 111 | .BR MB_CUR_MAX (3), |
4670051b MK |
112 | .BR mblen (3), |
113 | .BR mbstowcs (3), | |
114 | .BR mbtowc (3), | |
e37e3282 MK |
115 | .BR wcrtomb (3), |
116 | .BR wcstombs (3) |