This documentation is archived and is not being maintained.

strncpy, wcsncpy, _mbsncpy

Copy characters of one string to another.

char *strncpy(
   char *strDest,
   const char *strSource,
   size_t count 
);
wchar_t *wcsncpy(
   wchar_t *strDest,
   const wchar_t *strSource,
   size_t count 
);
unsigned char *_mbsncpy(
   unsigned char *strDest,
   const unsigned char *strSource,
   size_t count 
);

Parameters

strDest
Destination string.
strSource
Source string.
count
Number of characters to be copied.

Return Value

Returns strDest. No return value is reserved to indicate an error.

Remarks

The strncpy function copies the initial count characters of strSource to strDest and returns strDest. If count is less than or equal to the length of strSource, a null character is not appended automatically to the copied string. If count is greater than the length of strSource, the destination string is padded with null characters up to length count. The behavior of strncpy is undefined if the source and destination strings overlap.

Security Note   strncpy 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 copied; it is not a limit on the size of strDest. See the example below. For more information, see Avoiding Buffer Overruns.

wcsncpy and _mbsncpy are wide-character and multibyte-character versions of strncpy. The arguments and return value of wcsncpy and _mbsncpy vary accordingly. These three functions behave identically otherwise.

Generic-Text Routine Mappings

TCHAR.H routine _UNICODE & _MBCS not defined _MBCS defined _UNICODE defined
_tcsncpy strncpy _mbsnbcpy wcsncpy

Requirements

Routine Required header Compatibility
strncpy <string.h> ANSI, Win 98, Win Me, Win NT, Win 2000, Win XP
wcsncpy <string.h> or <wchar.h> ANSI, Win 98, Win Me, Win NT, Win 2000, Win XP
_mbsncpy <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_strncpy.c

#include <stdio.h>

int main( void )
{
   char a[20] = "test";
   char s[20];

   // simple strncpy usage:

   strcpy( s, "dogs like cats" );
   printf( "Original string:\n   '%s'\n", s );
   strncpy( s, "mice", 4 );
   printf( "After strncpy (no null-termination):\n   '%s'\n", s );
   strncpy( s+5, "love", 4 );
   printf( "After strncpy into middle of string:\n   '%s'\n", s );
   strncpy( s, "mice", 5 );
   printf( "After strncpy (with null-termination):\n   '%s'\n", s );

   // some problems with strncpy:

   strcpy( s, "dogs like cats" );
   strncpy( s, "this is a very long string", 20 ); // Danger:
      // at this point, a does not have a terminating null

   strcpy( s, "dogs like cats" );
   strncpy( s+10, "to chase cars", 14 ); // Danger:
      // strncpy has caused a buffer overrun and corrupted string a:
   printf( "Buffer overrun: a = '%s' (should be 'test')\n", a);
}

Output

Original string:
   'dogs like cats'
After strncpy (no null-termination):
   'mice like cats'
After strncpy into middle of string:
   'mice love cats'
After strncpy (with null-termination):
   'mice'
Buffer overrun: a = 'ars' (should be 'test')

See Also

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

Show: