Export (0) Print
Expand All
Expand Minimize

strncat, wcsncat, _mbsncat

Append characters of a string.

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
);

Parameters

strDest
Null-terminated destination string.
strSource
Null-terminated source string.
count
Number of characters to append.

Return Value

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

Remarks

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 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.

Generic-Text Routine Mappings

TCHAR.H routine _UNICODE & _MBCS not defined _MBCS defined _UNICODE defined
_tcsncat strncat _mbsnbcat wcsncat

Requirements

Routine Required header Compatibility
strncat <string.h> ANSI, Win 98, Win Me, Win NT, Win 2000, Win XP
wcsncat <string.h> or <wchar.h> ANSI, Win 98, Win Me, Win NT, Win 2000, Win XP
_mbsncat <mbstring.h> Win 98, Win Me, Win NT, Win 2000, Win XP

For additional compatibility information, see Compatibility in the Introduction.

Libraries

All versions of the C run-time libraries.

Example

// crt_strncat.c

#include <stdlib.h>

#define MAXSTRINGLEN(s) ( sizeof(s)/sizeof(s[0]) - 1 )

char string[40];

void BadAppend( char suffix[], int n )
{
   strncat( string, suffix, n );
}

void GoodAppend( char suffix[], int n )
{
   strncat( string, suffix, __min( n, MAXSTRINGLEN(string)-strlen(string)) );
}

int main( void )
{
   printf( "string can hold up to %d characters\n", MAXSTRINGLEN(string) );

   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) );
}

Output

string can hold up to 39 characters
After BadAppend :  This is the initial string!Extra text to add to (47 chars)
After GoodAppend:  This is the initial string!Extra text t (39 chars)

Note that BadAppend caused a buffer overrun.

See Also

String Manipulation Routines | _mbsnbcat | strcat | strcmp | strcpy | strncmp | strncpy | _strnicmp | strrchr | _strset | strspn | Run-Time Routines and .NET Framework Equivalents

Show:
© 2014 Microsoft