strcpy, strcpy_s

 

C

编译器支持

语言

头文件

类型支持

程序工具

可变参数函数支持

错误处理

动态内存管理

字符串库

算法

数值

日期和时间实用程序

输入/输出支持

本地化支持

并发支持 (C11)

技术规范

符号索引

 

字符串库

字节字符串

多字节字符串

宽字符串

 

以空字符结尾的字节字符串

函数
字符操作
isalnum isalpha islower isupper isdigit isxdigit isblank (C99)	iscntrl isgraph isspace isprint ispunct tolower toupper
转换为和从数字格式转换
atoiatolatoll (C99) atof strtolstrtoll (C99) strtoulstrtoull (C99)	strtoimaxstrtoumax (C99)(C99) strtofstrtodstrtold (C99)(C99) strfromfstrfromdstrfroml (C23)(C23)(C23)
字符串操作
strcpystrcpy_s (C11) strncpystrncpy_s (C11) strcatstrcat_s (C11)	strncatstrncat_s (C11) strxfrm strdup (C23) strndup (C23)
字符串检查
strlenstrnlen_s (C11) strcmp strncmp strcoll strchr strrchr	strspn strcspn strpbrk strstr strtokstrtok_s (C11)
内存操作
memchr memcmp memsetmemset_explicitmemset_s (C23)(C11)	memcpymemcpy_s (C11) memmovememmove_s (C11) memccpy (C23)
杂项
strerrorstrerror_sstrerrorlen_s (C11)(C11)

 

定义在头文件 <string.h> 中
	(1)
char *strcpy( char *dest, const char *src );			(直到 C99)
char *strcpy( char *restrict dest, const char *restrict src );			(自 C99)
errno_t strcpy_s( char *restrict dest, rsize_t destsz, const char *restrict src );		(2)	(自 C11)

1) 将 src 指向的以空字符结尾的字节字符串（包括空字符）复制到 dest 指向的第一个元素的字符数组中。

如果 dest 数组不足够大，则行为未定义。如果字符串重叠，则行为未定义。如果 dest 不是指向字符数组的指针，或者 src 不是指向以空字符结尾的字节字符串的指针，则行为未定义。

2) 与 (1) 相同，除了它可能会用未指定的值覆盖目标数组的其余部分，并且在运行时会检测到以下错误并调用当前安装的 约束处理程序 函数

• src 或 dest 是空指针
• destsz 为零或大于 RSIZE_MAX
• destsz 小于或等于 strnlen_s(src, destsz)；换句话说，将发生截断
• 源字符串和目标字符串之间会发生重叠

如果 dest 指向的字符数组的大小 <= strnlen_s(src, destsz) < destsz，则行为未定义；换句话说，destsz 的错误值不会暴露即将发生的缓冲区溢出。

与所有边界检查函数一样，只有在实现定义了 __STDC_LIB_EXT1__ 并且用户在包含 <string.h> 之前将 __STDC_WANT_LIB_EXT1__ 定义为整数常量 1 时，才保证 strcpy_s 可用。

参数

dest	-	指向要写入的字符数组的指针
src	-	指向要复制的以空字符结尾的字节字符串的指针
destsz	-	要写入的最大字符数，通常是目标缓冲区的大小

返回值

1) 返回 dest 的副本

2) 成功时返回零，错误时返回非零。此外，在发生错误时，会将零写入 dest[0]（除非 dest 是空指针，或者 destsz 为零或大于 RSIZE_MAX）。

注释

strcpy_s 允许覆盖从最后一个写入的字符到 destsz 的目标数组，以提高效率：它可以以多字节块进行复制，然后检查空字节。

函数 strcpy_s 类似于 BSD 函数 strlcpy，除了

• strlcpy 会截断源字符串以适应目标（这存在安全风险）
• strlcpy 不会执行 strcpy_s 进行的所有运行时检查
• strlcpy 不会通过将目标设置为空字符串或在调用失败时调用处理程序来使失败显而易见。

虽然 strcpy_s 禁止截断以避免潜在的安全风险，但可以使用边界检查的 strncpy_s 来截断字符串。

示例

运行此代码

#define __STDC_WANT_LIB_EXT1__ 1
#include <string.h>
#include <stdio.h>
#include <stdlib.h>
 
int main(void)
{
    const char *src = "Take the test.";
//  src[0] = 'M' ; // this would be undefined behavior
    char dst[strlen(src) + 1]; // +1 to accommodate for the null terminator
    strcpy(dst, src);
    dst[0] = 'M'; // OK
    printf("src = %s\ndst = %s\n", src, dst);
 
#ifdef __STDC_LIB_EXT1__
    set_constraint_handler_s(ignore_handler_s);
    int r = strcpy_s(dst, sizeof dst, src);
    printf("dst = \"%s\", r = %d\n", dst, r);
    r = strcpy_s(dst, sizeof dst, "Take even more tests.");
    printf("dst = \"%s\", r = %d\n", dst, r);
#endif
}

可能的输出

src = Take the test.
dst = Make the test.
dst = "Take the test.", r = 0
dst = "", r = 22

参考文献

• C17 标准（ISO/IEC 9899:2018）

• 7.24.2.3 strcpy 函数 (p: 264-265)

• K.3.7.1.3 strcpy_s 函数 (p: 447)

• C11 标准（ISO/IEC 9899:2011）

• 7.24.2.3 strcpy 函数 (p: 363)

• K.3.7.1.3 strcpy_s 函数 (p: 615-616)

• C99 标准（ISO/IEC 9899:1999）

• 7.21.2.3 strcpy 函数 (p: 326)

• C89/C90 标准（ISO/IEC 9899:1990）

• 4.11.2.3 strcpy 函数

另请参阅

strncpystrncpy_s (C11)	将一定数量的字符从一个字符串复制到另一个字符串 (函数)
memcpymemcpy_s (C11)	将一个缓冲区复制到另一个缓冲区 (函数)
wcscpywcscpy_s (C95)(C11)	将一个宽字符串复制到另一个宽字符串 (函数)
strdup (动态内存 TR)	分配字符串的副本 (函数)
C++ 文档 for strcpy