Export (0) Print
Expand All
div
eof
Expand Minimize
6 out of 15 rated this helpful - Rate this topic

strcat_s, wcscat_s, _mbscat_s 

Append a string. These are versions of strcat, wcscat, _mbscat with security enhancements as described in Security Enhancements in the CRT.


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
strDestination numberOfElements strSource Return value Contents of strDestination

NULL or unterminated

any

any

EINVAL

not modified

any

any

NULL

EINVAL

not modified

any

0, or too small

any

ERANGE

not modified

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_s

strcat_s

_mbscat_s

wcscat_s

Routine Required header Compatibility

strcat_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

wcscat_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

_mbscat_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.

See the code example in strcpy_s, wcscpy_s, _mbscpy_s.

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.