strncat, wcsncat (Windows CE 5.0)

Article
09/14/2012

Developing an Application > Microsoft C Run-time Library for Windows CE > Run-time Library Reference

Append characters of a string.

char *strncat( char *strDest, const char *strSource, size_tcount);wchar_t *wcsncat( wchar_t *strDest, const wchar_t *strSource, size_tcount);

Parameters

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

Return Values

Each of these functions returns a pointer to the destination string. No return value is reserved to indicate an error.

Remarks

These functions are supported by all versions of the C run-time libraries.

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.

wcsncat is the wide-character version of strncat. The string arguments and return value of wcsncat are wide-character strings. These two functions behave identically otherwise.

The first argument, strDest, must be large enough to hold the current strDest and strSource combined and a closing NULL ('\0'); otherwise, a buffer overrun can occur.

This can lead to a denial of service attack against the application if an access violation occurs, or in the worst case, allow an attacker to inject executable code into your process. This is especially true if strDest is a stack-based buffer.

The last argument, count, is the number of bytes to copy into strDest, not the size of strDest.

strncat only adds a trailing NULL if there is room left in the buffer, strDest.

The following code example shows a safe way to use strncat:

void test(char *szWords1, char *szWords2) {
     char buf[BUFFER_SIZE];
      
     strncpy(buf,szWords1,sizeof buf - 1);
     buf[BUFFER_SIZE - 1] = '\0';                
     unsigned int cRemaining = (sizeof buf - strlen(buf)) - 1;
     strncat(buf,szWords2,cRemaining);
}

The following table shows generic-text routine mappings for this function.

TCHAR.H Routine	_UNICODE Defined
_tcsncat	wcsncat

For more information about TCHAR.H routines, see Generic Text Mappings.

Example

Description

The following example concatenates two strings.

Code

#include <string.h>
#include <stdio.h>

void main( void )
{
   char string[80] = "This is the initial string!";
   char suffix[] = " extra text to add to the string...";
   /* Combine strings with no more than 19 characters of suffix: */
   printf( "Before: %s\n", string );
   strncat( string, suffix, 19 );
   printf( "After:  %s\n", string );
}
// Output
Before: This is the initial string!
After:  This is the initial string! extra text to add

Requirements

OS Versions: Windows CE 2.0 and later.

Header: stdio.h, string.h.

Link Library: coredll.dll.

Share via