_mbsnbcat_s, _mbsnbcat_s_l

Appends to a multibyte character string, at most, the first n bytes of another multibyte-character string. These functions are versions of _mbsnbcat, _mbsnbcat_l that have security enhancements, as described in Security features in the CRT.

Important

This API cannot be used in applications that execute in the Windows Runtime. For more information, see CRT functions not supported in Universal Windows Platform apps.

Syntax

errno_t _mbsnbcat_s(
   unsigned char *dest,
   size_t sizeInBytes,
   const unsigned char *src,
   size_t count
);
errno_t _mbsnbcat_s_l(
   unsigned char *dest,
   size_t sizeInBytes,
   const unsigned char *src,
   size_t count,
   _locale_t locale
);
template <size_t size>
errno_t _mbsnbcat_s(
   unsigned char (&dest)[size],
   const unsigned char *src,
   size_t count
); // C++ only
template <size_t size>
errno_t _mbsnbcat_s_l(
   unsigned char (&dest)[size],
   const unsigned char *src,
   size_t count,
   _locale_t locale
); // C++ only

Parameters

dest
Null-terminated multibyte-character destination string.

sizeInBytes
Size of the dest buffer in bytes.

src
Null-terminated multibyte-character source string.

count
Number of bytes from src to append to dest.

locale
Locale to use.

Return value

Zero if successful; otherwise, an error code.

Error conditions

dest	sizeInBytes	src	Return value
NULL	any	any	EINVAL
Any	<= 0	any	EINVAL
Any	any	NULL	EINVAL

If any of the error conditions occurs, the function generates an invalid parameter error, as described in Parameter validation. If the error is handled, the function returns EINVAL and sets errno to EINVAL.

Remarks

The _mbsnbcat_s function appends to dest, at most, the first count bytes of src. If the byte that immediately precedes the null character in dest is a lead byte, it's overwritten by the initial byte of src. Otherwise, the initial byte of src overwrites the terminating null character of dest. If a null byte appears in src before count bytes are appended, _mbsnbcat_s appends all bytes from src, up to the null character. If count is greater than the length of src, the length of src is used in place of count. The resulting string is terminated by a null character. If copying takes place between strings that overlap, the behavior is undefined.

The output value is affected by the setting of the LC_CTYPE category setting of the locale. For more information, see setlocale. The versions of these functions are identical, except that the ones that don't have the _l suffix use the current locale and the ones that do have the _l suffix instead use the locale parameter that's passed in. For more information, see Locale.

In C++, the use of these functions is simplified by template overloads. The overloads can infer buffer length automatically, which eliminates the need to specify a size argument, and they can automatically use the newer, more secure functions to replace older, less-secure functions. For more information, see Secure template overloads.

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

By default, this function's global state is scoped to the application. To change this behavior, see Global state in the CRT.

Generic-text routine mappings

Tchar.h routine	_UNICODE and _MBCS not defined	_MBCS defined	_UNICODE defined
_tcsncat_s	strncat_s	_mbsnbcat_s	wcsncat_s
_tcsncat_s_l	_strncat_s_l	_mbsnbcat_s_l	_wcsncat_s_l

Requirements

Routine	Required header
_mbsnbcat_s	<mbstring.h>
_mbsnbcat_s_l	<mbstring.h>

For more compatibility information, see Compatibility.

See also

String manipulation
_mbsnbcmp, _mbsnbcmp_l
_strncnt, _wcsncnt, _mbsnbcnt, _mbsnbcnt_l, _mbsnccnt, _mbsnccnt_l
_mbsnbcpy, _mbsnbcpy_l
_mbsnbcpy_s, _mbsnbcpy_s_l
_mbsnbset, _mbsnbset_l
strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l
strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l