Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All
Expand Minimize

mbtowc

Convert a multibyte character to a corresponding wide character.

int mbtowc(
   wchar_t *wchar,
   const char *mbchar,
   size_t count 
);

Parameters

wchar
Address of a wide character (type wchar_t).
mbchar
Address of a sequence of bytes (a multibyte character).
count
Number of bytes to check.

Return Value

If mbchar is not NULL and if the object that mbchar points to forms a valid multibyte character, mbtowc returns the length in bytes of the multibyte character. If mbchar is NULL or the object that it points to is a wide-character null character (L'\0'), the function returns 0. If the object that mbchar points to does not form a valid multibyte character within the first count characters, it returns –1.

Remarks

The mbtowc function converts count or fewer bytes pointed to by mbchar, if mbchar is not NULL, to a corresponding wide character. mbtowc stores the resulting wide character at wchar, if wchar is not NULL. mbtowc does not examine more than MB_CUR_MAX bytes.

Requirements

Routine Required header Compatibility
mbtowc <stdlib.h> ANSI, Win 98, Win Me, Win NT, Win 2000, Win XP

For additional compatibility information, see Compatibility in the Introduction.

Libraries

All versions of the C run-time libraries.

Example

// crt_mbtowc.c
/* Illustrates the behavior of the mbtowc function
 */

#include <stdlib.h>
#include <stdio.h>

int main( void )
{
    int      i;
    char    *pmbc    = (char *)malloc( sizeof( char ) );
    wchar_t  wc      = L'a';
    wchar_t *pwcnull = NULL;
    wchar_t *pwc     = (wchar_t *)malloc( sizeof( wchar_t ) );
    printf( "Convert a wide character to multibyte character:\n" );
    i = wctomb( pmbc, wc );
    printf( "  Characters converted: %u\n", i );
    printf( "  Multibyte character: %x\n\n", *pmbc );

    printf( "Convert multibyte character back to a wide "
            "character:\n" );
    i = mbtowc( pwc, pmbc, MB_CUR_MAX );
    printf( "  Bytes converted: %u\n", i );
    printf( "  Wide character: %x\n\n", *pwc );
    printf( "Attempt to convert when target is NULL\n" );
    printf( "  returns the length of the multibyte character:\n" );
    i = mbtowc( pwcnull, pmbc, MB_CUR_MAX );
    printf( "  Length of multibyte character: %u\n\n", i );

    printf( "Attempt to convert a NULL pointer to a" );
    printf( " wide character:\n" );
    pmbc = NULL;
    i = mbtowc( pwc, pmbc, MB_CUR_MAX );
    printf( "  Bytes converted: %u\n", i );
}

Output

Convert a wide character to multibyte character:
  Characters converted: 1
  Multibyte character: 61

Convert multibyte character back to a wide character:
  Bytes converted: 1
  Wide character: 61

Attempt to convert when target is NULL
  returns the length of the multibyte character:
  Length of multibyte character: 1

Attempt to convert a NULL pointer to a wide character:
  Bytes converted: 0

See Also

Data Conversion Routines | Locale Routines | Interpretation of Multibyte-Character Sequences | mblen | wcstombs | wctomb | MultiByteToWideChar | Run-Time Routines and .NET Framework Equivalents

Show:
© 2015 Microsoft