wcstombs_s、_wcstombs_s_lwcstombs_s, _wcstombs_s_l

将宽字符序列转换为对应的多字节字符序列。Converts a sequence of wide characters to a corresponding sequence of multibyte characters. wcstombs、_wcstombs_l 的一个版本,具有 CRT 中的安全功能中所述的安全增强功能。A version of wcstombs, _wcstombs_l with security enhancements as described in Security Features in the CRT.

语法Syntax

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

参数Parameters

pReturnValuepReturnValue
要转换的字符数。The number of characters converted.

mbstrmbstr
生成的已转换多字节字符字符串的缓冲区的地址。The address of a buffer for the resulting converted multibyte character string.

sizeInBytessizeInBytes
以字节为单位的大小mbstr缓冲区。The size in bytes of the mbstr buffer.

wcstrwcstr
指向要转换的宽字符字符串的指针。Points to the wide character string to be converted.

countcount
要在中存储的字节的最大数mbstr缓冲区,不包括终止 null 字符,或_TRUNCATEThe maximum number of bytes to store in the mbstr buffer, not including the terminating null character, or _TRUNCATE.

localelocale
要使用的区域设置。The locale to use.

返回值Return Value

如果成功,返回零;如果失败,则返回错误代码。Zero if successful, an error code on failure.

错误条件Error condition 返回值和errnoReturn value and errno
mbstrNULLsizeInBytes > 0mbstr is NULL and sizeInBytes > 0 EINVALEINVAL
wcstrNULLwcstr is NULL EINVALEINVAL
目标缓冲区因过小,无法包含转换后的字符串 (除非计数_TRUNCATE; 请参阅下面的备注)The destination buffer is too small to contain the converted string (unless count is _TRUNCATE; see Remarks below) ERANGEERANGE

如果发生这些情况中的任何一个,都会调用无效参数异常,如参数验证中所述。If any of these conditions occurs, the invalid parameter exception is invoked as described in Parameter Validation . 如果允许执行继续,函数将返回错误代码,并设置errno如下表所示。If execution is allowed to continue, the function returns an error code and sets errno as indicated in the table.

备注Remarks

Wcstombs_s函数将转换的指向的宽字符字符串wcstr指向的缓冲区中存储的多字节字符mbstrThe wcstombs_s function converts a string of wide characters pointed to by wcstr into multibyte characters stored in the buffer pointed to by mbstr. 在满足以下条件之一前,该转换将一直对每个字符执行:The conversion will continue for each character until one of these conditions is met:

  • 遇到 null 宽字符A null wide character is encountered

  • 遇到无法转换的宽字符A wide character that cannot be converted is encountered

  • 存储中的字节数mbstr缓冲 equals计数The number of bytes stored in the mbstr buffer equals count.

目标字符串始终以 null 结尾(即使在出错时)。The destination string is always null-terminated (even in the case of an error).

如果计数是特殊值_TRUNCATE,然后wcstombs_s多地将字符串转换根据目标缓冲区,同时仍保留为空的空间终结器。If count is the special value _TRUNCATE, then wcstombs_s converts as much of the string as will fit into the destination buffer, while still leaving room for a null terminator. 如果该字符串被截断,则返回值是STRUNCATE,和转换仍被视为成功。If the string is truncated, the return value is STRUNCATE, and the conversion is considered successful.

如果wcstombs_s成功转换了源字符串,它的大小放以字节为单位的转换后的字符串,包括 null 终止符 *pReturnValue (提供pReturnValue不是NULL)。If wcstombs_s successfully converts the source string, it puts the size in bytes of the converted string, including the null terminator, into *pReturnValue (provided pReturnValue is not NULL). 发生这种情况即使mbstr自变量是NULL ,并提供了一种方法来确定所需的缓冲区大小。This occurs even if the mbstr argument is NULL and provides a way to determine the required buffer size. 请注意,如果mbstrNULL计数将被忽略。Note that if mbstr is NULL, count is ignored.

如果wcstombs_s遇到无法转换为多字节字符的宽字符它将 0 放入 *pReturnValue,将目标缓冲区设置为空字符串,设置errnoEILSEQ,并返回EILSEQIf wcstombs_s encounters a wide character it cannot convert to a multibyte character, it puts 0 in *pReturnValue, sets the destination buffer to an empty string, sets errno to EILSEQ, and returns EILSEQ.

如果指向的序列wcstrmbstr重叠的行为wcstombs_s是不确定的。If the sequences pointed to by wcstr and mbstr overlap, the behavior of wcstombs_s is undefined.

重要

絋粄wcstrmbstr未重叠,并且计数是否正确反映了要转换的宽字符数。Ensure that wcstr and mbstr do not overlap, and that count correctly reflects the number of wide characters to convert.

wcstombs_s的任何区域设置相关的行为; 使用当前区域设置 _wcstombs_s_l等同于wcstombs只不过它改用已传入的区域设置。wcstombs_s uses the current locale for any locale-dependent behavior; _wcstombs_s_l is identical to wcstombs except that it uses the locale passed in instead. 有关详细信息,请参阅 LocaleFor more information, see Locale.

在 C++ 中,使用这些函数由模板重载简化;重载可以自动推导出缓冲区长度 (不再需要指定大小自变量),并且它们可以自动用以更新、更安全的对应物替换旧的、不安全的函数。In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. 有关详细信息,请参阅 Secure Template OverloadsFor more information, see Secure Template Overloads.

要求Requirements

例程所返回的值Routine 必需的标头Required header
wcstombs_swcstombs_s <stdlib.h><stdlib.h>

有关其他兼容性信息,请参阅 兼容性For additional compatibility information, see Compatibility.

示例Example

本程序演示的行为wcstombs_s函数。This program illustrates the behavior of the wcstombs_s function.

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

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

    // Free multibyte character buffer
    if (pMBBuffer)
    {
    free(pMBBuffer);
    }
}
Convert wide-character string:
   Characters converted: 14
    Multibyte character: Hello, world.

请参阅See also

数据转换Data Conversion
区域设置Locale
_mbclen、mblen、_mblen_l_mbclen, mblen, _mblen_l
mbstowcs、_mbstowcs_lmbstowcs, _mbstowcs_l
mbtowc、_mbtowc_lmbtowc, _mbtowc_l
wctomb_s、_wctomb_s_lwctomb_s, _wctomb_s_l
WideCharToMultiByteWideCharToMultiByte