strcat_s, wcscat_s, _mbscat_s

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at strcat_s, wcscat_s, _mbscat_s.

Appends a string. These versions of strcat, wcscat, _mbscat have security enhancements, as described in Security Features in the CRT.

System_CAPS_ICON_important.jpg Important

_mbscat_s cannot be used in applications that execute in the Windows Runtime. For more information, see CRT functions not supported with /ZW.

errno_t strcat_s(  
   char *strDestination,  
   size_t numberOfElements,  
   const char *strSource   
);  
errno_t wcscat_s(  
   wchar_t *strDestination,  
   size_t numberOfElements,  
   const wchar_t *strSource   
);  
errno_t _mbscat_s(  
   unsigned char *strDestination,  
   size_t numberOfElements,  
   const unsigned char *strSource   
);  
template <size_t size>  
errno_t strcat_s(  
   char (&strDestination)[size],  
   const char *strSource   
); // C++ only  
template <size_t size>  
errno_t wcscat_s(  
   wchar_t (&strDestination)[size],  
   const wchar_t *strSource   
); // C++ only  
template <size_t size>  
errno_t _mbscat_s(  
   unsigned char (&strDestination)[size],  
   const unsigned char *strSource   
); // C++ only  

Parameters

strDestination
Null-terminated destination string buffer.

numberOfElements
Size of the destination string buffer.

strSource
Null-terminated source string buffer.

Zero if successful; an error code on failure.

Error Conditions

strDestinationnumberOfElementsstrSourceReturn valueContents of strDestination
NULL or unterminatedanyanyEINVALnot modified
anyanyNULLEINVALstrDestination[0] set to 0
any0, or too smallanyERANGEstrDestination[0] set to 0

The strcat_s function appends strSource to strDestination and terminates the resulting string with a null character. The initial character of strSource overwrites the terminating null character of strDestination. The behavior of strcat_s is undefined if the source and destination strings overlap.

Note that the second parameter is the total size of the buffer, not the remaining size:

char buf[16];  
strcpy_s(buf, 16, "Start");  
strcat_s(buf, 16, " End");               // Correct  
strcat_s(buf, 16 – strlen(buf), " End"); // Incorrect  

wcscat_s and _mbscat_s are wide-character and multibyte-character versions of strcat_s. The arguments and return value of wcscat_s are wide-character strings; those of _mbscat_s are multibyte-character strings. These three functions behave identically otherwise.

If strDestination is a null pointer, or is not null-terminated, or if 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.

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
_tcscat_sstrcat_s_mbscat_swcscat_s
RoutineRequired header
strcat_s<string.h>
wcscat_s<string.h> or <wchar.h>
_mbscat_s<mbstring.h>

For additional compatibility information, see Compatibility.

See the code example in strcpy_s, wcscpy_s, _mbscpy_s.

System::String::Concat

String Manipulation
strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l
strncmp, wcsncmp, _mbsncmp, _mbsncmp_l
strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l
_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l
strrchr, wcsrchr, _mbsrchr, _mbsrchr_l
strspn, wcsspn, _mbsspn, _mbsspn_l

Show: