1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
3 .\" SPDX-License-Identifier: GPL-2.0-or-later
5 .\" References consulted:
6 .\" GNU glibc-2 source code and manual
7 .\" Dinkumware C library reference http://www.dinkumware.com/
8 .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
11 .TH MBSRTOWCS 3 2021-03-22 "GNU" "Linux Programmer's Manual"
13 mbsrtowcs \- convert a multibyte string to a wide-character string
16 .RI ( libc ", " \-lc )
21 .BI "size_t mbsrtowcs(wchar_t *restrict " dest ", const char **restrict " src ,
22 .BI " size_t " len ", mbstate_t *restrict " ps );
32 to a wide-character string starting at
36 wide characters are written to
41 The conversion is effectively performed by repeatedly
43 .I "mbrtowc(dest, *src, n, ps)"
47 positive number, as long as this call succeeds, and then incrementing
51 by the number of bytes consumed.
52 The conversion can stop for three reasons:
54 An invalid multibyte sequence has been encountered.
57 is left pointing to the invalid multibyte sequence,
66 non-L\(aq\e0\(aq wide characters have been stored at
70 is left pointing to the next
71 multibyte sequence to be converted,
72 and the number of wide characters written to
76 The multibyte string has been completely converted, including the
77 terminating null wide character (\(aq\e0\(aq), which has the side
78 effect of bringing back
84 is set to NULL, and the number of wide
87 excluding the terminating null wide character, is returned.
94 and the conversion proceeds as above,
95 except that the converted wide characters are not written out to memory,
96 and that no length limit exists.
98 In both of the above cases,
101 is NULL, a static anonymous
102 state known only to the
104 function is used instead.
106 The programmer must ensure that there is room for at least
114 function returns the number of wide characters that make
115 up the converted part of the wide-character string, not including the
116 terminating null wide character.
117 If an invalid multibyte sequence was
125 For an explanation of the terms used in this section, see
133 Interface Attribute Value
137 MT-Unsafe race:mbsrtowcs/!ps
144 POSIX.1-2001, POSIX.1-2008, C99.
155 is not multithread safe.