Debian Codegraph @

upstream/debian-unstable/man3/wcrtomb.3

raw
1 '\" t
2 .\" Copyright, Bruno Haible <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: GPL-2.0-or-later
6 .\"
7 .TH wcrtomb 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 wcrtomb \- convert a wide character to a multibyte sequence
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <wchar.h>
16 .P
17 .BI "size_t wcrtomb(char *restrict " s ", wchar_t " wc \
18 ", mbstate_t *restrict " ps );
19 .fi
20 .SH DESCRIPTION
21 The main case for this function is when
22 .I s
23 is
24 not NULL and
25 .I wc
26 is not a null wide character (L\[aq]\[rs]0\[aq]).
27 In this case, the
28 .BR wcrtomb ()
29 function
30 converts the wide character
31 .I wc
32 to its multibyte representation and stores it
33 at the beginning of the character
34 array pointed to by
35 .IR s .
36 It updates the shift state
37 .IR *ps ,
38 and
39 returns the length of said multibyte representation,
40 that is, the number of bytes
41 written at
42 .IR s .
43 .P
44 A different case is when
45 .I s
46 is not NULL,
47 but
48 .I wc
49 is a null wide character (L\[aq]\[rs]0\[aq]).
50 In this case, the
51 .BR wcrtomb ()
52 function stores at
53 the character array pointed to by
54 .I s
55 the shift sequence needed to
56 bring
57 .I *ps
58 back to the initial state,
59 followed by a \[aq]\[rs]0\[aq] byte.
60 It updates the shift state
61 .I *ps
62 (i.e., brings
63 it into the initial state),
64 and returns the length of the shift sequence plus
65 one, that is, the number of bytes written at
66 .IR s .
67 .P
68 A third case is when
69 .I s
70 is NULL.
71 In this case,
72 .I wc
73 is ignored,
74 and the function effectively returns
75 .P
76 .in +4n
77 .EX
78 wcrtomb(buf, L\[aq]\[rs]0\[aq], ps)
79 .EE
80 .in
81 .P
82 where
83 .I buf
84 is an internal anonymous buffer.
85 .P
86 In all of the above cases, if
87 .I ps
88 is NULL, a static anonymous
89 state known only to the
90 .BR wcrtomb ()
91 function is used instead.
92 .P
93 At most
94 .B MB_CUR_MAX
95 bytes will be written at
96 .IR s .
97 The programmer must ensure that there is enough room to store the
98 multibyte sequence at
99 .IR s .
100 .SH RETURN VALUE
101 The
102 .BR wcrtomb ()
103 function returns the number of
104 bytes that have been or would
105 have been written to the byte array at
106 .IR s .
107 If
108 .I wc
109 can not be
110 represented as a multibyte sequence (according to the current locale),
111 .I (size_t)\ \-1
112 is returned, and
113 .I errno
114 set to
115 .BR EILSEQ .
116 .SH ATTRIBUTES
117 For an explanation of the terms used in this section, see
118 .BR attributes (7).
119 .TS
120 allbox;
121 lbx lb lb
122 l l l.
123 Interface Attribute Value
124 T{
125 .na
126 .nh
127 .BR wcrtomb ()
128 T} Thread safety MT-Unsafe race:wcrtomb/!ps
129 .TE
130 .SH STANDARDS
131 C11, POSIX.1-2008.
132 .SH HISTORY
133 POSIX.1-2001, C99.
134 .SH NOTES
135 The behavior of
136 .BR wcrtomb ()
137 depends on the
138 .B LC_CTYPE
139 category of the
140 current locale.
141 .P
142 Passing NULL as
143 .I ps
144 is not multithread safe.
145 .SH SEE ALSO
146 .BR mbsinit (3),
147 .BR wcsrtombs (3)