wcrtomb_s

项目
06/09/2015

将宽字符转换为它的多字节字符形式。 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

参数

[out] pReturnValue
如果发生错误，返回写入的字符数或 -1。
[out] mbchar
生成的多字节转换字符。
[in] sizeOfmbchar
mbchar 字节变量的大小。
[in] wchar
要转换的宽字符。
[in] mbstate
指向 mbstate_t 对象的指针。

返回值

如果出错，返回零或 errno 值。

备注

wcrtomb_s 函数将一个宽字符转换为，在特定转换状态开始，包括mbstate，从在 wchar 包括的值，到通过 mbchar 地址形式。如果出错，pReturnValue 值的比特数的值会被修改，但是不会超过MB_CUR_MAX 字节数，或为-1。

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

wcrtomb_s 函数重启不同于 wctomb_s、_wctomb_s_l 。转换状态存储在 mbstate 随后调用相同或其他可重新启动的函数。当混淆重启和非重启函数的使用时，则结果未定义。例如，如果随后调用 wcsrtombs_s 而不是 wcstombs_s.，则应用程序应使用 wcsrlen 而不是 wcslen。

在 C++ 中，通过模板重载使用这些函数很简单；重载可以自动推导出缓冲区长度 (不再需要指定大小参数)，并且它们可以自动用以更新、更安全的对应物替换旧的、不安全的函数。有关更多信息，请参见安全模板重载。

异常

只要当函数正在执行和 mbstate 为空时，在当前线程中无函数调用 setlocale时，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");
    }
}