wcsrtombs_s

将宽字符字符串转换为多字节字符字符串表示形式。 wcsrtombs 的版本与安全增强的 CRT中的安全功能如中所述。

errno_t wcsrtombs_s(
   size_t *pReturnValue,
   char *mbstr,
   size_t sizeInBytes,
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
);
template <size_t size>
errno_t wcsrtombs_s(
   size_t *pReturnValue,
   char (&mbstr)[size],
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
); // C++ only

参数

  • [out] pReturnValue
    转换后的字符数。

  • [out] mbstr
    缓冲区的地址发生的转换过多字节字符字符串。

  • [out] sizeInBytes
    范围在 mbstr 缓冲区的字节。

  • [in] wcstr
    指向要转换的宽字符字符串。

  • [in] count
    在 mbstr 缓冲区将存储最大字节数或者 _TRUNCATE

  • [in] mbstate
    为 mbstate_t 转换状态对象的指针。

返回值

零,如果成功,则失败的错误代码。

错误状态

返回值和 errno

mbstr 是 NULL 和 sizeInBytes AMP_GT 0

EINVAL

wcstr 为 NULL

EINVAL

(除非 count 是 _TRUNCATE,目标缓冲区因过小而无法包含被转换的字符串;请参见下面的 " 备注 ")

ERANGE

如果这些条件中的任何一个结果,无效参数异常调用 参数验证 如中所述。 如果执行允许继续,该函数返回错误代码并如下表所示设置 errno 。

备注

wcsrtombs_s 函数 wcstr 点转换为宽字符字符串转换为缓冲区存储的多字节字符指向由 mbstr,在 mbstate包含的转换状态。 转换为每个字符将继续,直到上述任一条件匹配:

  • 空白宽字符遇到

  • 未能转换的宽字符遇到

  • 在 mbstr 缓冲区存储字节数等于 count。

目标字符串始终以 null 终止 (即使在错误)。

如果 count 为特殊值 _TRUNCATE,则 wcsrtombs_s 转换相同多个字符串与将放入目标缓冲区,那么,当仍 null 结束符时空间。

如果 wcsrtombs_s 成功转换源字符串,它在转换的字符串的字节放入范围,包括 null 结束符,以 *pReturnValue (提供的 pReturnValue 不是 NULL)。 发生这种情况,即使 mbstr 参数是 NULL 并提供用于确定所需的缓冲区大小。 请注意,如果 mbstr 是 NULL, count 被忽略。

如果它不能转换为多字节字符的 wcsrtombs_s 遇到宽字符,它在 *pReturnValue放置 -1,设置目标缓冲区设置为空字符串,设置 errno 到 EILSEQ,并返回 EILSEQ。

如果顺序指向由 wcstr 和 mbstr 重叠, wcsrtombs_s 行为不确定。 wcsrtombs_s 受当前区域设置的 LC_TYPE 类别的影响。

安全说明安全说明

确保 wcstr 和 mbstr 重叠,并且, count 准确反映宽字符数转换。

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

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

异常

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

示例

// crt_wcsrtombs_s.cpp
// 
// This code example converts a wide
// character string into a multibyte
// character string.
//

#include <stdio.h>
#include <memory.h>
#include <wchar.h>
#include <errno.h>

#define MB_BUFFER_SIZE 100

void main()
{
    const wchar_t   wcString[] = 
                    {L"Every good boy does fine."};
    const wchar_t   *wcsIndirectString = wcString;
    char            mbString[MB_BUFFER_SIZE];
    size_t          countConverted;
    errno_t         err;
    mbstate_t       mbstate;

    // Reset to initial shift state
    ::memset((void*)&mbstate, 0, sizeof(mbstate));

    err = wcsrtombs_s(&countConverted, mbString, MB_BUFFER_SIZE,
                      &wcsIndirectString, MB_BUFFER_SIZE, &mbstate);
    if (err == EILSEQ)
    {
        printf( "An encoding error was detected in the string.\n" );
    }
    else 
    {
        printf( "The string was successfully converted.\n" );
    }
}
  

.NET Framework 等效项

不适用。若要调用标准 C 函数,请使用 PInvoke。有关更多信息,请参见 平台调用示例

要求

实例

必需的头

wcsrtombs_s

wchar.h

请参见

参考

数据转换

区域设置

多字节字符序列的说明

wcrtomb

wcrtomb_s

wctomb, _wctomb_l

wcstombs, _wcstombs_l

mbsinit