Debian Codegraph @

upstream/debian-unstable/man3/wcsrtombs.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 wcsrtombs 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 wcsrtombs \- convert a wide-character string to a multibyte string
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <wchar.h>
16 .P
17 .BR "size_t wcsrtombs(" "size_t dsize;"
18 .BI " char " dest "[restrict " dsize ],
19 .BI " const wchar_t **restrict " src ,
20 .BI " size_t " dsize ", mbstate_t *restrict " ps );
21 .fi
22 .SH DESCRIPTION
23 If
24 .I dest
25 is not NULL,
26 the
27 .BR wcsrtombs ()
28 function converts
29 the wide-character string
30 .I *src
31 to a multibyte string starting at
32 .IR dest .
33 At most
34 .I dsize
35 bytes are written to
36 .IR dest .
37 The shift state
38 .I *ps
39 is updated.
40 The conversion is effectively performed by repeatedly
41 calling
42 .IR "wcrtomb(dest, *src, ps)" ,
43 as long as this call succeeds,
44 and then incrementing
45 .I dest
46 by the
47 number of bytes written and
48 .I *src
49 by one.
50 The conversion can stop for three reasons:
51 .IP \[bu] 3
52 A wide character has been encountered that can not be represented as a
53 multibyte sequence (according to the current locale).
54 In this case,
55 .I *src
56 is left pointing to the invalid wide character,
57 .I (size_t)\ \-1
58 is returned,
59 and
60 .I errno
61 is set to
62 .BR EILSEQ .
63 .IP \[bu]
64 The size limit forces a stop.
65 In this case,
66 .I *src
67 is left pointing
68 to the next wide character to be converted,
69 and the number of bytes written to
70 .I dest
71 is returned.
72 .IP \[bu]
73 The wide-character string has been completely converted, including the
74 terminating null wide character (L\[aq]\[rs]0\[aq]),
75 which has the side effect of bringing back
76 .I *ps
77 to the initial state.
78 In this case,
79 .I *src
80 is set to NULL, and the number
81 of bytes written to
82 .IR dest ,
83 excluding the terminating null byte (\[aq]\[rs]0\[aq]),
84 is returned.
85 .P
86 If
87 .I dest
88 is NULL,
89 .I dsize
90 is ignored,
91 and the conversion proceeds as above, except that the converted bytes
92 are not written out to memory, and that
93 no size limit exists.
94 .P
95 In both of the above cases,
96 if
97 .I ps
98 is NULL, a static anonymous
99 state known only to the
100 .BR wcsrtombs ()
101 function is used instead.
102 .P
103 The programmer must ensure that there is room for at least
104 .I dsize
105 bytes
106 at
107 .IR dest .
108 .SH RETURN VALUE
109 The
110 .BR wcsrtombs ()
111 function returns
112 the number of bytes that make up the
113 converted part of multibyte sequence,
114 not including the terminating null byte.
115 If a wide character was encountered
116 which could not be converted,
117 .I (size_t)\ \-1
118 is returned, and
119 .I errno
120 set to
121 .BR EILSEQ .
122 .SH ATTRIBUTES
123 For an explanation of the terms used in this section, see
124 .BR attributes (7).
125 .TS
126 allbox;
127 lb lb lbx
128 l l l.
129 Interface Attribute Value
130 T{
131 .na
132 .nh
133 .BR wcsrtombs ()
134 T} Thread safety T{
135 .na
136 .nh
137 MT-Unsafe race:wcsrtombs/!ps
138 T}
139 .TE
140 .SH STANDARDS
141 C11, POSIX.1-2008.
142 .SH HISTORY
143 POSIX.1-2001, C99.
144 .SH NOTES
145 The behavior of
146 .BR wcsrtombs ()
147 depends on the
148 .B LC_CTYPE
149 category of the
150 current locale.
151 .P
152 Passing NULL as
153 .I ps
154 is not multithread safe.
155 .SH SEE ALSO
156 .BR iconv (3),
157 .BR mbsinit (3),
158 .BR wcrtomb (3),
159 .BR wcsnrtombs (3),
160 .BR wcstombs (3)