strcpy, strcpy_s

From cppreference.com

Compiler support
Language
Headers
Type support
Program utilities
Variadic function support
Error handling
Dynamic memory management
Strings library
Algorithms
Numerics
Date and time utilities
Input/output support
Localization support
Concurrency support(C11)
Technical Specifications
Symbol index

[edit]

Strings library

Null-terminated byte strings
Null-terminated multibyte strings
Null-terminated wide strings

[edit]

Null-terminated byte strings

Functions

Character manipulation

isalnum
isalpha
islower
isupper
isdigit
isxdigit
isblank (C99)

iscntrl
isgraph
isspace
isprint
ispunct
tolower
toupper

Conversions to and from numeric formats

atoiatolatoll (C99)
atof
strtolstrtoll (C99)
strtoulstrtoull (C99)

strtoimaxstrtoumax (C99)(C99)
strtofstrtodstrtold (C99)(C99)
strfromfstrfromdstrfroml (C23)(C23)(C23)

String manipulation

strcpystrcpy_s (C11)
strncpystrncpy_s (C11)
strcatstrcat_s (C11)

strncatstrncat_s (C11)
strxfrm
strdup (C23)
strndup (C23)

String examination

strlenstrnlen_s (C11)
strcmp
strncmp
strcoll
strchr
strrchr

strspn
strcspn
strpbrk
strstr
strtokstrtok_s (C11)

Memory manipulation

memchr
memcmp
memsetmemset_explicitmemset_s (C23)(C11)

memcpymemcpy_s (C11)
memmovememmove_s (C11)
memccpy (C23)

Miscellaneous

strerrorstrerror_sstrerrorlen_s

(C11)(C11)

[edit]

Defined in header`<string.h>`
	(1)
char* strcpy(char* dest,constchar* src);			(until C99)
char* strcpy(charrestrict dest,constcharrestrict src);			(since C99)
errno_t strcpy_s(charrestrict dest, rsize_t destsz,constcharrestrict src);		(2)	(since C11)

1) Copies the null-terminated byte string pointed to bysrc, including the null terminator, to the character array whose first element is pointed to bydest.

The behavior is undefined if thedest array is not large enough. The behavior is undefined if the strings overlap. The behavior is undefined if eitherdest is not a pointer to a character array orsrc is not a pointer to a null-terminated byte string.

2) Same as(1), except that it may clobber the rest of the destination array with unspecified values and that the following errors are detected at runtime and call the currently installedconstraint handler function:

src ordest is a null pointer
destsz is zero or greater thanRSIZE_MAX
destsz is less or equalstrnlen_s(src, destsz); in other words, truncation would occur
overlap would occur between the source and the destination strings

The behavior is undefined if the size of the character array pointed to bydest<=strnlen_s(src, destsz)<destsz; in other words, an erroneous value ofdestsz may permit buffer overflow.

As with all bounds-checked functions,strcpy_s is only guaranteed to be available if__STDC_LIB_EXT1__ is defined by the implementation and if the user defines__STDC_WANT_LIB_EXT1__ to the integer constant1 before including<string.h>.

[edit]Parameters

dest	-	pointer to the character array to write to
src	-	pointer to the null-terminated byte string to copy from
destsz	-	maximum number of characters to write, typically the size of the destination buffer

[edit]Return value

1) returns a copy ofdest

2) returns zero on success, returns non-zero on error. Also, on error, writes zero todest[0] (unlessdest is a null pointer ordestsz is zero or greater thanRSIZE_MAX).

[edit]Notes

strcpy_s is allowed to clobber the destination array from the last character written up todestsz in order to improve efficiency: it may copy in multibyte blocks and then check for null bytes.

The functionstrcpy_s is similar to the BSD functionstrlcpy, except that

strlcpy truncates the source string to fit in the destination (which is a security risk)
strlcpy does not perform all the runtime checks thatstrcpy_s does
strlcpy does not make failures obvious by setting the destination to a null string or calling a handler if the call fails.

Althoughstrcpy_s prohibits truncation due to potential security risks, it's possible to truncate a string using bounds-checkedstrncpy_s instead.

[edit]Example

Run this code

#define __STDC_WANT_LIB_EXT1__ 1#include <stdio.h>#include <stdlib.h>#include <string.h> int main(void){constchar* src="Take the test.";//  src[0] = 'M' ; // this would be undefined behaviorchar dst[strlen(src)+1];// +1 to accommodate for the null terminator    strcpy(dst, src);    dst[0]='M';// OKprintf("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}

Possible output:

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

[edit]References

C23 standard (ISO/IEC 9899:2024):

7.24.2.3 The strcpy function (p: TBD)

K.3.7.1.3 The strcpy_s function (p: TBD)

C17 standard (ISO/IEC 9899:2018):

7.24.2.3 The strcpy function (p: 264-265)

K.3.7.1.3 The strcpy_s function (p: 447)

C11 standard (ISO/IEC 9899:2011):

7.24.2.3 The strcpy function (p: 363)

K.3.7.1.3 The strcpy_s function (p: 615-616)

C99 standard (ISO/IEC 9899:1999):

7.21.2.3 The strcpy function (p: 326)

C89/C90 standard (ISO/IEC 9899:1990):

4.11.2.3 The strcpy function

[edit]See also

strncpystrncpy_s (C11)	copies a certain amount of characters from one string to another (function)[edit]
memcpymemcpy_s (C11)	copies one buffer to another (function)[edit]
wcscpywcscpy_s (C95)(C11)	copies one wide string to another (function)[edit]
strdup (dynamic memory TR)	allocate a copy of a string (function)[edit]
C++ documentation forstrcpy