strncat_s、_strncat_s_l、wcsncat_s、_wcsncat_s_l、_mbsncat_s、_mbsncat_s_l

项目
06/09/2015

向字符串追加字符。 strncat、_strncat_l、wcsncat、_wcsncat_l、_mbsncat、_mbsncat_l 的这些版本如 CRT 中的安全功能所述，其安全得到了增强。

重要

_mbsncat_s 和 _mbsncat_s_l 不能在 Windows 运行时执行的应用程序中使用。有关详细信息，请参见 CRT functions not supported with /ZW（CRT 函数不支持使用/ZW）。

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

参数

[out] strDest
以NULL终止的目标字符串。
[in]numberOfElements
目标缓冲区的大小。
[in]strSource
null 终止的源字符串。
[in]count
要追加的字符数,或_TRUNCATE。
[in] locale
要使用的区域设置。

返回值

如果成功，则返回零；如果失败，则返回错误代码。

错误情况

strDestination	numberOfElements	strSource	返回值	strDestination 的内容
NULL 或未终止	any	any	EINVAL	未修改
any	any	NULL	EINVAL	未修改
any	0，或太小	any	ERANGE	未修改

备注

这些函数尝试追加 strSource 的第一 D 字符到strDest的末尾，D 是 count 的较小者和 strSource的长度。如果追加这些 D 字符将适应strDest的范围（大小由numberOfElements给出)，并且仍有 null 结束符的空间，则追加这些字符，在终止 null strDest的原始，并且新的终止 null 追加；否则，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 或相应地调整 size 参数：

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

或

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

任何情况下，结果字符串都以 null 字符终结。如果复制出现在重叠的字符串之间，则该行为不确定。

如果 strSource或 strDest为NULL，或者numberOfElements为零，则将调用无效参数处理程序，如参数验证所述。如果执行允许继续，该函数返回 EINVAL，而不修改其参数。

wcsncat_s 和 _mbsncat_s 是宽字符，属于 strncat_s 的多节字字符版本。字符串参数和 wcsncat_s 的返回值是宽字符串；_mbsncat_s 的参数和返回值为多字节字符串。否则这三个函数否则具有相同行为。

输出值受区域设置的 LC_CTYPE 类设置影响；有关更多信息，请参见 setlocale。这些不带 _l 后缀的函数的版本使用为该区域设置相关的行为的当前区域设置；带有 _l 后缀的版本相同，只不过它们使用传递的区域设置参数。有关详细信息，请参阅区域设置。

在 C++ 中，使用这些函数由模板重载简化；重载可以自动推导出缓冲区长度 (不再需要指定大小参数)，并且它们可以自动用以更新、更安全的对应物替换旧的、不安全的函数。有关详细信息，请参阅安全模板重载。

这些函数的调试版本首先用 0xFD 填充缓冲区。若要禁用此行为，请使用 _CrtSetDebugFillThreshold。

一般文本例程映射

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();
}