mbsrtowcs() — Convert a Multibyte String to a Wide Character String (Restartable)
Format
#include <wchar.h>
size_t mbsrtowcs (wchar_t *dst, const char **src, size_t len,
mbstate_t *ps);
Language Level
ANSI
Threadsafe
Yes, if ps
is
not NULL.
Locale Sensitive
The behavior of this function might be affected by the LC_CTYPE category of the current locale. This function might also be affected by the LC_UNI_CTYPE category of the current locale if LOCALETYPE(*LOCALEUCS2) or LOCALETYPE(*LOCALEUTF) is specified on the compilation command. This function is not available when LOCALETYPE(*CLD) is specified on the compilation command. For more information, see Understanding CCSIDs and Locales.
Wide Character Function
See Wide Characters for more information.
Description
This function is the restartable
version of mbstowcs()
.
The mbsrtowcs()
function
converts a sequence of multibyte characters that begins in the conversion
state described by ps from the array indirectly pointed to
by src into a sequence of corresponding wide characters. It
then stores the converted characters into the array pointed to by dst.
Conversion continues up to and including an ending null
character, which is also stored. Conversion will stop earlier in
two cases: when a sequence of bytes are reached that do not form a
valid multibyte character, or (if dst is not a null pointer)
when len wide characters have been stored into the array pointed
to by dst. Each conversion takes place as if by a call to mbrtowc()
function.
If dst is not a null pointer, the pointer object pointed to by src will be assigned either a null pointer (if conversion stopped due to reaching an ending null character) or the address just past the last multibyte character converted. If conversion stopped due to reaching an ending null character, the initial conversion state is described.
Return Value
If the input string does not
begin with a valid multibyte character, an encoding error occurs,
the mbsrtowcs()
function
stores the value of the macro EILSEQ in errno, and returns (size_t)
-1, but the conversion state will be unchanged. Otherwise, it returns
the number of multibyte characters successfully converted, which is
the same as the number of array elements modified when dst is
not a null pointer.
If a conversion error occurs, errno
might
be set to ECONVERT.
Example
#include <stdio.h>
#include <stdlib.h>
#include <wchar.h>
#include <locale.h>
#define SIZE 10
int main(void)
{
char mbs1[] = "abc";
char mbs2[] = "\x81\x41" "m" "\x81\x42";
const char *pmbs1 = mbs1;
const char *pmbs2 = mbs2;
mbstate_t ss1 = 0;
mbstate_t ss2 = 0;
wchar_t wcs1[SIZE], wcs2[SIZE];
if (NULL == setlocale(LC_ALL, "/qsys.lib/locale.lib/ja_jp939.locale"))
{
printf("setlocale failed.\n");
exit(EXIT_FAILURE);
}
mbsrtowcs(wcs1, &pmbs1, SIZE, &ss1);
mbsrtowcs(wcs2, &pmbs2, SIZE, &ss2);
printf("The first wide character string is %ls.\n", wcs1);
printf("The second wide character string is %ls.\n", wcs2);
return 0;
}
/*******************************************************
The output should be similar to:
The first wide character string is abc.
The second wide character string is Am B.
*******************************************************/
Related Information
- mblen() — Determine Length of a Multibyte Character
- mbrlen() — Determine Length of a Multibyte Character (Restartable)
- mbrtowc() — Convert a Multibyte Character to a Wide Character (Restartable)
- mbstowcs() — Convert a Multibyte String to a Wide Character String
- setlocale() — Set Locale
- wcrtomb() — Convert a Wide Character to a Multibyte Character (Restartable)
- wcsrtombs() — Convert Wide Character String to Multibyte String (Restartable)
- <locale.h>
- <wchar.h>