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 WCSRTOMBS 3 2021-03-22 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
13 wcsrtombs \- convert a wide-character string to a multibyte string
16 .RI ( libc ", " \-lc )
21 .BI "size_t wcsrtombs(char *restrict " dest ", const wchar_t **restrict " src ,
22 .BI " size_t " len ", mbstate_t *restrict " ps );
31 the wide-character string
33 to a multibyte string starting at
42 The conversion is effectively performed by repeatedly
44 .IR "wcrtomb(dest, *src, ps)" ,
45 as long as this call succeeds,
49 number of bytes written and
52 The conversion can stop for three reasons:
54 A wide character has been encountered that can not be represented as a
55 multibyte sequence (according to the current locale).
58 is left pointing to the invalid wide character,
66 The length limit forces a stop.
70 to the next wide character to be converted,
71 and the number of bytes written to
75 The wide-character string has been completely converted, including the
76 terminating null wide character (L\(aq\e0\(aq),
77 which has the side effect of bringing back
82 is set to NULL, and the number
85 excluding the terminating null byte (\(aq\e0\(aq),
93 and the conversion proceeds as above, except that the converted bytes
94 are not written out to memory, and that
95 no length limit exists.
97 In both of the above cases,
100 is NULL, a static anonymous
101 state known only to the
103 function is used instead.
105 The programmer must ensure that there is room for at least
114 the number of bytes that make up the
115 converted part of multibyte sequence,
116 not including the terminating null byte.
117 If a wide character was encountered
118 which could not be converted,
125 For an explanation of the terms used in this section, see
133 Interface Attribute Value
137 MT-Unsafe race:wcsrtombs/!ps
144 POSIX.1-2001, POSIX.1-2008, C99.
155 is not multithread safe.