wcstombs_s、_wcstombs_s_l

项目
06/09/2015

将多字节字符序列转换为对应的宽字符序列。 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 > 0	EINVAL
wcstr 为 NULL	EINVAL
目标缓冲区因过小而无法包含转换的字符串。(除非 count 是 _TRUNCATE；请参见下面"备注")	ERANGE

如果任一错误状态发生，调用无效参数异常，如参数验证所述。如果允许继续执行，函数返回错误代码然后按照下表设置 errno。

备注

wcstombs_s 函数将由wcstr 指向的缓冲区存储的多字节字符转换为 mbstr指向的缓冲区的宽字节字符。字符的转换将继续进行，直到与这些情况之一匹配：

遇到空宽字符
遇到不能转换宽字符
mbstr 缓冲存储字节数等于 count。

目标字符串始终为 null 终止 (即使发生错误)。

如果 count 是特殊值 _TRUNCATE，则当仍有 null 结束符的空间时，wcstombs_s 将许多字符串整合到目标缓冲区。

如果 wcstombs_s 成功转换了源字符串，它将转换字符串的字节的大小（包括空终止符）放入*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);
    }
}