strncpy、 _strncpy_l、 wcsncpy、 _wcsncpy_l、 _mbsncpy、 _mbsncpy_l

發行項
03/26/2013

一個字串的字元複製到另一個。更多這些函式的可用安全版本，請參閱 strncpy_s、 _strncpy_s_l、 wcsncpy_s、 _wcsncpy_s_l、 _mbsncpy_s、 _mbsncpy_s_l 。

重要

_mbsncpy 和 _mbsncpy_l 不能用於 Windows 執行階段執行的應用程式。如需詳細資訊，請參閱 CRT 函式不支援使用 /ZW。

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

參數

strDest
目的資料。
strSource
來源字串。
count
要複製的字元數。
locale
使用的地區設定。

傳回值

傳回 strDest。傳回值不會保留表示錯誤。

備註

strncpy 函式複製 strSource 初始 count 字元對 strDest 並傳回 strDest。如果 count 小於或等於 strSource的長度， null 字元不會自動附加至複製的字串。如果 count 大於 strSource的長度，目的資料填補 Null 字元長度 count。如果來源和目的資料重疊， strncpy 行為是未定義。

安全性提示
strncpy 不會檢查 strDest的足夠的空間;這讓它一個可能原因緩衝區滿溢。count 引數限制複製的字元數目;會在 strDest大小的一項限制。請參閱下列範例。如需詳細資訊，請參閱 Avoiding Buffer Overruns 。

如果 strDest 或 strSource 是 NULL 指標，或者，如果 count 小於或等於零，無效的參數叫用處理常式，如參數驗證中所述。如果執行允許繼續執行，這些函式傳回 -1 並將 errno 設為 EINVAL

wcsncpy 和 _mbsncpy 是 strncpy 的寬字元和多位元組字元版本。引數和傳回值 wcsncpy 和 _mbsncpy 跟著變更。這六個函式另有相同的行為。

這些函式版本與 _l 尾碼的相同，但為其地區設定相關行為使用地區設定來取代目前的地區設定。如需詳細資訊，請參閱地區設定。

在 C++ 中，這些函式有多載樣板可以調用更新、更安全的這些函式的相對版本。如需詳細資訊，請參閱安全範本多載。

泛用文字常式對應

TCHAR.H 常式	未定義 _UNICODE & _MBCS	已定義 _MBCS	已定義 _UNICODE
_tcsncpy	strncpy	_mbsnbcpy	wcsncpy
_tcsncpy_l	_strncpy_l	_mbsnbcpy_l	_wcsncpy_l

注意事項
_strncpy_l 和 _wcsncpy_l 沒有地區設定相關屬性;它們提供 _tcsncpy_l 並不適合直接呼叫。

需求

程序	必要的標頭檔
strncpy	<string.h>
wcsncpy	<string.h> 或 <wchar.h>
_mbsncpy, _mbsncpy_l	<mbstring.h>

如需其他平台相容性資訊，請參閱相容性。

範例

下列範例示範如何使用 strncpy ，以及它如何誤用造成程式 Bug 和安全性問題。編譯器會為每一個呼叫的警告對 strncpy 與 **crt_strncpy_x86.c(15) : warning C4996: 'strncpy': This function or variable may be unsafe. Consider using strncpy_s instead. To disable deprecation, use _CRT_SECURE_NO_WARNINGS. See online help for details.**相同。

// crt_strncpy_x86.c
// Use this command in an x86 developer command prompt to compile: 
// cl /TC /W3 crt_strncpy_x86.c

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

int main() {
   char t[20];
   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), "test");
   strncpy(t, "this is a very long string", 20 ); // C4996
   // Danger: at this point, t has no terminating null,
   // so the printf continues until it runs into one.
   // In this case, it will print "this is a very long test"
   printf("%s\n", t);

   strcpy_s(t, sizeof(t), "dogs like cats");
   printf("%s\n", t);

   strncpy(t + 10, "to chase cars.", 14); // C4996
   printf("%s\n", t);

   // strncpy has caused a buffer overrun and corrupted string s
   printf("Buffer overrun: s = '%s' (should be 'test')\n", s);
   // Since the stack grows from higher to lower addresses, buffer
   // overruns can corrupt function return addresses on the stack,
   // which can be exploited to run arbitrary code.
}

Output

自動變數和層級設定錯誤偵測和程式碼保護可能會變更編譯器設定變更。這個範例可能有不同的結果時，內建其他編輯環境或其他編譯器選項。