wcrtomb_s

项目
02/21/2013

将宽字符转换为字节字符表示形式。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 为空，使用内部 mbstate_t 转换状态。如果在 wchar 包含的字符没有相应的多字节字符， pReturnValue 的值将为 -1，并且该函数将返回 EILSEQ的 errno 值。

wcrtomb_s 功能与 wctomb_s， _wctomb_s_l 不同由其 restartability。转换状态中的 mbstate 存储的后续调用相同或其他可重新启动的功能。，混合使用可重新启动和 nonrestartable 函数时，结果是未定义的。例如，应用程序将使用 wcsrlen 而不是 wcslen，因此，如果以后对 wcsrtombs_s 使用了而不是 wcstombs_s.

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

异常

wcrtomb_s 功能是多线程安全性，只要在当前线程的函数不调用 setlocale ，则此函数执行时，并 mbstate 为空。

示例

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