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

参数

pReturnValue
转换后的字符串的大小（以字节为单位），包括 null 终止符。

mbstr
生成的已转换多字节字符字符串的缓冲区的地址。

sizeInBytes
缓冲区 mbstr 的大小（以字节为单位）。

wcstr
指向要转换的宽字符字符串的指针。

count
mbstr 缓冲区或 _TRUNCATE 要存储的最大字节数。

mbstate
指向 mbstate_t 转换状态对象的指针。

返回值

如果成功，返回零；如果失败，则返回错误代码。

添加状态 返回值和 errno
mbstr 为 NULL 且 sizeInBytes> 0 EINVAL
wcstr 是 NULL EINVAL
目标缓冲区过小，无法包含转换的字符串（除非 count 是 _TRUNCATE；请参阅下面的备注） ERANGE

如果发生这些情况中的任何一个，都会调用无效参数异常，如参数验证中所述。 如果允许执行继续，函数将返回错误代码并按表中所示设置 errno。

注解

wcsrtombs_s 函数通过使用 mbstate 中包含的转换状态，将由 wcstr 指向的宽字符的字符串转换为 mbstr 指向的缓冲区中存储的多字节字符。 在满足以下条件之一前，该转换将一直对每个字符执行：

  • 遇到 null 宽字符

  • 遇到无法转换的宽字符

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

目标字符串始终以 null 结尾（即使有错误）。

如果 count 是特殊值 _TRUNCATE，则 wcsrtombs_s 会根据目标缓冲区的容量尽量多地转换字符串，同时为 null 终止符留下空间。

如果 wcsrtombs_s 成功转换了源字符串，它会将转换的字符串（包括 null 终止符）的大小（以字节为单位）放入 *pReturnValue（假定 pReturnValue 不是 NULL）。 即使 mbstr 参数是 NULL，也会计算大小；它提供了一种方法来确定所需的缓冲区大小。 如果 mbstr 为 NULL，则忽略 count。

如果 wcsrtombs_s 遇到无法转换为多字节字符的宽字符，会将 -1 放入 *pReturnValue，将目标缓冲区设置为空字符串，将 errno 设置为 EILSEQ，并返回 EILSEQ。

如果 wcstr 和 mbstr 指向的序列重叠，则 wcsrtombs_s 的行为没有定义。 wcsrtombs_s 受到当前区域设置中 LC_TYPE 类别的影响。

重要

请确保 wcstr 和 mbstr 未重叠，并且 count 正确地反映了要转换的宽字节的数量。

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

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

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

例外

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

示例

// 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

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

The string was successfully converted.

要求

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

另请参阅

数据转换
区域设置
多字节字符序列的解释
wcrtomb
wcrtomb_s
wctomb、_wctomb_l
wcstombs、_wcstombs_l
mbsinit