Debian Codegraph @

upstream/debian-unstable/man3/mbsnrtowcs.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 mbsnrtowcs 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 mbsnrtowcs \- convert a multibyte string to a wide-character 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 mbsnrtowcs(" "size_t size;"
18 .BI " wchar_t " dest "[restrict " size "], const char **restrict " src ,
19 .BI " size_t " nms ", size_t " size \
20 ", mbstate_t *restrict " ps );
21 .fi
22 .P
23 .RS -4
24 Feature Test Macro Requirements for glibc (see
25 .BR feature_test_macros (7)):
26 .RE
27 .P
28 .BR mbsnrtowcs ():
29 .nf
30 Since glibc 2.10:
31 _POSIX_C_SOURCE >= 200809L
32 Before glibc 2.10:
33 _GNU_SOURCE
34 .fi
35 .SH DESCRIPTION
36 The
37 .BR mbsnrtowcs ()
38 function is like the
39 .BR mbsrtowcs (3)
40 function, except that
41 the number of bytes to be converted, starting at
42 .IR *src ,
43 is limited to at most
44 .I nms
45 bytes.
46 .P
47 If
48 .I dest
49 is not NULL, the
50 .BR mbsnrtowcs ()
51 function converts at
52 most
53 .I nms
54 bytes from the
55 multibyte string
56 .I *src
57 to a wide-character string starting at
58 .IR dest .
59 At most
60 .I size
61 wide characters are written to
62 .IR dest .
63 The shift state
64 .I *ps
65 is updated.
66 The conversion is effectively performed by repeatedly
67 calling
68 .I "mbrtowc(dest, *src, n, ps)"
69 where
70 .I n
71 is some
72 positive number, as long as this call succeeds, and then incrementing
73 .I dest
74 by one and
75 .I *src
76 by the number of bytes consumed.
77 The
78 conversion can stop for three reasons:
79 .IP \[bu] 3
80 An invalid multibyte sequence has been encountered.
81 In this case,
82 .I *src
83 is left pointing to the invalid multibyte sequence,
84 .I (size_t)\ \-1
85 is returned,
86 and
87 .I errno
88 is set to
89 .BR EILSEQ .
90 .IP \[bu]
91 The
92 .I nms
93 limit forces a stop,
94 or
95 .I size
96 non-L\[aq]\[rs]0\[aq] wide characters
97 have been stored at
98 .IR dest .
99 In this case,
100 .I *src
101 is left pointing to the
102 next multibyte sequence to be converted, and the number of wide characters
103 written to
104 .I dest
105 is returned.
106 .IP \[bu]
107 The multibyte string has been completely converted, including the
108 terminating null wide character (\[aq]\[rs]0\[aq])
109 (which has the side effect of bringing back
110 .I *ps
111 to the
112 initial state).
113 In this case,
114 .I *src
115 is set to NULL, and the number of wide
116 characters written to
117 .IR dest ,
118 excluding the terminating null wide character,
119 is returned.
120 .P
121 According to POSIX.1,
122 if the input buffer ends with an incomplete character,
123 it is unspecified whether conversion stops at the end of
124 the previous character (if any), or at the end of the input buffer.
125 The glibc implementation adopts the former behavior.
126 .P
127 If
128 .I dest
129 is NULL,
130 .I size
131 is ignored, and the conversion proceeds as
132 above, except that the converted wide characters
133 are not written out to memory,
134 and that no destination size limit exists.
135 .P
136 In both of the above cases, if
137 .I ps
138 is NULL, a static anonymous
139 state known only to the
140 .BR mbsnrtowcs ()
141 function is used instead.
142 .P
143 The programmer must ensure that there is room for at least
144 .I size
145 wide
146 characters at
147 .IR dest .
148 .SH RETURN VALUE
149 The
150 .BR mbsnrtowcs ()
151 function returns the number of wide characters
152 that make up the converted part of the wide-character string,
153 not including the terminating null wide character.
154 If an invalid multibyte sequence was
155 encountered,
156 .I (size_t)\ \-1
157 is returned, and
158 .I errno
159 set to
160 .BR EILSEQ .
161 .SH ATTRIBUTES
162 For an explanation of the terms used in this section, see
163 .BR attributes (7).
164 .TS
165 allbox;
166 lb lb lbx
167 l l l.
168 Interface Attribute Value
169 T{
170 .na
171 .nh
172 .BR mbsnrtowcs ()
173 T} Thread safety T{
174 .na
175 .nh
176 MT-Unsafe race:mbsnrtowcs/!ps
177 T}
178 .TE
179 .SH STANDARDS
180 POSIX.1-2008.
181 .SH NOTES
182 The behavior of
183 .BR mbsnrtowcs ()
184 depends on the
185 .B LC_CTYPE
186 category of the
187 current locale.
188 .P
189 Passing NULL as
190 .I ps
191 is not multithread safe.
192 .SH SEE ALSO
193 .BR iconv (3),
194 .BR mbrtowc (3),
195 .BR mbsinit (3),
196 .BR mbsrtowcs (3)