_mbsnbcat_s, _mbsnbcat_s_l
Appends, at most, the first n bytes of one multibyte-character string to another. These are versions of _mbsnbcat, _mbsnbcat_l with security enhancements as described in Security Enhancements in the CRT.
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.
Zero if successful; an error code otherwise.
| Dest | sizeInBytes | src | Return value |
|---|---|---|---|
| NULL | any | any | EINVAL |
| Any | <= 0 | any | EINVAL |
| Any | any | NULL | EINVAL |
If any of the above 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.
The _mbsnbcat_s 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_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 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 versions of these functions without the _l suffix use the current locale for this locale-dependent behavior; the versions with the _l suffix are identical except that they use the locale parameter passed in instead.
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.
| Routine | Required header | Compatibility |
|---|---|---|
| _mbsnbcat_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 |
| _mbsnbcat_s_l | <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 more compatibility information, see Compatibility in the Introduction.
Not applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
Reference
String Manipulation (CRT)_mbsnbcmp, _mbsnbcmp_l
_mbsnbcnt, _mbsnbcnt_l, _mbsnccnt, _mbsnccnt_l, _strncnt, _wcsncnt
_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
