strcpy_s, wcscpy_s, _mbscpy_s, _mbscpy_s_l

复制字符串。 这些版本的 strcpy、wcscpy、_mbscpy 具有安全增强功能，如 CRT 中的安全功能中所述。

重要

_mbscpy_s 和 _mbscpy_s_l 无法用于在 Windows 运行时中执行的应用程序。 有关详细信息，请参阅通用 Windows 平台应用中不支持的 CRT 函数。

语法

errno_t strcpy_s(
   char *dest,
   rsize_t dest_size,
   const char *src
);
errno_t wcscpy_s(
   wchar_t *dest,
   rsize_t dest_size,
   const wchar_t *src
);
errno_t _mbscpy_s(
   unsigned char *dest,
   rsize_t dest_size,
   const unsigned char *src
);
errno_t _mbscpy_s_l(
   unsigned char *dest,
   rsize_t dest_size,
   const unsigned char *src,
   _locale_t locale
);

// Template functions are C++ only:
template <size_t size>
errno_t strcpy_s(
   char (&dest)[size],
   const char *src
); // C++ only
template <size_t size>
errno_t wcscpy_s(
   wchar_t (&dest)[size],
   const wchar_t *src
); // C++ only
template <size_t size>
errno_t _mbscpy_s(
   unsigned char (&dest)[size],
   const unsigned char *src
); // C++ only
template <size_t size>
errno_t _mbscpy_s_l(
   unsigned char (&dest)[size],
   const unsigned char *src,
   _locale_t locale
); // C++ only

参数

dest
目标字符串缓冲区的位置。

dest_size
多字节窄函数 char 单元以及宽函数 wchar_t 单元中的目标字符串缓冲区的大小。 此值必须大于零，且不能大于 RSIZE_MAX。 确保此大小考虑了字符串后的 NULL 终止。

src
以 null 结尾的源字符串缓冲区。

locale
要使用的区域设置。

返回值

如果成功，则为零；否则返回错误。

错误条件

dest	dest_size	src	返回值	dest 的内容
NULL	any	any	EINVAL	未修改
any	任意	NULL	EINVAL	dest[0]：设置为 0
任意	0 或过小	any	ERANGE	dest[0]：设置为 0

备注

strcpy_s 函数将 src 地址中的内容（包括结尾的 null 字符）复制到 dest 指定的位置。 目标字符串必须足够大以保存源字符串及其结尾的 null 字符。 如果源和目标字符串重叠，则 strcpy_s 的行为是未定义的。

wcscpy_s 是宽字符版本的 strcpy_s；_mbscpy_s 是多字节字符版本。 wcscpy_s 的自变量是宽字符字符串。 _mbscpy_s 和 _mbscpy_s_l 的自变量是多字节字符字符串。 否则这些函数具有相同行为。 _mbscpy_s_l 与 _mbscpy_s 是相同的，只不过它改用传递的区域设置参数，而不是当前区域设置。 有关详细信息，请参阅 locale。

如果 dest 或 src 是空指针，或者如果大小为 dest_size 的目标字符串过小，则调用无效参数处理程序，如参数验证中所述。 如果允许继续执行，则在 dest 或 src 是 null 指针时，这些函数将返回 EINVAL 并将 errno 设置为 EINVAL；如果目标字符串过小，则它们将返回 ERANGE 并将 errno 设置为 ERANGE。

成功执行时，目标字符串始终以 null 结尾。

在 C++ 中，这些函数的使用由模板重载简化，重载可以自动推导出缓冲区长度，这样就不必指定大小自变量。 而且，它们可以自动将不太安全的旧函数替换为更新、更安全的函数。 有关详细信息，请参阅安全模板重载。

这些函数的调试库版本首先用 0xFE 填充缓冲区。 若要禁用此行为，请使用 _CrtSetDebugFillThreshold。

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

一般文本例程映射

TCHAR.H 例程	_UNICODE 和 _MBCS 未定义	_MBCS 已定义	_UNICODE 已定义
_tcscpy_s	strcpy_s	_mbscpy_s	wcscpy_s

要求

例程	必需的标头
strcpy_s	<string.h>
wcscpy_s	<string.h> 或 <wchar.h>
_mbscpy_s	<mbstring.h>

这些函数是 Microsoft 特定函数。 有关兼容性的详细信息，请参阅 兼容性。

示例

与生产质量代码不同，此示例在不检查错误的情况下调用安全字符串函数：

// crt_strcpy_s.c
// Compile by using: cl /W4 crt_strcpy_s.c
// This program uses strcpy_s and strcat_s
// to build a phrase.

#include <string.h>     // for strcpy_s, strcat_s
#include <stdlib.h>     // for _countof
#include <stdio.h>      // for printf
#include <errno.h>      // for return values

int main(void)
{
    char stringBuffer[80];

    strcpy_s(stringBuffer, _countof(stringBuffer), "Hello world from ");
    strcat_s(stringBuffer, _countof(stringBuffer), "strcpy_s ");
    strcat_s(stringBuffer, _countof(stringBuffer), "and ");
    strcat_s(stringBuffer, _countof(stringBuffer), "strcat_s!");

    printf("stringBuffer = %s\n", stringBuffer);
}

stringBuffer = Hello world from strcpy_s and strcat_s!

生成 C++ 代码时，模板版本可能更易于使用。

// crt_wcscpy_s.cpp
// Compile by using: cl /EHsc /W4 crt_wcscpy_s.cpp
// This program uses wcscpy_s and wcscat_s
// to build a phrase.

#include <cstring>  // for wcscpy_s, wcscat_s
#include <cstdlib>  // for _countof
#include <iostream> // for cout, includes <cstdlib>, <cstring>
#include <errno.h>  // for return values

int main(void)
{
    wchar_t stringBuffer[80];
    // using template versions of wcscpy_s and wcscat_s:
    wcscpy_s(stringBuffer, L"Hello world from ");
    wcscat_s(stringBuffer, L"wcscpy_s ");
    wcscat_s(stringBuffer, L"and ");
    // of course we can supply the size explicitly if we want to:
    wcscat_s(stringBuffer, _countof(stringBuffer), L"wcscat_s!");

    std::wcout << L"stringBuffer = " << stringBuffer << std::endl;
}

stringBuffer = Hello world from wcscpy_s and wcscat_s!

另请参阅

字符串操作
strcat、wcscat、_mbscat、_mbscat_l
strcmp、wcscmp、_mbscmp、_mbscmp_l
strncat_s、_strncat_s_l、wcsncat_s、_wcsncat_s_l、_mbsncat_s、_mbsncat_s_l
strncmp、wcsncmp、_mbsncmp、_mbsncmp_l
strncpy_s、_strncpy_s_l、wcsncpy_s、_wcsncpy_s_l、_mbsncpy_s、_mbsncpy_s_l
_strnicmp、_wcsnicmp、_mbsnicmp、_strnicmp_l、_wcsnicmp_l、_mbsnicmp_l
strrchr、wcsrchr、_mbsrchr、_mbsrchr_l
strspn、wcsspn、_mbsspn、_mbsspn_l