strcpy_s， wcscpy_s， _mbscpy_s

项目
04/10/2013

将一个字符串。这些是 strcpy， wcscpy， _mbscpy 的版本与安全增强如 CRT中的安全功能所述。

重要

_mbscpy_s 不能在运行时的窗口执行的应用程序。有关更多信息，请参见 CRT 函数不支持与 /ZW。

errno_t strcpy_s(
   char *strDestination,
   size_t numberOfElements,
   const char *strSource 
);
errno_t wcscpy_s(
   wchar_t *strDestination,
   size_t numberOfElements,
   const wchar_t *strSource 
);
errno_t _mbscpy_s(
   unsigned char *strDestination,
   size_t numberOfElements,
   const unsigned char *strSource 
);
template <size_t size>
errno_t strcpy_s(
   char (&strDestination)[size],
   const char *strSource 
); // C++ only
template <size_t size>
errno_t wcscpy_s(
   wchar_t (&strDestination)[size],
   const wchar_t *strSource 
); // C++ only
template <size_t size>
errno_t _mbscpy_s(
   unsigned char (&strDestination)[size],
   const unsigned char *strSource 
); // C++ only

参数

strDestination
位置的位置字符串缓冲区
numberOfElements
目标字符串缓冲区的大小。
strSource
null 终止的源字符串缓冲区。

返回值

零，如果成功；否则为 false。

错误状态

strDestination	numberOfElements	strSource	返回值	strDestination内容
NULL	any	any	EINVAL	不修改
any	any	NULL	EINVAL	strDestination[0] 设置为 0
any	0 或太小	any	ERANGE	strDestination[0] 设置为 0

备注

strcpy_s 函数副本。strSource地址的内容，包括终止 null 字符)，以 strDestination指定的位置。目标字符串必须足以容纳源字符串，包括终止 null 字符)。如果源页和目标字符串重叠，strcpy_s 行为不确定。

wcscpy_s 和 _mbscpy_s 分别为 strcpy_s 的宽字符和多字节字符版本。参数和返回 wcscpy_s 的值是宽字符字符串；这些 _mbscpy_s 的多字节字符字符串。这三个功能否则具有相同的行为。

如果 strDestination 或 strSource 是 null 指针，或者，如果目标字符串过小；无效参数处理程序调用如参数验证所述。如果执行允许继续，这些函数返回 EINVAL 并将 errno 到 EINVAL。

在成功执行，目标字符串将始终为 null 终止。

在 C++ 中，使用这些功能由模板超加载简化；超加载可能推断缓冲区长度 (自动不再需要指定范围参数)，并且还可以用以较新，安全重复自动替换旧，不安全的功能。有关更多信息，请参见安全模板重载。

这些函数的" debug "版本使用 0xFE 首先加载缓冲区。若要禁用此行为，请使用 _CrtSetDebugFillThreshold。

一般文本例程映射

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>

有关其他的兼容性信息，请参见中介绍的兼容性。

示例

// crt_strcpy_s.cpp
// This program uses strcpy_s and strcat_s
// to build a phrase.
//

#include <string.h>
#include <stdlib.h>
#include <stdio.h>
#include <errno.h>

int main( void )
{
   char string[80];
   // using template versions of strcpy_s and strcat_s:
   strcpy_s( string, "Hello world from " );
   strcat_s( string, "strcpy_s " );
   strcat_s( string, "and " );
   // of course we can supply the size explicitly if we want to:
   strcat_s( string, _countof(string), "strcat_s!" );
   
   printf( "String = %s\n", string );
}