Export (0) Print
Expand All
div
eof
Expand Minimize
This topic has not yet been rated - Rate this topic

wcrtomb 

Convert a wide character into its multibyte character representation. This function is deprecated because a more secure version is available; see wcrtomb_s.


size_t wcrtomb(
   char *mbchar,
   wchar_t wchar,
   mbstate_t *mbstate
);
template <size_t size>
size_t wcrtomb(
   char (&mbchar)[size],
   wchar_t wchar,
   mbstate_t *mbstate
); // C++ only

Parameters

[out] mbchar

The resulting multibyte converted character.

[in] wchar

A wide character to convert.

[in] mbstate

A pointer to an mbstate_t object.

Returns the number of bytes required to represent the converted multibyte character, otherwise a -1 if an error occurs.

The wcrtomb function converts a wide character, beginning in the specified conversion state contained in mbstate, from the value contained in wchar, into the address represented by mbchar. The return value is the number of bytes required to represent the corresponding multibyte character, but it will not return more than MB_CUR_MAX bytes.

If mbstate is null, the internal mbstate_t object containing the conversion state of mbchar is used. If the character sequence wchar does not have a corresponding multibyte character representation, a -1 is returned and the errno is set to EILSEQ.

The wcrtomb function differs from wctomb, _wctomb_l by its restartability. The conversion state is stored in mbstate for subsequent calls to the same or other restartable functions. Results are undefined when mixing the use of restartable and nonrestartable functions. For example, an application would use wcsrlen rather than wcslen, if a subsequent call to wcsrtombs were used instead of wcstombs.

In C++, this function has a template overload that invokes the newer, secure counterparts of this function. For more information, see Secure Template Overloads.

The wcrtomb function is multithread safe as long as no function in the current thread calls setlocale while this function is executing and while the mbstate is null.

// crt_wcrtomb.c
// compile with: /W3
// This program converts a wide character
// to its corresponding multibyte character.

#include <string.h>
#include <stdio.h>
#include <wchar.h>

int main( void )
{
    size_t      sizeOfCovertion = 0;
    mbstate_t   mbstate;
    char        mbStr = 0;
    wchar_t*    wcStr = L"Q";

    // Reset to initial conversion state
    memset(&mbstate, 0, sizeof(mbstate));

    sizeOfCovertion = wcrtomb(&mbStr, *wcStr, &mbstate); // C4996
    // Note: wcrtomb is deprecated; consider using wcrtomb_s instead
    if (sizeOfCovertion > 0)
    {
        printf("The corresponding wide character \"");
        wprintf(L"%s\"", wcStr);
        printf(" was converted to the \"%c\" ", mbStr);
        printf("multibyte character.\n");
    }
    else
    {
        printf("No corresponding multibyte character "
               "was found.\n");
    }
}

Output

The corresponding wide character "Q" was converted to the "Q" multibyte character.

Not applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.

Routine Required header Compatibility

wcrtomb

<wchar.h>

ANSI, Windows 95, Windows 98, Windows 98 Second Edition, Windows Millennium Edition, Windows NT 4.0, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.