| Standards / Extensions | C or C++ | Dependencies |
|---|---|---|
ISO C Amendment |
both |
#include <wchar.h>
size_t mbsrtowcs(wchar_t *dst, const char **src, size_t len, mbstate_t *ps);#define _XOPEN_SOURCE
#define _MSE_PROTOS
#include <wchar.h>
size_t mbsrtowcs(wchar_t *dst, const char **src, size_t len, mbstate_t *ps);Converts a sequence of multibyte characters that begins in the conversion state described by ps from the array indirectly pointed to by src. It converts this sequence into a sequence of corresponding wide characters, that, if dst is not a NULL pointer, are then stored into the array pointed to by dst. Conversion continues up to and including a terminating NULL character, and the terminating NULL wide character is also stored. Conversion stops earlier in two cases: (1) when a sequence of bytes is reached that does not form a valid multibyte character, or (2) if dst is not a NULL pointer, when len codes have been stored into the array pointed to by dst. Each conversion takes place as if by a call to the mbrtowc() function.
If dst is not a NULL pointer, the pointer object pointed to by src is assigned either a NULL pointer (if conversion stopped because a terminating NULL character was reached) or the address just past the last multibyte character converted. If conversion stopped because a terminating NULL character was reached, the resulting state is the initial state.
mbsrtowcs() is a restartable version of mbstowcs(). That is, shift-state information is passed as on of the arguments and is updated on exit. With mbsrtowcs(), you can switch from one multibyte string to another, provided that you have kept the shift-state information.
The behavior of this wide-character function is affected by the LC_CTYPE category of the current locale. If you change the category, undefined results can occur.
Special behavior for XPG4
If you define any feature test macro specifying XPG4 behavior before the statement in your program source file to include the wchar header, then you must also define the _MSE_PROTOS feature test macro to make the declaration of the mbsrtowcs() function in the wchar header available when you compile your program. Please see Table 1 for a list of XPG4 and other feature test macros.
If successful, mbsrtowcs() returns the number of multibyte characters converted, not including the terminating NULL character, if any.
⁄* CELEBM06 *⁄
#include <stdio.h>
#include <stdlib.h>
#include <wchar.h>
#define SIZE 10
int main(void)
{
wchar_t wcs[SIZE];
char mbs[SIZE]="abcd"; ⁄* string containing the multibyte char *⁄
char *ptr = mbs; ⁄* pointer to the mbs string *⁄
int length;
⁄* Determine the length of the multibyte string pointed to by *⁄
⁄* mbs. Store the multibyte characters in the wchar_t array *⁄
⁄* pointed to by wcs. *⁄
length = mbsrtowcs(wcs, (const char**)&ptr, SIZE, NULL);
wcs[length] = L'\0';
printf(" length: %d \n", length);
printf(" wcs:\"%ls\"\n",wcs);
printf(" mbs:\"%s\"\n",mbs);
printf(" &mbs: %p \n", mbs);
printf(" &ptr: %p \n", ptr);
}