wcstombs、_wcstombs_l

项目
06/09/2015

将多字节字符序列转换为对应的宽字符序列。提供这些函数的更多安全版本；请参见 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

参数

mbstr
多字节字符序列的地址。
wcstr
宽字节字符序列的地址。
count
输出在多字节字符串可存储最大字节数。
locale
要使用的区域设置。

返回值

如果 wcstombs 成功转换多字节字符串，则返回字节数写入输出的多字节字符串，包括终端 NULL （任何）。如果 mbstr 参数为 NULL，则 wcstombs 返回在目标字符串的字符串所需的大小。如果 wcstombs 遇到无法转换为多字节的宽字符，则返回 -1 ，强制转换成size_t 并将 errno 设置为 EILSEQ。

备注

wcstombs 函数将宽字符串通过 wcstr 指向一致的多字节字符并将结果存储在 mbstr 数组中。 count 参数即指示可以存储在输出的多字节字符串的最大字节数 (即 mbstr 的大小)。通常，当转换字符串时不知道需要多少字节。一些宽字符在输出字符串只需要一个字节；其他需要两个。如果在输入字符串的每个宽字符有多字节输出字符串的两字节 (包括 NULL)，确保结果适应。

如果 wcstombs 遇到空宽字符字符 (L' \ 0 ') 或之前，或者当 count 发生，则将其转换为 8 位 0 并停止。因此，只有在转换期间 wcstombs 遇到宽字节 null 字符，在 mbstr 的多字符字符串以 null 结尾。如果由 wcstr 与 mbstr 指向的序列重叠，wcstombs 行为是未定义的。

如果 mbstr 参数为 NULL，则 wcstombs 返回在目标字符串的字符串所需的大小。

wcstombs验证其参数。如果 wcstr 为 NULL，或者如果 count 大于INT_MAX，此函数调用的参数无效处理程序，如参数验证所述。如果允许执行继续，则该函数将 errno 设置为 EINVAL并返回 -1。

wcstombs使用区域设置相关行为的当前区域设置；和_wcstombs_l 相同，但它将使用传递的区域设置。有关详细信息，请参阅区域设置。

在 C++ 中，这些函数具有模板重载，以调用这些函数的更新、更安全副本。有关更多信息，请参见安全模板重载。

要求

例程	必需的标头
wcstombs	<stdlib.h>
_wcstombs_l	<stdlib.h>

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

示例

此程序阐述 wcstombs 函数的行为。

// 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);
}