strncpy、_strncpy_l、wcsncpy、_wcsncpy_l、_mbsncpy、_mbsncpy_l

發行項
06/09/2015

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

重要

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

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

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