`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`

發行項
10/12/2023

將字元附加至字串。這些版本的 strncat 、 _strncat_l 、 wcsncat 、 _wcsncat_l 、 _mbsncat 具有 _mbsncat_l 安全性增強功能，如 CRT 的安全性功能中所述。

重要

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

語法

errno_t strncat_s(
   char *strDest,
   size_t numberOfElements,
   const char *strSource,
   size_t count
);
errno_t _strncat_s_l(
   char *strDest,
   size_t numberOfElements,
   const char *strSource,
   size_t count,
   _locale_t locale
);
errno_t wcsncat_s(
   wchar_t *strDest,
   size_t numberOfElements,
   const wchar_t *strSource,
   size_t count
);
errno_t _wcsncat_s_l(
   wchar_t *strDest,
   size_t numberOfElements,
   const wchar_t *strSource,
   size_t count,
   _locale_t locale
);
errno_t _mbsncat_s(
   unsigned char *strDest,
   size_t numberOfElements,
   const unsigned char *strSource,
   size_t count
);
errno_t _mbsncat_s_l(
   unsigned char *strDest,
   size_t numberOfElements,
   const unsigned char *strSource,
   size_t count,
   _locale_t locale
);
template <size_t size>
errno_t strncat_s(
   char (&strDest)[size],
   const char *strSource,
   size_t count
); // C++ only
template <size_t size>
errno_t _strncat_s_l(
   char (&strDest)[size],
   const char *strSource,
   size_t count,
   _locale_t locale
); // C++ only
template <size_t size>
errno_t wcsncat_s(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count
); // C++ only
template <size_t size>
errno_t _wcsncat_s_l(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count,
   _locale_t locale
); // C++ only
template <size_t size>
errno_t _mbsncat_s(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count
); // C++ only
template <size_t size>
errno_t _mbsncat_s_l(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count,
   _locale_t locale
); // C++ only

參數

strDest
以 Null 終止的目的地字串。

numberOfElements
目的緩衝區大小。

strSource
以 Null 結束的來源字串。

count
要附加的字元數，或 _TRUNCATE 。

locale
要使用的地區設定。

傳回值

如果成功，則傳回 0，如果失敗，則為錯誤碼。

錯誤條件

`strDestination`	`numberOfElements`	`strSource`	傳回值	`strDestination` 的內容。
`NULL` 或未終止的	任意	任意	`EINVAL`	未修改
任意	任意	`NULL`	`EINVAL`	未修改
任意	0 或太小	任意	`ERANGE`	未修改

備註

這些函式嘗試將 strSource 的前 D 個字元附加到 strDest 結尾，其中 D 是較小的 count 且長度為 strSource。如果附加這些 D 字元會符合 strDest （其大小指定為 numberOfElements ），但仍保留 null 結束字元的空間，則會附加這些字元，從原始的終止 Null 開始，並附加新的終止 Null strDest ;否則， strDest[0] 會設定為 null 字元，並叫用不正確參數處理常式，如參數驗證中所述。

上述段落有例外狀況。如果 count 為 _TRUNCATE ，則會將符合的數量 strSource 附加至， strDest 同時仍保留空間以附加終止 Null。

例如，

char dst[5];
strncpy_s(dst, _countof(dst), "12", 2);
strncat_s(dst, _countof(dst), "34567", 3);

表示我們要求 strncat_s 將三個字元附加至緩衝區長度為五個字元的兩個字元;它不會保留 Null 結束字元的空格，因此 strncat_s 會清除字串，並呼叫不正確參數處理常式。

如果需要截斷行為，請使用 _TRUNCATE 或據以調整 count 參數︰

strncat_s(dst, _countof(dst), "34567", _TRUNCATE);

或

strncat_s(dst, _countof(dst), "34567", _countof(dst)-strlen(dst)-1);

在所有案例中，產生的字串都終止於 Null 字元。如果在重疊的字串之間執行複製，則行為是未定義的。

如果 strSource 或 strDest 為，或 numberOfElements 為 NULL 零，則會叫用不正確參數處理常式，如參數驗證中所述。如果允許繼續執行，函式會傳回 EINVAL 但不修改其參數。

wcsncat_s 和 _mbsncat_s 分別是 strncat_s 的寬字元版本和多位元組字元版本。的字串引數和傳回值 wcsncat_s 是寬字元字串。的引數和傳回值 _mbsncat_s 是多位元組字元字串。除此之外，這三個函式的行為相同。

