_mbccpy_s、_mbccpy_s_l_mbccpy_s, _mbccpy_s_l

将一个多字节字符从一个字符串复制到另一个字符串。Copies one multibyte character from a string to another string. 这些版本的 _mbccpy、_mbccpy_l 具有安全增强功能,如 CRT 中的安全功能所述。These versions of _mbccpy, _mbccpy_l have security enhancements, as described in Security Features in the CRT.

重要

此 API 不能用于在 Windows 运行时中执行的应用程序。This API cannot be used in applications that execute in the Windows Runtime. 有关详细信息,请参阅通用 Windows 平台应用中不支持的 CRT 函数For more information, see CRT functions not supported in Universal Windows Platform apps.

语法Syntax

errno_t _mbccpy_s(
   unsigned char *dest,
   size_t buffSizeInBytes,
   int * pCopied,
   const unsigned char *src
);
errno_t _mbccpy_s_l(
   unsigned char *dest,
   size_t buffSizeInBytes,
   int * pCopied,
   const unsigned char *src,
   locale_t locale
);
template <size_t size>
errno_t _mbccpy_s(
   unsigned char (&dest)[size],
   int * pCopied,
   const unsigned char *src
); // C++ only
template <size_t size>
errno_t _mbccpy_s_l(
   unsigned char (&dest)[size],
   int * pCopied,
   const unsigned char *src,
   locale_t locale
); // C++ only

参数Parameters

destdest
复制目标。Copy destination.

buffSizeInBytesbuffSizeInBytes
目标缓冲区的大小。Size of the destination buffer.

pCopiedpCopied
填充复制的字节数(如果成功则为 1 或 2)。Filled with the number of bytes copied (1 or 2 if successful). 传递NULL如果你不关心数。Pass NULL if you don't care about the number.

srcsrc
要复制的多字节字符。Multibyte character to copy.

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

返回值Return Value

如果成功,则为零;如果失败,则为错误代码。Zero if successful; an error code on failure. 如果srcdestNULL,或如果多个buffSizeinBytes字节都要复制到dest,然后调用无效参数处理程序,如中所述参数验证If src or dest is NULL, or if more than buffSizeinBytes bytes would be copied to dest, then the invalid parameter handler is invoked, as described in Parameter Validation. 如果允许执行继续,函数将返回EINVALerrno设置为EINVALIf execution is allowed to continue, the functions return EINVAL and errno is set to EINVAL.

备注Remarks

_Mbccpy_s函数将复制一个多字节字符从srcdestThe _mbccpy_s function copies one multibyte character from src to dest. 如果src未指向所确定的隐式调用那样多字节字符的前导字节_ismbblead,然后单字节的src复制到的点。If src does not point to the lead byte of a multibyte character as determined by an implicit call to _ismbblead, then the single byte that src points to is copied. 如果src指向前导字节,但下一个字节 0 和因此无效,则 0 复制到desterrno设置为EILSEQ,与函数返回EILSEQIf src points to a lead byte but the following byte is 0 and thus invalid, then 0 is copied to dest, errno is set to EILSEQ, and the function returns EILSEQ.

_mbccpy_s不附加 null 终止符的占用; 但是,如果src指向 null 字符,则该 null 将复制到dest (这是只是常规的单字节副本)。_mbccpy_s does not append a null terminator; however, if src points to a null character, then that null is copied to dest (this is just a regular single-byte copy).

中的值pCopied填入复制的字节数。The value in pCopied is filled with the number of bytes copied. 如果操作成功,则可能的值为 1 和 2。Possible values are 1 and 2 if the operation is successful. 如果NULL传递在中,忽略此参数。If NULL is passed in, this parameter is ignored.

srcsrc 复制到目标copied to dest pCopiedpCopied 返回值Return value
非前导字节non-lead-byte 非前导字节non-lead-byte 11 00
00 00 11 00
前导字节,后跟非零值lead-byte followed by non-0 前导字节,后跟非零值lead-byte followed by non-0 22 00
前导字节,后跟 0lead-byte followed by 0 00 11 EILSEQEILSEQ

请注意,第二行只是第一行的特殊情况。Note that the second row is just a special case of the first. 另请注意,此表假定buffSizeInBytes >= pCopiedAlso note that the table assumes buffSizeInBytes >= pCopied.

_mbccpy_s的任何区域设置相关行为使用当前区域设置。_mbccpy_s uses the current locale for any locale-dependent behavior. _mbccpy_s_l等同于 _mbccpy_s只不过 _mbccpy_s_l使用为任何区域设置相关的行为传入的区域设置。_mbccpy_s_l is identical to _mbccpy_s except that _mbccpy_s_l uses the locale passed in for any locale-dependent behavior.

在 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. 有关详细信息,请参阅 Secure Template OverloadsFor more information, see Secure Template Overloads.

一般文本例程映射Generic-Text Routine Mappings

Tchar.h 例程Tchar.h routine 未定义 _UNICODE 和 _MBCS_UNICODE and _MBCS not defined 已定义 _MBCS_MBCS defined 已定义 _UNICODE_UNICODE defined
_tccpy_s_tccpy_s 映射到宏或内联函数。Maps to macro or inline function. _mbccpy_s_mbccpy_s 映射到宏或内联函数。Maps to macro or inline function.

要求Requirements

例程Routine 必需的标头Required header
_mbccpy_s_mbccpy_s <mbstring.h><mbstring.h>
_mbccpy_s_l_mbccpy_s_l <mbstring.h><mbstring.h>

有关更多兼容性信息,请参阅 兼容性For more compatibility information, see Compatibility.

请参阅See also

区域设置Locale
多字节字符序列的解释Interpretation of Multibyte-Character Sequences
_mbclen、mblen、_mblen_l_mbclen, mblen, _mblen_l