共用方式為


strncpy_s_strncpy_s_lwcsncpy_s_wcsncpy_s_l_mbsncpy_s_mbsncpy_s_l_tcsncpy_s、、_tcsncpy_s_l、、 _tcsnccpy_s_tcsnccpy_s_l

將某個字串的字元複製到另一個字串。 這些版本的、 、 、 wcsncpy_mbsncpy_wcsncpy_l具有_mbsncpy_l安全性增強功能,如 CRT 的安全性功能中所述_strncpy_lstrncpy

重要

在 Windows 執行階段中執行的應用程式中無法使用 _mbsncpy_s_mbsncpy_s_l。 如需詳細資訊,請參閱 CRT functions not supported in Universal Windows Platform apps (通用 Windows 平台應用程式中不支援的 CRT 函式)。

針對 _tcsnccpy_s_tcsnccpy_s_l_tcsnccpy_s_tcsnccpy_s_l ,請參閱 泛型文字函式對應。

語法

errno_t strncpy_s(
   char *strDest,
   size_t numberOfElements,
   const char *strSource,
   size_t count
);
errno_t _strncpy_s_l(
   char *strDest,
   size_t numberOfElements,
   const char *strSource,
   size_t count,
   _locale_t locale
);
errno_t wcsncpy_s(
   wchar_t *strDest,
   size_t numberOfElements,
   const wchar_t *strSource,
   size_t count
);
errno_t _wcsncpy_s_l(
   wchar_t *strDest,
   size_t numberOfElements,
   const wchar_t *strSource,
   size_t count,
   _locale_t locale
);
errno_t _mbsncpy_s(
   unsigned char *strDest,
   size_t numberOfElements,
   const unsigned char *strSource,
   size_t count
);
errno_t _mbsncpy_s_l(
   unsigned char *strDest,
   size_t numberOfElements,
   const unsigned char *strSource,
   size_t count,
   _locale_t locale
);
template <size_t size>
errno_t strncpy_s(
   char (&strDest)[size],
   const char *strSource,
   size_t count
); // C++ only
template <size_t size>
errno_t _strncpy_s_l(
   char (&strDest)[size],
   const char *strSource,
   size_t count,
   _locale_t locale
); // C++ only
template <size_t size>
errno_t wcsncpy_s(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count
); // C++ only
template <size_t size>
errno_t _wcsncpy_s_l(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count,
   _locale_t locale
); // C++ only
template <size_t size>
errno_t _mbsncpy_s(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count
); // C++ only
template <size_t size>
errno_t _mbsncpy_s_l(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count,
   _locale_t locale
); // C++ only

參數

strDest
目的字串。

numberOfElements
目的地字串的大小 (以字元計)。

strSource
來源字串。

count
要複製的字元數,或 _TRUNCATE

locale
要使用的地區設定。

傳回值

如果成功則為零,如果發生截斷則為 STRUNCATE,否則為錯誤碼。

錯誤條件

strDest numberOfElements strSource 傳回值 strDest 的內容。
NULL 任意 任意 EINVAL 未修改
任意 任意 NULL EINVAL strDest[0] 設定為 0
任意 0 任意 EINVAL 未修改
NULL 太小 任意 ERANGE strDest[0] 設定為 0

備註

這些函式嘗試將 strSource 的前 D 個字元附加到 strDest 結尾,其中 D 是較小的 count 且長度為 strSource。 如果這些D字元會容納在 strDest 內(其大小指定為 numberOfElements),但仍保留 null 終止符的空間,則會複製這些字元,並附加終止 Null;否則,strDest[0]會設定為 Null 字元,並叫用無效的參數處理程式,如參數驗證中所述

上述段落有例外狀況。 如果 count_TRUNCATE,則會複製符合 的 strSource 和一樣 strDest 多,同時仍保留終止 Null 的空間,這一律會附加。

例如,

char dst[5];
strncpy_s(dst, 5, "a long string", 5);

表示 strncpy_s 將五個字元複製到5位元節緩衝區。 此複本不會保留 Null 終止符的空間,因此 strncpy_s 會清除字串,並呼叫無效的參數處理程式。

