strcpy_s, wcscpy_s, _mbscpy

Run-Time Library Reference

strcpy_s, wcscpy_s, _mbscpy_s

Copy a string. These are versions of strcpy, wcscpy, _mbscpy with security enhancements as described in Security Enhancements in the CRT.

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

Parameters

strDestination: Location of destination string buffer

numberOfElements: Size of the destination string buffer.

strSource: Null-terminated source string buffer.

Return Value

Zero if successful; an error otherwise.

Error Conditions

strDestination	numberOfElements	strSource	Return value	Contents of strDestination
NULL	any	any	EINVAL	not modified
any	any	NULL	EINVAL	not modified
any	0, or too small	any	ERANGE	not modified

Remarks

The strcpy_s function copies the contents in the address of strSource, including the terminating null character, to the location specified by strDestination. The destination string must be large enough to hold the source string, including the terminating null character. The behavior of strcpy_s is undefined if the source and destination strings overlap.

wcscpy_s and _mbscpy_s are wide-character and multibyte-character versions of strcpy_s respectively. The arguments and return value of wcscpy_s are wide character strings; those of _mbscpy_s are multibyte character strings. These three functions behave identically otherwise.

If strDestination or strSource is a null pointer, or if the destination string is too small, the invalid parameter handler is invoked as described in Parameter Validation. If execution is allowed to continue, these functions return EINVAL and set errno to EINVAL.

Upon successful execution, the destination string will always be null terminated.

In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see Secure Template Overloads.

The debug versions of these functions first fill the buffer with 0xFD. To disable this behavior, use _CrtSetDebugFillThreshold.

Generic-Text Routine Mappings

TCHAR.H routine	_UNICODE & _MBCS not defined	_MBCS defined	_UNICODE defined
_tcscpy_s	strcpy_s	_mbscpy_s	wcscpy_s

Requirements

Routine	Required header	Compatibility
strcpy_s	<string.h>	Windows 95, Windows 98, Windows 98 Second Edition, Windows Millennium Edition, Windows NT 4.0, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003
wcscpy_s	<string.h> or <wchar.h>	Windows 95, Windows 98, Windows 98 Second Edition, Windows Millennium Edition, Windows NT 4.0, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003
_mbscpy_s	<mbstring.h>	Windows 95, Windows 98, Windows 98 Second Edition, Windows Millennium Edition, Windows NT 4.0, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003

For additional compatibility information, see Compatibility in the Introduction.

Example

// crt_strcpy_s.cpp
// This program uses strcpy_s and strcat_s
// and strcat 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 );
}

Output

String = Hello world from strcpy_s and strcat_s!

.NET Framework Equivalent

System::String::Copy

Reference

String Manipulation (CRT)
strcat, wcscat, _mbscat
strcmp, wcscmp, _mbscmp
strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l
strncmp, wcsncmp, _mbsncmp, _mbsncmp_l
strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l
_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l
strrchr, wcsrchr, _mbsrchr, _mbsrchr_l
strspn, wcsspn, _mbsspn, _mbsspn_l