Debian Codegraph @

upstream/debian-unstable/man3/mbsrtowcs.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 mbsrtowcs 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 mbsrtowcs \- convert a multibyte string to a wide-character string (restartable)
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 mbsrtowcs(" "size_t dsize;"
18 .BI " wchar_t " dest "[restrict " dsize ],
19 .BI " const char **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 convert the
27 multibyte string
28 .I *src
29 to a wide-character string starting at
30 .IR dest .
31 At most
32 .I dsize
33 wide characters are written to
34 .IR dest .
35 The shift state
36 .I *ps
37 is updated.
38 The conversion is effectively performed by repeatedly
39 calling
40 .I "mbrtowc(dest, *src, n, ps)"
41 where
42 .I n
43 is some
44 positive number, as long as this call succeeds, and then incrementing
45 .I dest
46 by one and
47 .I *src
48 by the number of bytes consumed.
49 The conversion can stop for three reasons:
50 .IP \[bu] 3
51 An invalid multibyte sequence has been encountered.
52 In this case,
53 .I *src
54 is left pointing to the invalid multibyte sequence,
55 .I (size_t)\ \-1
56 is returned,
57 and
58 .I errno
59 is set to
60 .BR EILSEQ .
61 .IP \[bu]
62 .I dsize
63 non-L\[aq]\[rs]0\[aq] wide characters have been stored at
64 .IR dest .
65 In this case,
66 .I *src
67 is left pointing to the next
68 multibyte sequence to be converted,
69 and the number of wide characters written to
70 .I dest
71 is returned.
72 .IP \[bu]
73 The multibyte string has been completely converted, including the
74 terminating null wide character (\[aq]\[rs]0\[aq]), which has the side
75 effect of bringing back
76 .I *ps
77 to the
78 initial state.
79 In this case,
80 .I *src
81 is set to NULL, and the number of wide
82 characters written to
83 .IR dest ,
84 excluding the terminating null wide character, 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,
92 except that the converted wide characters are not written out to memory,
93 and that no length 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 mbsrtowcs ()
101 function is used instead.
102 .P
103 In order to avoid the case 2 above, the programmer should make sure
104 .I dsize
105 is
106 greater than or equal to
107 .IR "mbsrtowcs(NULL,src,0,ps)+1" .
108 .P
109 The programmer must ensure that there is room for at least
110 .I dsize
111 wide
112 characters at
113 .IR dest .
114 .P
115 This function is a restartable version of
116 .BR mbstowcs (3).
117 .SH RETURN VALUE
118 The number of wide characters that make
119 up the converted part of the wide-character string, not including the
120 terminating null wide character.
121 If an invalid multibyte sequence was
122 encountered,
123 .I (size_t)\ \-1
124 is returned, and
125 .I errno
126 set to
127 .BR EILSEQ .
128 .SH ATTRIBUTES
129 For an explanation of the terms used in this section, see
130 .BR attributes (7).
131 .TS
132 allbox;
133 lb lb lbx
134 l l l.
135 Interface Attribute Value
136 T{
137 .na
138 .nh
139 .BR mbsrtowcs ()
140 T} Thread safety T{
141 .na
142 .nh
143 MT-Unsafe race:mbsrtowcs/!ps
144 T}
145 .TE
146 .SH STANDARDS
147 C11, POSIX.1-2008.
148 .SH HISTORY
149 POSIX.1-2001, C99.
150 .SH NOTES
151 The behavior of
152 .BR mbsrtowcs ()
153 depends on the
154 .B LC_CTYPE
155 category of the
156 current locale.
157 .P
158 Passing NULL as
159 .I ps
160 is not multithread safe.
161 .SH SEE ALSO
162 .BR iconv (3),
163 .BR mbrtowc (3),
164 .BR mbsinit (3),
165 .BR mbsnrtowcs (3),
166 .BR mbstowcs (3)