strcpy_s, wcscpy_s, _mbscpy_s

Copies a string. These versions of strcpy, wcscpy, _mbscpy have security enhancements, as described in Security Features 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 the destination string buffer

  • numberOfElements
    Size of the destination string buffer.

  • strSource
    Null-terminated source string buffer.

Return Value

Zero if successful; otherwise, an error.

Error Conditions

strDestination

numberOfElements

strSource

Return value

Contents of strDestination

NULL

any

any

EINVAL

not modified

any

any

NULL

EINVAL

strDestination[0] set to 0

any

0, or too small

any

ERANGE

strDestination[0] set to 0

Remarks

The strcpy_s function copies the contents in the address of strSource—this includes the terminating null character—to the location that's specified by strDestination. The destination string must be large enough to hold the source string and its terminating null character. The behavior of strcpy_s is undefined if the source and destination strings overlap.

wcscpy_s is a wide-character version of strcpy_s and _mbscpy_s is a multibyte-character version. 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 when strDestination or strSource is a null pointer, and they return ERANGE and set errno to ERANGE when the destination string is too small.

Upon successful execution, the destination string is always null terminated.

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

The debug versions of these functions first fill the buffer with 0xFE. 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

strcpy_s

<string.h>

wcscpy_s

<string.h> or <wchar.h>

_mbscpy_s

<mbstring.h>

For additional compatibility information, see Compatibility.

Example

// 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 );
}
String = Hello world from strcpy_s and strcat_s!

.NET Framework Equivalent

System::String::Copy

See Also

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