Locale-Sensitive Windows C++ Functions

LPTSTR StrCatBuff(LPTSTR pszDestination, LPCTSTR pszSource, int cchDestBuffSize);

LPSTR StrCatBuffA(LPSTR pszDestination, LPCSTR pszSource, int cchDestBuffSize);

LPWSTR StrCatBuffW(LPWSTR pszDestination, LPCWSTR pszSource, int cchDestBuffSize);

Internationalization (I18n) Function Overview

The StrCatBuff function concatenates pszSource onto the end of pszDestination, overwriting the null byte at the end of pszDestination. The pszSource and pszDestination arrays cannot overlap. cchDestBuffSize ensures that pszDestination will not be overrun; however, in the event that there is not space for all of pszSource, the null-terminating character will not be set. Therefore, the caller must ensure pszDestination points to a region of memory that is large enough to hold the concatenated result, including the null terminator.

StrCatBuffA is the narrow version of the function; its arguments and return are single-byte or multibyte strings, and cchDestBuffSize is a byte size.

StrCatBuffW is the wide version of the function; its arguments and return are wide-character strings, and cchDestBuffSize is a wide-character size.

I18n Issues

Use the appropriate version of the function as required for internationalization support, ensuring that cchDestBuffSize is set correctly for the chosen platform: bytes for the narrow version and WCHARs for the wide version. See Locale-Sensitive Length Functions for a discussion on multibyte and wide character sizes.

Recommended Replacements*

Due to the security risks of this function, consider using a safe string function.

If StrCatBuff is called, use the Generic version of the function rather than explicitly calling the narrow or wide versions. StrCatBuff will be mapped to StrCatBuffW when the program is compiled with the #define UNICODE switch, and to StrCatBuffA otherwise. Using the Generic version facilitates switching between an MBCS and UTF-16 Unicode application.

These are shown as the first choices in the following table:

Microsoft Windows MBCS	StringCchCat/StringCbCat or StrCatBuff or StrCatBuffA
Microsoft Windows Unicode	StringCchCat/StringCbCat or StrCatBuff or StrCatBuffW
Microsoft Windows Generic	StringCchCat/StringCbCat or StrCatBuff