| Standards / Extensions | C or C++ | Dependencies |
|---|---|---|
ISO C Amendment |
both |
#include <wchar.h>
size_t wcsrtombs(char * __restrict__dst,
const wchar_t ** __restrict__src, size_t len,
mbstate_t * __restrict__ps);#define _XOPEN_SOURCE
#define _MSE_PROTOS
#include <wchar.h>
size_t wcsrtombs(char *dst,
const wchar_t **src, size_t len, mbstate_t *ps);Converts a sequence of wide characters from the array indirectly pointed to by src into a sequence of corresponding multibyte characters that begin in the shift state described by ps, which, if dst is not a NULL pointer, are then stored into the array pointed to by dst. Conversion continues up to and including the terminating NULL wide character; the terminating NULL wide character (byte) shall be stored.
Each conversion takes places as if by a call to the wcrtomb() function.
If dst is not NULL a pointer, the object pointed to by src shall be assigned either a NULL pointer (if conversion stopped due to reaching a terminating NULL wide character) or the address of the code just past the last wide character converted. If conversion stopped due to reaching a terminating NULL wide character, the resulting state described shall be the initial conversion state.
wcsrtombs() is a “restartable” version of wcstombs(). That is, shift state information is passed as on of the arguments, and gets updated on exit. With wcsrtombs(), you may 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 wcsrtombs() 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, wcsrtombs() returns the number of bytes in the resulting multibyte character sequence, which is the same as the number of array elements modified when dst is not a NULL pointer.
If the string contains an invalid wide character, an encoding error occurs. wcsrtombs() returns (size_t)-1 and stores the value of the macro EILSEQ in errno, but the conversion state shall be unchanged.
⁄* CELEBW18 *⁄
#include <stdio.h>
#include <string.h>
#include <wchar.h>
#define SIZE 20
int main(void)
{
char dest[SIZE];
wchar_t *wcs = L"string";
const wchar_t *ptr;
size_t count = SIZE;
size_t length;
ptr = (wchar_t *) wcs;
length = wcsrtombs(dest, &ptr, count, NULL);
printf("%d characters were converted.\n", length);
printf("The converted string is \"%s\"\n\n", dest);
⁄* Reset the destination buffer *⁄
memset(dest, '\0', sizeof(dest));
⁄* Now convert only 3 characters *⁄
ptr = (wchar_t *) wcs;
length = wcsrtombs(dest, &ptr, 3, NULL);
printf("%d characters were converted.\n", length);
printf("The converted string is \"%s\"\n\n", dest);
} 6 characters were converted.
The converted string is "string"
3 characters were converted.
The converted string is "str"