如果需要截斷行為,請使用 _TRUNCATE 或 (size - 1):

strncpy_s(dst, 5, "a long string", _TRUNCATE);
strncpy_s(dst, 5, "a long string", 4);

與 不同的 strncpy是,如果 count 大於 的 strSource長度,則目的字串不會以長度為 的 countNull 字元填補。

如果來源和目的字串重疊,則 strncpy_s 的行為未定義。

如果 strDeststrSourceNULL,或 numberOfElements 為 0,則會叫用無效的參數處理常式。 如果允許繼續執行,函式會傳回 EINVAL,並將 errno 設為 EINVAL

wcsncpy_s_mbsncpy_s 分別是 strncpy_s 的寬字元版本和多位元組字元版本。 和的wcsncpy_smbsncpy_s自變數和傳回值會因此而有所不同。 除此之外,這六個函式的行為相同。

輸出值會受到設定地區設定之 LC_CTYPE 類別設定的影響。 如需詳細資訊,請參閱setlocale。 這些沒有 _l 後置字元的函式版本,會針對此與地區設定相關的行為使用目前的地區設定;具有 _l 後置字元的版本也一樣,只不過它們會改用傳遞的地區設定參數。 如需詳細資訊,請參閱 Locale

C++ 利用多載樣板簡化了這些函式的使用方式。多載可自動推斷緩衝區長度 (因而不須指定大小引數),也可以將不安全的舊函式自動取代成較新且安全的對應函式。 如需詳細資訊,請參閱安全範本多載

這些函式的偵錯連結庫版本會先將緩衝區填入0xFE。 若要停用此行為,請使用 _CrtSetDebugFillThreshold

根據預設,此函式的全域狀態會限定於應用程式。 若要變更此行為,請參閱 CRT 中的全域狀態

泛型文字函式對應

數據行中的 tchar.h 函式會根據編譯時期定義的字元集,對應至其他數據行中的函式。

tchar.h 常式 _UNICODE_MBCS 未定義 _MBCS 已定義 _UNICODE 已定義
_tcsncpy_s strncpy_s _mbsnbcpy_s wcsncpy_s
_tcsncpy_s_l _strncpy_s_l _mbsnbcpy_s_l _wcsncpy_s_l
_tcsnccpy_s strncpy_s _mbsncpy_s _wcsncpy_s
_tcsnccpy_s_l _strncpy_s_l _mbsncpy_s_l _wcsncpy_s_l

注意

_strncpy_s_l_mbsncpy_s_l_wcsncpy_s_l 沒有地區設定相依性。 它們只提供給 _tcsncpy_s_l ,且不適合直接呼叫。

需求

常式 必要的標頭
strncpy_s, _strncpy_s_l <string.h>
wcsncpy_s, _wcsncpy_s_l <string.h><wchar.h>
_mbsncpy_s, _mbsncpy_s_l <mbstring.h>

如需相容性詳細資訊,請參閱相容性

範例:將字元複製到緩衝區

// crt_strncpy_s_1.cpp
// compile with: /MTd

// these #defines enable secure template overloads
// (see last part of Examples() below)
#define _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES 1
#define _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT 1

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <crtdbg.h>  // For _CrtSetReportMode
#include <errno.h>

// This example uses a 10-byte destination buffer.

errno_t strncpy_s_tester( const char * src,
                          int count )
{
   char dest[10];

   printf( "\n" );

   if ( count == _TRUNCATE )
      printf( "Copying '%s' to %d-byte buffer dest with truncation semantics\n",
               src, _countof(dest) );
   else
      printf( "Copying %d chars of '%s' to %d-byte buffer dest\n",
              count, src, _countof(dest) );

   errno_t err = strncpy_s( dest, _countof(dest), src, count );

   printf( "    new contents of dest: '%s'\n", dest );

   return err;
}

