ILE C/C++ Run-Time Library Functions


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.

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.

The behavior of mbsrtowcs() is affected by the LC_CTYPE category of the current locale.

Note:
This function is not available when you specify LOCALETYPE(*CLD) on the compilation command.

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 may be set to ECONVERT.

Example that uses mbsrtowcs()


#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.
    *******************************************************/

Also, see the examples for mbrtowc() -- Convert a Multibyte Character to a Wide Character (Restartable).

Related Information


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]