wcstombs_s，_wcstombs_s_l

  • 项目

将宽字符序列转换为对应的多字节字符序列。 wcstombs、_wcstombs_l 版本，具有 CRT 中的安全性功能中所述的安全性增强功能。

语法

errno_t wcstombs_s(
   size_t *pReturnValue,
   char *mbstr,
   size_t sizeInBytes,
   const wchar_t *wcstr,
   size_t count
);

errno_t _wcstombs_s_l(
   size_t *pReturnValue,
   char *mbstr,
   size_t sizeInBytes,
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
);

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

template <size_t size>
errno_t _wcstombs_s_l(
   size_t *pReturnValue,
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
); // C++ only

参数

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

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

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

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

count
要存储在 mbstr 缓冲区中的最大字节数，不包括终止 null 字符或 _TRUNCATE。

locale
要使用的区域设置。

返回值

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

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

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

备注

wcstombs_s 函数将wcstr 指向的宽字节字符字符串转换为存储在 mbstr 指向的缓冲区中的多字节字符。 在满足以下条件之一前，该转换将一直对每个字符执行：

  • 遇到 null 宽字符

  • 遇到无法转换的宽字符

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

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

如果 count 是特殊值 _TRUNCATE，则 wcstombs_s 会根据目标缓冲区的容量尽量多地转换字符串，同时为 null 终止符留下空间。 如果字符串被截断，则返回值为 STRUNCATE，并且转换被视为成功。

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

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

如果 wcstr 和 mbstr 指向的序列重叠，则 wcstombs_s 的行为没有定义。

重要

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

wcstombs_s 对所有区域设置相关行为使用当前区域设置；_wcstombs_s_l 与 wcstombs 相同，只不过前者使用的是传入的区域设置。 有关详细信息，请参阅 Locale。

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

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

要求

例程 必需的标头
wcstombs_s <stdlib.h>

有关兼容性的详细信息，请参阅 兼容性。

示例

本程序演示 wcstombs_s 函数的行为。

// crt_wcstombs_s.c
// This example converts a wide character
// string to a multibyte character string.
#include <stdio.h>
#include <stdlib.h>
#include <assert.h>

#define BUFFER_SIZE 100

int main( void )
{
    size_t i;
    char *pMBBuffer = (char *)malloc( BUFFER_SIZE );
    const wchar_t*pWCBuffer = L"Hello, world.";

    printf( "Convert wide-character string:\n" );

    // Conversion
    wcstombs_s(&i, pMBBuffer, (size_t)BUFFER_SIZE,
               pWCBuffer, (size_t)BUFFER_SIZE - 1); // -1 so the appended NULL doesn't fall outside the allocated buffer

    // Output
    printf("   Characters converted: %u\n", i);
    printf("    Multibyte character: %s\n\n", pMBBuffer );

    // Free multibyte character buffer
    if (pMBBuffer)
    {
        free(pMBBuffer);
    }
    
    return 0;
}

Convert wide-character string:
   Characters converted: 14
    Multibyte character: Hello, world.

另请参阅

数据转换
区域设置
_mbclen、mblen、_mblen_l
mbstowcs、_mbstowcs_l
mbtowc、_mbtowc_l
wctomb_s、_wctomb_s_l
WideCharToMultiByte