Export (0) Print
Expand All
Expand Minimize

mbstowcs

Converts a sequence of multibyte characters to a corresponding sequence of wide characters.

size_t mbstowcs(
   wchar_t *wcstr,
   const char *mbstr,
   size_t count 
);

Parameters

wcstr
The address of a sequence of wide characters.
mbstr
The address of a sequence of null terminated multibyte characters.
count
The maximum number of multibyte characters to convert.

Return Value

If mbstowcs successfully converts the source string, it returns the number of converted multibyte characters. If the wcstr argument is NULL, the function returns the required size of the destination string. If mbstowcs encounters an invalid multibyte character, it returns –1. If the return value is count, the wide-character string is not null-terminated.

Security Note   Ensure that wcstr and mbstr do not overlap, and that count correctly reflects the number of multibyte characters to convert.

Remarks

The mbstowcs function converts up to a maximum number of count multibyte characters pointed to by mbstr to a string of corresponding wide characters that are determined by the current locale. It stores the resulting wide-character string at the address represented by wcstr. The result is similar to a series of calls to mbtowc. If mbstowcs encounters the single-byte null character ('\0') either before or when count occurs, it converts the null character to a wide-character null character (L'\0') and stops. Thus the wide-character string at wcstr is null-terminated only if a null character is encountered during conversion. If the sequences pointed to by wcstr and mbstr overlap, the behavior is undefined.

If the wcstr argument is NULL, mbstowcs returns the required size of the destination string.

Requirements

Routine Required header Compatibility
mbstowcs <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_mbstowcs.c
/* illustrates the behavior of the mbstowcs function
 */

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

int main( void )
{
    int i;
    char    *pmbnull  = NULL;
    char    *pmbhello = (char *)malloc( MB_CUR_MAX );
    wchar_t *pwchello = L"Hi";
    wchar_t *pwc      = (wchar_t *)malloc( sizeof( wchar_t ));

    printf( "Convert to multibyte string:\n" );
    i = wcstombs( pmbhello, pwchello, MB_CUR_MAX );
    printf( "  Characters converted: %u\n", i );
    printf( "  Hex value of first" );
    printf( " multibyte character: %#.4x\n\n", pmbhello[0] );

    printf( "Convert back to wide-character string:\n" );
    i = mbstowcs( pwc, pmbhello, MB_CUR_MAX );
    printf( "  Characters converted: %u\n", i );
    printf( "  Hex value of first" );
    printf( " wide character: %#.4x\n\n", pwc[0] );
}

Output

Convert to multibyte string:
  Characters converted: 1
  Hex value of first multibyte character: 0x0048

Convert back to wide-character string:
  Characters converted: 1
  Hex value of first wide character: 0x0048

See Also

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

Show:
© 2014 Microsoft