wctomb_s, _wctomb_s_l

Article
06/05/2017

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at wctomb_s, _wctomb_s_l.

Converts a wide character to the corresponding multibyte character. A version of wctomb, _wctomb_l with security enhancements as described in Security Features in the CRT.

Syntax

errno_t wctomb_s(  
   int *pRetValue,  
   char *mbchar,  
   size_t sizeInBytes,  
   wchar_t wchar   
);  
errno_t _wctomb_s_l(  
   int *pRetValue,  
   char *mbchar,  
   size_t sizeInBytes,  
   wchar_t wchar,  
   _locale_t locale  
);

Parameters

[out] pRetValue
The number of bytes, or a code indicating the result.

[out] mbchar
The address of a multibyte character.

[in] sizeInBytes
Size of the buffer mbchar.

[in] wchar
A wide character.

[in] locale
The locale to use.

Return Value

Zero if successful, an error code on failure.

Error Conditions

`mbchar`	`sizeInBytes`	Return value	`pRetValue`
`NULL`	>0	`EINVAL`	not modified
any	>`INT_MAX`	`EINVAL`	not modified
any	too small	`EINVAL`	not modified

If any of the above error conditions occurs, the invalid parameter handler is invoked, as described in Parameter Validation. If execution is allowed to continue, wctomb returns EINVAL and sets errno to EINVAL.

Remarks

The wctomb_s function converts its wchar argument to the corresponding multibyte character and stores the result at mbchar. You can call the function from any point in any program.

If wctomb_s converts the wide character to a multibyte character, it puts the number of bytes (which is never greater than MB_CUR_MAX) in the wide character into the integer pointed to by pRetValue. If wchar is the wide-character null character (L'\0'), wctomb_s fills pRetValue with 1. If the target pointer mbchar is NULL, wctomb_s puts 0 in pRetValue. If the conversion is not possible in the current locale, wctomb_s puts –1 in pRetValue.

wctomb_s uses the current locale for locale-dependent information; _wctomb_s_l is identical except that it uses the locale passed in instead. For more information, see Locale.

Requirements

Routine	Required header
`wctomb_s`	<stdlib.h>
`_wctomb_s_l`	<stdlib.h>

For additional compatibility information, see Compatibility in the Introduction.

Example

This program illustrates the behavior of the wctomb function.

// crt_wctomb_s.cpp  
#include <stdio.h>  
#include <stdlib.h>  
  
int main( void )  
{  
    int i;  
    wchar_t wc = L'a';  
    char *pmb = (char *)malloc( MB_CUR_MAX );  
  
    printf_s( "Convert a wide character:\n" );  
    wctomb_s( &i, pmb, MB_CUR_MAX, wc );  
    printf_s( "   Characters converted: %u\n", i );  
    printf_s( "   Multibyte character: %.1s\n\n", pmb );  
}

Convert a wide character:  
   Characters converted: 1  
   Multibyte character: a

.NET Framework Equivalent

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