Export (0) Print
Expand All
div
eof
Expand Minimize

wcstombs, _wcstombs_l 

Converts a sequence of wide characters to a corresponding sequence of multibyte characters. These functions are deprecated because more secure versions are available; see wcstombs_s, _wcstombs_s_l.


size_t wcstombs(
   char *mbstr,
   const wchar_t *wcstr,
   size_t count 
);
size_t _wcstombs_l(
   char *mbstr,
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
size_t wcstombs(
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count 
); // C++ only
template <size_t size>
size_t _wcstombs_l(
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
); // C++ only

Parameters

mbstr

The address of a sequence of multibyte characters.

wcstr

The address of a sequence of wide characters.

count

The maximum number of bytes that can be stored in the multibyte output string.

locale

The locale to use.

If wcstombs successfully converts the multibyte string, it returns the number of bytes written into the multibyte output string, excluding the terminating NULL (if any). If the mbstr argument is NULL, wcstombs returns the required size in bytes of the destination string. If wcstombs encounters a wide character it cannot convert to a multibyte character, it returns –1 cast to type size_t and sets errno to EILSEQ.

The wcstombs function converts the wide-character string pointed to by wcstr to the corresponding multibyte characters and stores the results in the mbstr array. The count parameter indicates the maximum number of bytes that can be stored in the multibyte output string (that is, the size of mbstr). In general, it is not known how many bytes will be required when converting a wide-character string. Some wide characters will require only one byte in the output string; others require two. If there are two bytes in the multibyte output string for every wide character in the input string (including the wide character NULL), the result is guaranteed to fit.

If wcstombs encounters the wide-character null character (L'\0') either before or when count occurs, it converts it to an 8-bit 0 and stops. Thus, the multibyte character string at mbstr is null-terminated only if wcstombs encounters a wide-character null character during conversion. If the sequences pointed to by wcstr and mbstr overlap, the behavior of wcstombs is undefined.

If the mbstr argument is NULL, wcstombs returns the required size in bytes of the destination string.

wcstombs validates its parameters. If wcstr is NULL, or if count is greater than INT_MAX, this function invokes the invalid parameter handler, as described in Parameter Validation . If execution is allowed to continue, the function sets errno to EINVAL and returns -1.

wcstombs uses the current locale for any locale-dependent behavior; _wcstombs_l is identical except that it uses the locale passed in instead.

In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see Secure Template Overloads.

Routine Required header Compatibility

wcstombs

<stdlib.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

_wcstombs_l

<stdlib.h>

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

For additional compatibility information, see Compatibility in the Introduction.

This program illustrates the behavior of the wcstombs function.

// crt_wcstombs.c
// compile with: /W3
// This example demonstrates the use
// of wcstombs, which converts a string
// of wide characters to a string of 
// multibyte characters.

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

#define BUFFER_SIZE 100

int main( void )
{
    size_t  count;
    char    *pMBBuffer = (char *)malloc( BUFFER_SIZE );
    wchar_t *pWCBuffer = L"Hello, world.";

    printf("Convert wide-character string:\n" );

    count = wcstombs(pMBBuffer, pWCBuffer, BUFFER_SIZE ); // C4996
    // Note: wcstombs is deprecated; consider using wcstombs_s instead
    printf("   Characters converted: %u\n",
            count );
    printf("    Multibyte character: %s\n\n",
           pMBBuffer );

    free(pMBBuffer);
}

Output

Convert wide-character string:
   Characters converted: 13
    Multibyte character: Hello, world.

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

Community Additions

ADD
Show:
© 2014 Microsoft