_mbsnbcat, _mbsnbcat_l

 

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 _mbsnbcat, _mbsnbcat_l.

Appends, at most, the first n bytes of one multibyte-character string to another. More secure versions of these functions are available; see _mbsnbcat_s, _mbsnbcat_s_l.

System_CAPS_ICON_important.jpg Important

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

unsigned char *_mbsnbcat(  
   unsigned char *dest,  
   const unsigned char *src,  
   size_t count   
);  
unsigned char *_mbsnbcat_l(  
   unsigned char *dest,  
   const unsigned char *src,  
   size_t count,  
   _locale_t locale  
);  
template <size_t size>  
unsigned char *_mbsnbcat(  
   unsigned char (&dest)[size],  
   const unsigned char *src,  
   size_t count   
); // C++ only  
template <size_t size>  
unsigned char *_mbsnbcat_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.

src
Null-terminated multibyte-character source string.

count
Number of bytes from src to append to dest.

locale
Locale to use.

_mbsnbcat returns a pointer to the destination string. No return value is reserved to indicate an error.

The _mbsnbcat function appends, at most, the first count bytes of src to dest. If the byte immediately preceding the null character in dest is a lead byte, the initial byte of src overwrites this lead byte. 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 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 with 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; see setlocale for more information. The _mbsnbcat version of the function uses the current locale for this locale-dependent behavior; the _mbsnbcat_l version is identical except that they use the locale parameter passed in instead. For more information, see Locale.

Security Note Use a null-terminated string. The null-terminated string must not exceed the size of the destination buffer. For more information, see Avoiding Buffer Overruns.

If dest or src is NULL, the function will generate an invalid parameter error, as described in Parameter Validation. If the error is handled, the function returns EINVAL and sets errno to EINVAL.

In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see Secure Template Overloads.

Generic-Text Routine Mappings

Tchar.h routine_UNICODE and _MBCS not defined_MBCS defined_UNICODE defined
_tcsncatstrncat_mbsnbcatwcsncat
_tcsncat_l_strncat_l_mbsnbcat_l_wcsncat_l
RoutineRequired header
_mbsnbcat<mbstring.h>
_mbsnbcat_l<mbstring.h>

For more compatibility information, see Compatibility.

Not applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.

String Manipulation
_mbsnbcmp, _mbsnbcmp_l
_strncnt, _wcsncnt, _mbsnbcnt, _mbsnbcnt_l, _mbsnccnt, _mbsnccnt_l
_mbsnbcpy, _mbsnbcpy_l
_mbsnbicmp, _mbsnbicmp_l
_mbsnbset, _mbsnbset_l
strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l
_mbsnbcat_s, _mbsnbcat_s_l

Show: