复制字符串。 这些版本的 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 | 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!