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