void Examples()
{
   strncpy_s_tester( "howdy", 4 );
   strncpy_s_tester( "howdy", 5 );
   strncpy_s_tester( "howdy", 6 );

   printf( "\nDestination buffer too small:\n" );
   strncpy_s_tester( "Hi there!!", 10 );

   printf( "\nTruncation examples:\n" );

   errno_t err = strncpy_s_tester( "How do you do?", _TRUNCATE );
   printf( "    truncation %s occur\n", err == STRUNCATE ? "did"
                                                       : "did not" );

   err = strncpy_s_tester( "Howdy.", _TRUNCATE );
   printf( "    truncation %s occur\n", err == STRUNCATE ? "did"
                                                       : "did not" );

   printf( "\nSecure template overload example:\n" );

   char dest[10];
   strncpy( dest, "very very very long", 15 );
   // With secure template overloads enabled (see #defines at
   // top of file), the preceding line is replaced by
   //    strncpy_s( dest, _countof(dest), "very very very long", 15 );
   // Instead of causing a buffer overrun, strncpy_s invokes
   // the invalid parameter handler.
   // If secure template overloads were disabled, strncpy would
   // copy 15 characters and overrun the dest buffer.
   printf( "    new contents of dest: '%s'\n", dest );
}

void myInvalidParameterHandler(
   const wchar_t* expression,
   const wchar_t* function,
   const wchar_t* file,
   unsigned int line,
   uintptr_t pReserved)
{
   wprintf(L"Invalid parameter handler invoked: %s\n", expression);
}

int main( void )
{
   _invalid_parameter_handler oldHandler, newHandler;

   newHandler = myInvalidParameterHandler;
   oldHandler = _set_invalid_parameter_handler(newHandler);
   // Disable the message box for assertions.
   _CrtSetReportMode(_CRT_ASSERT, 0);

   Examples();
}
Copying 4 chars of 'howdy' to 10-byte buffer dest
    new contents of dest: 'howd'

Copying 5 chars of 'howdy' to 10-byte buffer dest
    new contents of dest: 'howdy'

Copying 6 chars of 'howdy' to 10-byte buffer dest
    new contents of dest: 'howdy'

Destination buffer too small:

Copying 10 chars of 'Hi there!!' to 10-byte buffer dest
Invalid parameter handler invoked: (L"Buffer is too small" && 0)
    new contents of dest: ''

Truncation examples:

Copying 'How do you do?' to 10-byte buffer dest with truncation semantics
    new contents of dest: 'How do yo'
    truncation did occur

Copying 'Howdy.' to 10-byte buffer dest with truncation semantics
    new contents of dest: 'Howdy.'
    truncation did not occur

Secure template overload example:
Invalid parameter handler invoked: (L"Buffer is too small" && 0)
    new contents of dest: ''

範例: strncpystrncpy_s

// crt_strncpy_s_2.c
// contrasts strncpy and strncpy_s

#include <stdio.h>
#include <stdlib.h>

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

   // simple strncpy usage:

   strcpy_s( s, 20, "dogs like cats" );
   printf( "Original string:\n   '%s'\n", s );

   // Here we can't use strncpy_s since we don't
   // want null termination
   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 );

   // If we use strncpy_s, the string is terminated
   strncpy_s( s, _countof(s), "mice", 4 );
   printf( "After strncpy_s (with null-termination):\n   '%s'\n", s );

}
Original string:
   'dogs like cats'
After strncpy (no null-termination):
   'mice like cats'
After strncpy into middle of string:
   'mice love cats'
After strncpy_s (with null-termination):
   'mice'

另請參閱

字串操作
地區設定
多位元組字元序列的解譯
_mbsnbcpy, _mbsnbcpy_l
strcat_s、 、 wcscat_s_mbscat_s
strcmp、 、 wcscmp_mbscmp
strcpy_s、 、 wcscpy_s_mbscpy_s
strncat_s、、_strncat_s_lwcsncat_s_wcsncat_s_l、、_mbsncat_s_mbsncat_s_l
strncmp、 、 wcsncmp_mbsncmp_mbsncmp_l
_strnicmp、、_wcsnicmp_mbsnicmp_strnicmp_l、、_wcsnicmp_l_mbsnicmp_l
strrchr、 、 wcsrchr_mbsrchr_mbsrchr_l
_strset、、_strset_l_wcsset_wcsset_l、、_mbsset_mbsset_l
strspn、 、 wcsspn_mbsspn_mbsspn_l