strncat, _strncat_l, wcsncat, wcsncat_l, _mbsncat _mbsncat_l
Append characters of a string. More secure versions are available, see strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l .
char *strncat( char *strDest, const char *strSource, size_t count ); wchar_t *wcsncat( wchar_t *strDest, const wchar_t *strSource, size_t count ); unsigned char *_mbsncat( unsigned char *strDest, const unsigned char *strSource, size_t count ); unsigned char *_mbsncat_l( unsigned char *strDest, const unsigned char *strSource, size_t count, _locale_t locale ); template <size_t size> char *strncat( char (&strDest)[size], const char *strSource, size_t count ); // C++ only template <size_t size> wchar_t *wcsncat( wchar_t (&strDest)[size], const wchar_t *strSource, size_t count ); // C++ only template <size_t size> unsigned char *_mbsncat( unsigned char (&strDest)[size], const unsigned char *strSource, size_t count ); // C++ only template <size_t size> unsigned char *_mbsncat_l( unsigned char (&strDest)[size], const unsigned char *strSource, size_t count, _locale_t locale ); // C++ only
Parameters
- strDest
-
Null-terminated destination string.
- strSource
-
Null-terminated source string.
- count
-
Number of characters to append.
- locale
-
Locale to use.
The strncat function appends, at most, the first count characters of strSource to strDest. The initial character of strSource overwrites the terminating null character of strDest. If a null character appears in strSource before count characters are appended, strncat appends all characters from strSource, up to the null character. If count is greater than the length of strSource, the length of strSource is used in place of count. The all cases, the resulting string is terminated with a null character. If copying takes place between strings that overlap, the behavior is undefined.
 Security Note |
|---|
| strncat does not check for sufficient space in strDest; it is therefore a potential cause of buffer overruns. Keep in mind that count limits the number of characters appended; it is not a limit on the size of strDest. See the example below. For more information, see Avoiding Buffer Overruns. |
wcsncat and _mbsncat are wide-character and multibyte-character versions of strncat. The string arguments and return value of wcsncat are wide-character strings; those of _mbsncat are multibyte-character strings. These three functions behave identically otherwise.
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++, these functions have template overloads. For more information, see Secure Template Overloads.
| TCHAR.H routine | _UNICODE & _MBCS not defined | _MBCS defined | _UNICODE defined |
|---|---|---|---|
| _tcsncat | strncat | _mbsnbcat | wcsncat |
| _tcsncat_l | _strncat_l | _mbsnbcat_l | _wcsncat_l |
| Note |
|---|
| _strncat_l and _wcsncat_l have no locale dependence and are not meant to be called directly. They are provided for internal use by _tcsncat_l. |
| Routine | Required header | Compatibility |
|---|---|---|
| strncat | <string.h> | ANSI, 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 |
| wcsncat | <string.h> or <wchar.h> | ANSI, 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 |
| _mbsncat | <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 |
| _mbsncat_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 additional compatibility information, see Compatibility in the Introduction.
// crt_strncat.c
// Use strcat and strncat to append to a string.
#include <stdlib.h>
#define MAXSTRINGLEN 39
char string[MAXSTRINGLEN+1];
// or char *string = malloc(MAXSTRINGLEN+1);
void BadAppend( char suffix[], int n )
{
strncat( string, suffix, n );
}
void GoodAppend( char suffix[], size_t n )
{
strncat( string, suffix, __min( n, MAXSTRINGLEN-strlen(string)) );
}
int main( void )
{
string[0] = '\0';
printf( "string can hold up to %d characters\n", MAXSTRINGLEN );
strcpy( string, "This is the initial string!" );
// concatenate up to 20 characters...
BadAppend( "Extra text to add to the string...", 20 );
printf( "After BadAppend : %s (%d chars)\n", string, strlen(string) );
strcpy( string, "This is the initial string!" );
// concatenate up to 20 characters...
GoodAppend( "Extra text to add to the string...", 20 );
printf( "After GoodAppend: %s (%d chars)\n", string, strlen(string) );
}
Reference
String Manipulation (CRT)_mbsnbcat, _mbsnbcat_l
strcat, wcscat, _mbscat
strcmp, wcscmp, _mbscmp
strcpy, wcscpy, _mbscpy
strncmp, wcsncmp, _mbsncmp, _mbsncmp_l
strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l
_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l
strrchr, wcsrchr, _mbsrchr, _mbsrchr_l
_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l
strspn, wcsspn, _mbsspn, _mbsspn_l
Locale
Interpretation of Multibyte-Character Sequences
