1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
3 .\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA)
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.
10 .\" References consulted:
11 .\" GNU glibc-2 source code and manual
12 .\" Dinkumware C library reference http://www.dinkumware.com/
13 .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
15 .TH MBSNRTOWCS 3 2021-03-22 "GNU" "Linux Programmer's Manual"
17 mbsnrtowcs \- convert a multibyte string to a wide-character string
22 .BI "size_t mbsnrtowcs(wchar_t *restrict " dest ", const char **restrict " src ,
23 .BI " size_t " nms ", size_t " len \
24 ", mbstate_t *restrict " ps );
28 Feature Test Macro Requirements for glibc (see
29 .BR feature_test_macros (7)):
35 _POSIX_C_SOURCE >= 200809L
45 the number of bytes to be converted, starting at
61 to a wide-character string starting at
65 wide characters are written to
70 The conversion is effectively performed by repeatedly
72 .I "mbrtowc(dest, *src, n, ps)"
76 positive number, as long as this call succeeds, and then incrementing
80 by the number of bytes consumed.
82 conversion can stop for three reasons:
84 An invalid multibyte sequence has been encountered.
87 is left pointing to the invalid multibyte sequence,
100 non-L\(aq\e0\(aq wide characters
105 is left pointing to the
106 next multibyte sequence to be converted, and the number of wide characters
111 The multibyte string has been completely converted, including the
112 terminating null wide character (\(aq\e0\(aq)
113 (which has the side effect of bringing back
119 is set to NULL, and the number of wide
120 characters written to
122 excluding the terminating null wide character,
125 According to POSIX.1,
126 if the input buffer ends with an incomplete character,
127 it is unspecified whether conversion stops at the end of
128 the previous character (if any), or at the end of the input buffer.
129 The glibc implementation adopts the former behavior.
135 is ignored, and the conversion proceeds as
136 above, except that the converted wide characters
137 are not written out to memory,
138 and that no destination length limit exists.
140 In both of the above cases, if
142 is NULL, a static anonymous
143 state known only to the
145 function is used instead.
147 The programmer must ensure that there is room for at least
155 function returns the number of wide characters
156 that make up the converted part of the wide-character string,
157 not including the terminating null wide character.
158 If an invalid multibyte sequence was
166 For an explanation of the terms used in this section, see
174 Interface Attribute Value
178 MT-Unsafe race:mbsnrtowcs/!ps
196 is not multithread safe.