strcpy_s、wcscpy_s、_mbscpy_sstrcpy_s, wcscpy_s, _mbscpy_s

复制字符串。Copies a string. CRT 中的安全性增强功能所述,这些版本的 strcpy、wcscpy、_mbscpy 具有安全性增强功能。These versions of strcpy, wcscpy, _mbscpy have security enhancements, as described in Security Features in the CRT.

重要

_mbscpy_s不能用于在 Windows 运行时中执行的应用程序。_mbscpy_s 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 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
);
// 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

参数Parameters

destdest
目标字符串缓冲区的位置。Location of the destination string buffer.

dest_sizedest_size
中的目标字符串缓冲区大小char对于窄和多字节函数,单位和wchar_t宽函数的单位。Size of the destination string buffer in char units for narrow and multi-byte functions, and wchar_t units for wide functions. 此值必须大于零并且不得大于RSIZE_MAXThis value must be greater than zero and not greater than RSIZE_MAX.

srcsrc
以 null 结尾的源字符串缓冲区。Null-terminated source string buffer.

返回值Return Value

如果成功,则为零;否则返回错误。Zero if successful; otherwise, an error.

错误条件Error Conditions

destdest dest_sizedest_size srcsrc 返回值Return value 内容目标Contents of dest
NULLNULL 任何any 任何any EINVALEINVAL 未修改not modified
任何any 任何any NULLNULL EINVALEINVAL 目标[0] 设置为 0dest[0] set to 0
任何any 0 或过小0, or too small 任何any ERANGEERANGE 目标[0] 设置为 0dest[0] set to 0

备注Remarks

Strcpy_s函数将内容复制中的地址src,包括终止 null 字符,由指定的位置destThe strcpy_s function copies the contents in the address of src, including the terminating null character, to the location that's specified by dest. 目标字符串必须足够大以保存源字符串及其结尾的 null 字符。The destination string must be large enough to hold the source string and its terminating null character. 行为strcpy_s是不确定的如果源和目标字符串重叠。The behavior of strcpy_s is undefined if the source and destination strings overlap.

wcscpy_s是宽字符版本的strcpy_s,和 _mbscpy_s是多字节字符版本。wcscpy_s is the wide-character version of strcpy_s, and _mbscpy_s is the multibyte-character version. 自变量wcscpy_s是宽字符字符串; 而的 _mbscpy_s是多字节字符字符串。The arguments of wcscpy_s are wide-character strings; those of _mbscpy_s are multibyte-character strings. 否则这三个函数否则具有相同行为。These three functions behave identically otherwise.

如果destsrc是 null 指针,或如果目标字符串大小dest_size是太小,则调用无效参数处理程序,如中所述参数验证If dest or src is a null pointer, or if the destination string size dest_size is too small, the invalid parameter handler is invoked, as described in Parameter Validation. 如果允许执行继续,则这些函数将返回EINVAL并设置errnoEINVALdestsrc null 指针,并且它们返回ERANGE并设置errnoERANGE目标字符串时太小。If execution is allowed to continue, these functions return EINVAL and set errno to EINVAL when dest or src is a null pointer, and they return ERANGE and set errno to ERANGE when the destination string is too small.

成功执行时,目标字符串始终以 null 结尾。Upon successful execution, the destination string is always null-terminated.

在 C++ 中,模板重载简化了这些函数的使用;重载可以自动推断缓冲区长度,从而无需指定大小自变量;并且它们可以自动将较旧、不安全的函数替换为更新、更安全的函数。In C++, use of these functions is simplified by template overloads that can infer buffer length automatically so that you don't have to specify a size argument, and they can automatically replace older, less-secure functions with their newer, more secure counterparts. 有关详细信息,请参阅 Secure Template OverloadsFor more information, see Secure Template Overloads.

这些函数的调试库版本首先填充具有 0xFE 的缓冲区。The debug library versions of these functions first fill the buffer with 0xFE. 若要禁用此行为,请使用 _CrtSetDebugFillThresholdTo disable this behavior, use _CrtSetDebugFillThreshold.

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

TCHAR.H 例程TCHAR.H routine 未定义 _UNICODE 和 _MBCS_UNICODE & _MBCS not defined 已定义 _MBCS_MBCS defined 已定义 _UNICODE_UNICODE defined
_tcscpy_s_tcscpy_s strcpy_sstrcpy_s _mbscpy_s_mbscpy_s wcscpy_swcscpy_s

要求Requirements

例程Routine 必需的标头Required header
strcpy_sstrcpy_s <string.h><string.h>
wcscpy_swcscpy_s <string.h> 或 <wchar.h><string.h> or <wchar.h>
_mbscpy_s_mbscpy_s <mbstring.h><mbstring.h>

这些函数是特定于 Microsoft 的。These functions are Microsoft-specific. 有关其他兼容性信息,请参阅 兼容性For additional compatibility information, see Compatibility.

示例Example

生产质量与代码不同,此示例调用而不会检查有错误的安全字符串函数:Unlike production quality code, this sample calls the secure string functions without checking for errors:

// 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 string[80];

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

    printf("String = %s\n", string);
}
String = Hello world from strcpy_s and strcat_s!

在生成 c + + 代码时,可以更轻松地使用的模板版本。When building C++ code, the template versions may be easier to use.

// 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 string[80];
    // using template versions of wcscpy_s and wcscat_s:
    wcscpy_s(string, L"Hello world from ");
    wcscat_s(string, L"wcscpy_s ");
    wcscat_s(string, L"and ");
    // of course we can supply the size explicitly if we want to:
    wcscat_s(string, _countof(string), L"wcscat_s!");

    std::wcout << L"String = " << string << std::endl;
}
String = Hello world from wcscpy_s and wcscat_s!

请参阅See also

字符串操作String Manipulation
strcat、wcscat、_mbscatstrcat, wcscat, _mbscat
strcmp、wcscmp、_mbscmpstrcmp, wcscmp, _mbscmp
strncat_s、_strncat_s_l、wcsncat_s、_wcsncat_s_l、_mbsncat_s、_mbsncat_s_lstrncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l
strncmp、wcsncmp、_mbsncmp、_mbsncmp_lstrncmp, wcsncmp, _mbsncmp, _mbsncmp_l
strncpy_s、_strncpy_s_l、wcsncpy_s、_wcsncpy_s_l、_mbsncpy_s、_mbsncpy_s_lstrncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l
_strnicmp、_wcsnicmp、_mbsnicmp、_strnicmp_l、_wcsnicmp_l、_mbsnicmp_l_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l
strrchr、wcsrchr、_mbsrchr、_mbsrchr_lstrrchr, wcsrchr, _mbsrchr, _mbsrchr_l
strspn、wcsspn、_mbsspn、_mbsspn_lstrspn, wcsspn, _mbsspn, _mbsspn_l