wcrtomb_s

将宽字符转换为多字节字符表示形式。 这是 wcrtomb 版本，具有 CRT 中的安全性功能中所述的安全性增强功能。

语法

errno_t wcrtomb_s(
   size_t *pReturnValue,
   char *mbchar,
   size_t sizeOfmbchar,
   wchar_t *wchar,
   mbstate_t *mbstate
);
template <size_t size>
errno_t wcrtomb_s(
   size_t *pReturnValue,
   char (&mbchar)[size],
   wchar_t *wchar,
   mbstate_t *mbstate
); // C++ only

参数

pReturnValue
返回写入的字节数，如果发生错误，则返回 -1。

mbchar
生成的多字节转换字符。

sizeOfmbchar
mbchar 变量的大小（以字节为单位）。

wchar
要转换的宽字符。

mbstate
指向 mbstate_t 对象的指针。

返回值

返回零，如果发生错误，则返回 errno 值。

注解

从 mbstate 中包含的指定转换状态开始，wcrtomb_s 函数将 wchar 的宽字符值转换为 mbchar 表示的地址。 pReturnValue 值是转换的字节数，但不能超过 MB_CUR_MAX 字节，发生错误时该值为 -1。

如果 mbstate 为 null，则使用内部 mbstate_t 转换状态。 如果 wchar 包含的字符没有相应的多字节字符，则 pReturnValue 值为 -1 且函数将返回 EILSEQ 的 errno 值。

wcrtomb_s 函数的可重启性不同于 wctomb_s、_wctomb_s_l。 转换状态存储在 mbstate 中，以便后续调用相同的或其他可重启函数。 混合使用可重启函数和不可重启函数时，结果不确定。 例如，如果使用 wcsrlen（而非 wcslen）的后续调用，则应用程序应使用 wcsrtombs_s，而非 wcstombs_s。

在 C++ 中，模板重载简化了此函数的使用；重载可以自动推导出缓冲区长度（不再需要指定大小自变量），并且它们可以自动用更新、更安全的对应物替换不安全的旧函数。 有关详细信息，请参阅安全模板重载。

默认情况下，此函数的全局状态范围限定为应用程序。 若要更改此行为，请参阅 CRT 中的全局状态。

例外

只要当前线程中的函数都不调用 setlocale，此函数正在执行且 mbstate 是 null，wcrtomb_s 函数就是多线程安全的。

示例

// crt_wcrtomb_s.c
// This program converts a wide character
// to its corresponding multibyte character.
//

#include <string.h>
#include <stdio.h>
#include <wchar.h>

int main( void )
{
    errno_t     returnValue;
    size_t      pReturnValue;
    mbstate_t   mbstate;
    size_t      sizeOfmbStr = 1;
    char        mbchar = 0;
    wchar_t*    wchar = L"Q\0";

    // Reset to initial conversion state
    memset(&mbstate, 0, sizeof(mbstate));

    returnValue = wcrtomb_s(&pReturnValue, &mbchar, sizeof(char),
                            *wchar, &mbstate);
    if (returnValue == 0) {
        printf("The corresponding wide character \"");
        wprintf(L"%s\"", wchar);
        printf(" was converted to a the \"%c\" ", mbchar);
        printf("multibyte character.\n");
    }
    else
    {
        printf("No corresponding multibyte character "
               "was found.\n");
    }
}

The corresponding wide character "Q" was converted to a the "Q" multibyte character.

要求

例程	必需的标头
wcrtomb_s	<wchar.h>

另请参阅

数据转换
区域设置
多字节字符序列的解释
mbsinit