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, которые не поддерживаются с ключом /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

Параметры

[исходящий] strDest
Строка назначения, завершающаяся символом NULL.
[входящий]numberOfElements
Размер буфера назначения.
[входной]strSource
Исходная строка, завершающаяся символом NULL.
[входящий]count
Количество добавляемых знаков, или _TRUNCATE.
[входящий] locale
Языковой стандарт, который необходимо использовать.

Возвращаемое значение

Возвращает 0 при успехе; код ошибки при неудаче.

Условия возникновения ошибки

strDestination	numberOfElements	strSource	Возвращаемое значение	Содержимое strDestination.
NULL или без признака завершения	any	any	EINVAL	без изменений
any	any	NULL	EINVAL	без изменений
any	0 или слишком мало	any	ERANGE	без изменений

Заметки

Эти функции пытаются добавить первые D символов строки strSource в конец строки strDest, где D меньшее из величины count и длины strSource. Если эти добавляемые D символов поместятся внутри strDest (чей размер задается как numberOfElements), и по-прежнему останется место для завершающего нуль-символа, тогда эти символы добавляются, начиная с исходного нуль-символа strDest, и добавляется новый завершающий нуль-символ; в противном случае strDest[0] становится равным нуль-символу, и вызывается обработчик недопустимого параметра, как описано в разделе Проверка параметров.

Для вышеприведенного абзаца есть исключения. Если count равен _TRUNCATE, то в strDest добавляется столько символов из strSource, сколько поместится, что оставит место для добавления завершающего нуль-символа.

Например:

char dst[5];

strncpy_s(dst, _countof(dst), "12", 2);

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

это означает, что происходит попытка добавить с помощью strncat_s три символа к двум символам в буфере длиной в пять символов; это не оставит места для завершающего нуль-символа, поэтому strncat_s обнуляет строку и вызывает обработчик недопустимого параметра.

Если необходимо усечение, следует использовать _TRUNCATE или отрегулировать параметр size соответствующим образом:

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

или

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

Во всех случаях, результирующая строка завершается нуль-символом. Если копирование производится между перекрывающимися строками, поведение не определено.

Если параметр 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();
}