MBSRTOWCS(3) | Library Functions Manual | MBSRTOWCS(3) |
mbsrtowcs
, mbsrntowcs
—
#include <wchar.h>
size_t
mbsrtowcs
(wchar_t * restrict
pwcs, const char ** restrict s,
size_t n, mbstate_t * restrict
ps);
size_t
mbsnrtowcs
(wchar_t * restrict
pwcs, const char ** restrict s,
size_t nmc, size_t n,
mbstate_t * restrict ps);
mbsrtowcs
() function converts the multibyte
character string indirectly pointed to by s to the
corresponding wide-character string, and stores it in the array pointed to by
pwcs. The conversion stops due to the following reasons:
mbsrtowcs
() has already stored
n wide characters.Each character will be converted as if mbrtowc(3) is continuously called.
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 NUL 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 reaching a NUL byte, the
mbsrtowcs
() places the state object pointed to by
ps to an initial state after the conversion has taken
place.
The behaviour of mbsrtowcs
() is affected
by the LC_CTYPE
category of the current locale.
These are the special cases:
s
== NULL || *s == NULL
pwcs
== NULL
ps
== NULL
mbsrtowcs
() uses its own internal state object
to keep the conversion state, instead of ps
mentioned in this manual page.
Calling any other functions in Standard
C Library (libc, -lc) never changes the internal state of
mbsrtowcs
(), which is initialized at startup
time of the program.
The mbsnrtowcs
() function behaves
identically to mbsrtowcs
(), except that the
conversion stops after reading at most nmc characters
from the buffer pointed to by s.
mbsrtowcs
() and mbsnrtowcs
()
functions return:
0
,
or positiveNULL
and the value returned is equal to
n, the wide-character string pointed to by
pwcs is not NUL-terminated. If
pwcs is a NULL pointer, the value returned is the
number of elements to contain the whole string converted, except for a
terminating NUL wide character.(size_t)-1
mbsrtowcs
() sets errno to
indicate the error.mbsrtowcs
() and mbsnrtowcs
()
functions may fail with the following errors:
mbsrtowcs
() function conforms to
ISO/IEC 9899/AMD1:1995 (“ISO C90, Amendment
1”). The restrict
qualifier was added by
ISO/IEC 9899:1999 (“ISO C99”).
The mbsnrtowcs
() function conforms to
IEEE Std 1003.1-2008 (“POSIX.1”).
September 9, 2024 | NetBSD 10.1 |