mbtowc() — Convert Multibyte Character to a Wide Character

Format

#include <stdlib.h>
int mbtowc(wchar_t *pwc, const char *string, size_t n);

Language Level

ANSI

Threadsafe

No

Use mbrtowc() instead.

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. For more information, see Understanding CCSIDs and Locales.

Wide Character Function

See Wide Characters for more information.

Description

The mbtowc() function first determines the length of the multibyte character pointed to by string. It then converts the multibyte character to a wide character as described in mbstowcs. A maximum of n bytes are examined.

Return Value

If string is NULL, the mbtowc() function returns:
  • Nonzero when the active locale is mixed byte. The function initializes the state variable.
  • 0 otherwise.
If string is not NULL, the mbtowc() function returns:
  • 0 if string points to the null character
  • The number of bytes comprising the converted multibyte character
  • -1 if string does not point to a valid multibyte character.

If a conversion error occurs, errno might be set to ECONVERT.

Example

This example uses the mblen() and mbtowc() functions to convert a multibyte character into a single wide character. 
#include <stdio.h>
#include <stdlib.h>
 
#define LOCNAME "/qsys.lib/mylib.lib/ja_jp959.locale"
/*Locale created from source JA_JP and CCSID 939 */
 
int length, temp;
char string [] = "\x0e\x41\x71\x0f";
wchar_t arr[6];
 
int main(void)
{
   /* initialize internal state variable */
   temp = mbtowc(arr, NULL, 0);            
 
   setlocale (LC_ALL, LOCNAME);
   /* Set string to point to a multibyte character. */
   length = mblen(string, MB_CUR_MAX);
   temp = mbtowc(arr,string,length);
   arr[1] = L'\0';
   printf("wide character string: %ls",arr);
}

Related Information