Upgrade your Internet Experience
Microsoft.com
Welcome Sign in
Visual C++ Developer Center
Click to Rate and Give Feedback
MSDN
MSDN Library
Visual Studio 2005
Visual Studio
Visual C++
Reference
Libraries Reference
Run-Time Library
 strncpy, _strncpy_l, wcsncpy, _wcsn...

  Switch on low bandwidth view
This page is specific to
Microsoft Visual Studio 2005/.NET Framework 2.0

Other versions are also available for the following:
Run-Time Library Reference 
strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l 

Copy characters of one string to another. These functions are deprecated because more secure versions are available; see strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l.

char *strncpy(
   char *strDest,
   const char *strSource,
   size_t count 
);
char *_strncpy_l(
   char *strDest,
   const char *strSource,
   size_t count,
   locale_t locale 
);
wchar_t *wcsncpy(
   wchar_t *strDest,
   const wchar_t *strSource,
   size_t count 
);
wchar_t *_wcsncpy_l(
   wchar_t *strDest,
   const wchar_t *strSource,
   size_t count,
   locale_t locale 
);
unsigned char *_mbsncpy(
   unsigned char *strDest,
   const unsigned char *strSource,
   size_t count 
);
unsigned char *_mbsncpy_l(
   unsigned char *strDest,
   const unsigned char *strSource,
   size_t count,
   _locale_t locale
);
template <size_t size>
char *strncpy(
   char (&strDest)[size],
   const char *strSource,
   size_t count 
); // C++ only
template <size_t size>
char *_strncpy_l(
   char (&strDest)[size],
   const char *strSource,
   size_t count,
   locale_t locale 
); // C++ only
template <size_t size>
wchar_t *wcsncpy(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count 
); // C++ only
template <size_t size>
wchar_t *_wcsncpy_l(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count,
   locale_t locale 
); // C++ only
template <size_t size>
unsigned char *_mbsncpy(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count 
); // C++ only
template <size_t size>
unsigned char *_mbsncpy_l(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count,
   _locale_t locale
); // C++ only

Parameters

strDest

Destination string.

strSource

Source string.

count

Number of characters to be copied.

locale

Locale to use.

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

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

If strDest or strSource is a NULL pointer, or if count is less than or equal to zero, the invalid parameter handler is invoked, as described in Parameter Validation. If execution is allowed to continue, these functions return -1 and set errno to EINVAL

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

The versions of these functions with the _l suffix are identical except that they use the locale passed in instead of the current locale for their locale-dependent behavior.

In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see Secure Template Overloads.

Generic-Text Routine Mappings
TCHAR.H routine _UNICODE & _MBCS not defined _MBCS defined _UNICODE defined

_tcsncpy

strncpy

_mbsnbcpy

wcsncpy

_tcsncpy_l

_strncpy_l

_mbsnbcpy_l

_wcsncpy_l

NoteNote

_strncpy_l and _wcsncpy_l have no locale dependence; they are provided just for _tcsncpy_l and are not intended to be called directly.

Routine Required header Compatibility

strncpy

<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

wcsncpy

<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

_mbsncpy, _mbsncpy_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_strncpy_x86.c
// compile with: /W1
// processor: x86
#include <stdio.h>
#include <string.h>

int main() {
   char a[20] = "test";
   char s[20];
   char *p = 0, *q = 0;

   strcpy_s( s, sizeof(s), "AA BB CC" );
   // Note: strncpy is deprecated; consider using strncpy_s instead
   strncpy( s, "aa", 2 );   // "aa BB CC"         C4996
   strncpy( s+3, "bb", 2 ); // "aa bb CC"         C4996
   strncpy( s, "ZZ", 3 );   // "ZZ",              C4996
                            // count greater than strSource, null added
   printf( "%s\n", s );

   strcpy_s( s, sizeof(s), "AA BB CC" );
   p = strstr(s, "BB");
   q = strstr(s, "CC");
   strncpy(s, "aa", p - s - 1);   // "aa BB CC"   C4996
   strncpy(p, "bb", q - p - 1);   // "aa bb CC"   C4996
   strncpy(q, "cc",  q - s);      // "aa bb cc"   C4996
   strncpy(q, "dd", strlen(q));   // "aa bb dd"   C4996
   printf( "%s\n", s );

   // some problems with strncpy
   strcpy_s( s, sizeof(s), "AA BB CC" );
   strncpy( s, "this is a very long string", 20 ); // C4996
   // Danger: at this point, s has no terminating null

   strcpy_s( s, sizeof(s), "dogs like cats" );
   strncpy( s+10, "to chase cars", 14);
   // strncpy has caused a buffer overrun and corrupted string a
   printf( "Buffer overrun: a = '%s' (should be 'test')\n", a );
   // In this case, a is just a char array, but if a were a function
   // pointer, this would be an exploitable buffer overrun.
}

Output

ZZ
aa bb dd
Buffer overrun: a = 'ars' (should be 'test')
// crt_strncpy_x64.c
// compile with: /W3
// processor: x64 IPF
#include <stdio.h>
#include <string.h>

int main() {
   char a[20];
   char s[20];
   char b[20] = "test";
   char *p = 0, *q = 0;

   strcpy_s( s, sizeof(s), "AA BB CC" );
   // Note: strncpy is deprecated; consider using strncpy_s instead
   strncpy( s, "aa", 2 );   // "aa BB CC"         C4996
   strncpy( s+3, "bb", 2 ); // "aa bb CC"         C4996
   strncpy( s, "ZZ", 3 );   // "ZZ",              C4996
                            // count greater than strSource, null added
   printf( "%s\n", s );

   strcpy_s( s, sizeof(s), "AA BB CC" );
   p = strstr(s, "BB");
   q = strstr(s, "CC");
   strncpy(s, "aa", p - s - 1);   // "aa BB CC"   C4996
   strncpy(p, "bb", q - p - 1);   // "aa bb CC"   C4996
   strncpy(q, "cc",  q - s);      // "aa bb cc"   C4996
   strncpy(q, "dd", strlen(q));   // "aa bb dd"   C4996
   printf( "%s\n", s );

   // some problems with strncpy
   strcpy_s( s, sizeof(s), "AA BB CC" );
   strncpy( s, "this is a very long string", 20 ); // C4996
   // Danger: at this point, s has no terminating null

   strcpy_s( s, sizeof(s), "dogs like cats" );
   strncpy( s+10, "to chase cars and buses and things", 36);
   // strncpy has caused a buffer overrun and corrupted string b
   printf( "Buffer overrun: b = '%s' (should be 'test')\n", b );
   // In this case, b is just a char array, but if b were a function
   // pointer, this would be an exploitable buffer overrun.
}

Output

ZZ
aa bb dd
Buffer overrun: b = 's and things' (should be 'test')
Tags What's this?: Add a tag
Community Content   What is Community Content?
Add new content RSS  Annotations
© 2009 Microsoft Corporation. All rights reserved. Terms of Use  |  Trademarks  |  Privacy Statement
Page view tracker