輸出值會受到 LC_CTYPE 地區設定之類別設定的影響。如需詳細資訊，請參閱setlocale。沒有 _l 尾碼的這些函式版本會針對此地區設定相依行為使用目前的地區設定;具有 _l 尾碼的版本完全相同，不同之處在于它們會改用傳入的地區設定參數。如需詳細資訊，請參閱 Locale。

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

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

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

泛型文字常式對應

TCHAR.H 常式	`_UNICODE` 和 `_MBCS` 未定義	`_MBCS` 定義	`_UNICODE` 定義
`_tcsncat_s`	`strncat_s`	`_mbsnbcat_s`	`wcsncat_s`
`_tcsncat_s_l`	`_strncat_s_l`	`_mbsnbcat_s_l`	`_wcsncat_s_l`

_strncat_s_l 和 _wcsncat_s_l 沒有地區設定相依性;它們只會針對 _tcsncat_s_l 提供。

需求

常式	必要的標頭
`strncat_s`	<string.h>
`wcsncat_s`	<string.h > 或 < wchar.h>
`_mbsncat_s`, `_mbsncat_s_l`	<mbstring.h>

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

範例

// crt_strncat_s.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 strncat_s_tester( const char * initialDest,
                          const char * src,
                          int count )
{
   char dest[10];
   strcpy_s( dest, _countof(dest), initialDest );

   printf_s( "\n" );

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

   printf_s( "    old contents of dest: '%s'\n", dest );

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

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

   return err;
}

void Examples()
{
   strncat_s_tester( "hi ", "there", 4 );
   strncat_s_tester( "hi ", "there", 5 );
   strncat_s_tester( "hi ", "there", 6 );

   printf_s( "\nDestination buffer too small:\n" );
   strncat_s_tester( "hello ", "there", 4 );

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

   errno_t err = strncat_s_tester( "hello ", "there", _TRUNCATE );
   printf_s( "    truncation %s occur\n", err == STRUNCATE ? "did"
                                                       : "did not" );

   err = strncat_s_tester( "hello ", "!", _TRUNCATE );
   printf_s( "    truncation %s occur\n", err == STRUNCATE ? "did"
                                                       : "did not" );

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

   char dest[10] = "cats and ";
   strncat( dest, "dachshunds", 15 );
   // With secure template overloads enabled (see #define
   // at top of file), the preceding line is replaced by
   //    strncat_s( dest, _countof(dest), "dachshunds", 15 );
   // Instead of causing a buffer overrun, strncat_s invokes
   // the invalid parameter handler.
   // If secure template overloads were disabled, strncat would
   // append "dachshunds" and overrun the dest buffer.
   printf_s( "    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_s(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();
}

Appending 4 chars of 'there' to 10-byte buffer dest
    old contents of dest: 'hi '
    new contents of dest: 'hi ther'

Appending 5 chars of 'there' to 10-byte buffer dest
    old contents of dest: 'hi '
    new contents of dest: 'hi there'

Appending 6 chars of 'there' to 10-byte buffer dest
    old contents of dest: 'hi '
    new contents of dest: 'hi there'

Destination buffer too small:

Appending 4 chars of 'there' to 10-byte buffer dest
    old contents of dest: 'hello '
Invalid parameter handler invoked: (L"Buffer is too small" && 0)
    new contents of dest: ''

Truncation examples:

Appending 'there' to 10-byte buffer dest with truncation semantics
    old contents of dest: 'hello '
    new contents of dest: 'hello the'
    truncation did occur

Appending '!' to 10-byte buffer dest with truncation semantics
    old contents of dest: 'hello '
    new contents of dest: 'hello !'
    truncation did not occur

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

另請參閱

字串操作
 地區設定
 多位元組字元序列的解譯
 _mbsnbcat, _mbsnbcat_l
strcat, wcscat, _mbscat
strcmp, wcscmp, _mbscmp
strcpy, wcscpy, _mbscpy
strncmp, wcsncmp, _mbsncmp, _mbsncmp_l
strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_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

Share via

`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`

語法

參數

傳回值

錯誤條件

備註

泛型文字常式對應

需求

範例

另請參閱

意見反應

意見反應

其他資源

Share via

strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l

語法

參數

傳回值

錯誤條件

備註

泛型文字常式對應

需求

範例

另請參閱

意見反應

意見反應

其他資源

`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`