MBSRTOWCS(3) BSD Programmer's Manual MBSRTOWCS(3)
mbsrtowcs, mbsnrtowcs, mbsnrtowcsvis - convert a multibyte character
string to a wide character
#include <wchar.h>
size_t
mbsrtowcs(wchar_t *pwcs, const char **s, size_t n, mbstate_t *ps);
size_t
mbsnrtowcs(wchar_t *pwcs, const char **s, size_t max, size_t n,
mbstate_t *ps);
#include <mbfun.h>
size_t
mbsnrtowcsvis(wchar_t *pwcs, const char **s, size_t max, size_t n,
mbstate_t *ps);
/* deprecated */
mbsrtowcs() converts the multibyte character string indirectly pointed to
by s to the corresponding wide character string, and stores it in the ar-
ray pointed to by pwcs. mbsnrtowcs() behaves the same, but reads at most
max octets from the string indirectly pointed to by s. mbsnrtowcsvis()
behaves the same, but automatically converts input octets from 8-bit to
UCS. The conversion stops due to the following reasons:
• The conversion reaches a null byte. In this case, the null byte is
also converted.
• mbsrtowcs() or mbsnrtowcs() has already stored n wide characters.
• The conversion encounters an invalid character.
• The mbsnrtowcs() function has already devoured max octets.
Each character is converted as if optu8to16(3) is continuously called.
In the case of mbsnrtowcsvis(), each character is converted as if
optu8to16vis(3) is continuously called; if the max argument is initially
set to 0, the remaining state is drained.
After conversion, if pwcs is not a NULL pointer, the pointer object
pointed to by s is a NULL pointer (if the conversion is stopped due to
reaching a null byte) or the first byte of the character just after the
last character converted.
If pwcs is not a null pointer and the conversion is stopped due to reach-
ing a null byte, the mbsrtowcs() and mbsnrtowcs() functions place the
state object pointed to by ps to an initial state after the conversion
has taken place.
The behaviour of the mbsrtowcs() and mbsnrtowcs() functions is affected
by the LC_CTYPE category of the current locale.
These are the special cases:
s == NULL || *s == NULL
Undefined (may cause the program to crash).
pwcs == NULL The conversion has taken place, but the resultant wide
character string was discarded. In this case, the pointer
object pointed to by s is not modified and n is ignored.
ps == NULL mbsrtowcs() uses its own internal state object to keep the
conversion state, instead of ps mentioned in this manual
page. mbsnrtowcs() has an own internal state which is dif-
ferent from the one of mbsrtowcs().
Calling any other functions in libc never change the inter-
nal state of mbsnrtowcs() or mbsrtowcs(), which is initial-
ised at startup time of the program.
mbsrtowcs() and mbsnrtowcs() return:
0 or positive
The value returned is the number of elements stored in the
array pointed to by pwcs, except for a terminating null
wide character (if any). If pwcs is not null and the value
returned is equal to n, the wide character string pointed
to by pwcs is not null terminated. If pwcs is a null
pointer, the value returned is the number of elements to
contain the whole string converted, except for a terminat-
ing null wide character.
(size_t)-1 The array indirectly pointed to by s contains a byte se-
quence forming invalid character. In this case, mbsrtowcs()
and mbsnrtowcs() set errno to indicate the error.
mbsrtowcs() and mbsnrtowcs() may cause an error in the following cases:
[EILSEQ] The pointer pointed to by s points to an invalid or incom-
plete multibyte character.
[EINVAL] ps points to an invalid or uninitialized mbstate_t object.
mbrtowc(3), mbstowcs(3), optu8to16(3), optu8to16vis(3), setlocale(3)
The mbsrtowcs() function conforms to ISO/IEC 9899/AMD1:1995 ("ISO C90,
Amendment 1"). The mbsnrtowcs() function is a GNU extension.
The mbsnrtowcsvis() function assumes codepage 1252 and maps holes into
distinguishable codepoints. This extended function declares a macro with
the same name that can be used to check for its presence.
mbsnrtowcs() first appeared in MirBSD #10. mbsnrtowcsvis() first appeared
in MirBSD #11.
MirBSD #10-current December 7, 2021 1