wcstombs_s， _wcstombs_s_l

项目
02/21/2013

将宽字符序列分成多字节字符一个对应的序列。 wcstombs， _wcstombs_l 的版本与安全增强的 CRT中的安全功能如中所述。

errno_t wcstombs_s(
   size_t *pReturnValue,
   char *mbstr,
   size_t sizeInBytes,
   const wchar_t *wcstr,
   size_t count 
);
errno_t _wcstombs_s_l(
   size_t *pReturnValue,
   char *mbstr,
   size_t sizeInBytes,
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
errno_t wcstombs_s(
   size_t *pReturnValue,
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count 
); // C++ only
template <size_t size>
errno_t _wcstombs_s_l(
   size_t *pReturnValue,
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
); // C++ only

参数

[out] pReturnValue
转换后的字符数。
[out] mbstr
缓冲区的地址发生的转换过多字节字符字符串。
[in]sizeInBytes
范围在 mbstr 缓冲区的字节。
[in] wcstr
指向要转换的宽字符字符串。
[in] count
要存储的宽的最大字符数在 mbstr 缓冲区，不包括终止 null 字符或 _TRUNCATE。
[in] locale
使用的区域设置。

返回值

零，如果成功，则失败的错误代码。

错误状态	返回值和 errno
mbstr 是 NULL 和 sizeInBytes AMP_GT 0	EINVAL
wcstr 为 NULL	EINVAL
(除非 count 是 _TRUNCATE，目标缓冲区因过小而无法包含被转换的字符串;请参见下面的 " 备注 ")	ERANGE

如果这些条件中的任何一个结果，无效参数异常调用参数验证如中所述。如果执行允许继续，该函数返回错误代码并如下表所示设置 errno 。

备注

wcstombs_s 函数 wcstr 点转换为宽字符字符串转换为缓冲区存储的多字节字符指向由 mbstr。转换为每个字符将继续，直到上述任一条件匹配:

空白宽字符遇到
未能转换的宽字符遇到
在 mbstr 缓冲区存储字节数等于 count。

目标字符串始终以 null 终止 (即使在错误)。

如果 count 为特殊值 _TRUNCATE，则 wcstombs_s 转换相同多个字符串与将放入目标缓冲区，那么，当仍 null 结束符时空间。

如果 wcstombs_s 成功转换源字符串，它在转换的字符串的字节放入范围，包括 null 结束符，以 *pReturnValue (提供的 pReturnValue 不是 NULL)。发生这种情况，即使 mbstr 参数是 NULL 并提供用于确定所需的缓冲区大小。请注意，如果 mbstr 是 NULL， count 被忽略。

如果它不能转换为多字节字符的 wcstombs_s 遇到宽字符，它在 *pReturnValue放置 0，设置目标缓冲区设置为空字符串，设置 errno 到 EILSEQ，并返回 EILSEQ。

如果顺序指向由 wcstr 和 mbstr 重叠， wcstombs_s 行为不确定。

安全说明
确保 wcstr 和 mbstr 重叠，并且， count 准确反映宽字符数转换。

wcstombs_s 为所有与区域设置相关的行为使用当前区域设置; _wcstombs_s_l 与 wcstombs 与相同，但它使用的区域设置。有关更多信息，请参见区域设置。

在 C++ 中，使用这些功能由模板重载简化;重载可推断缓冲区长度 (自动不再需要指定范围参数)，并且还可以用以较新，安全重复自动替换旧，不安全的功能。有关更多信息，请参见安全模板重载。

要求

实例	必需的头
wcstombs_s	stdlib.h

有关其他的兼容性信息，请参见中介绍的兼容性。

示例

此过程说明 wcstombs_s 功能的行为。

// crt_wcstombs_s.c
// This example converts a wide character
// string to a multibyte character string.
#include <stdio.h>
#include <stdlib.h>
#include <assert.h>

#define BUFFER_SIZE 100

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

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

    // Conversion
    wcstombs_s(&i, pMBBuffer, (size_t)BUFFER_SIZE, 
               pWCBuffer, (size_t)BUFFER_SIZE );

    // Output
    printf("   Characters converted: %u\n", i);
    printf("    Multibyte character: %s\n\n",
     pMBBuffer );

    // Free multibyte character buffer
    if (pMBBuffer)
    {
    free(pMBBuffer);
    }
}