`strncat_s`, , `_strncat_s_l_wcsncat_s_lwcsncat_s_mbsncat_s`,`_mbsncat_s_l`

Статья
08/03/2024

Присоединяет символы к строке. Эти версии , , _strncat_l, _mbsncat_lwcsncat_wcsncat_l_mbsncat имеют улучшения безопасности, как описано в функциях strncatбезопасности в CRT.

Внимание

Функции _mbsncat_s и _mbsncat_s_l не могут использоваться в приложениях, запускаемых в среде выполнения Windows. Дополнительные сведения: Функции CRT, которые не поддерживаются в приложениях универсальной платформы Windows.

Синтаксис

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
Строка назначения, завершающаяся нуль-символом.

numberOfElements
Размер буфера назначения.

strSource
Исходная строка, завершающаяся символом NULL.

count
Число символов для добавления или _TRUNCATE.

locale
Используемый языковой стандарт.

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

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

Условия ошибок

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

Замечания

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

Существует исключение из приведенного выше абзаца. Если 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);

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

Если strSource значение strDest NULLnumberOfElements равно нулю или равно нулю, вызывается обработчик недопустимых параметров, как описано в разделе проверки параметров. Если выполнение может быть продолжено, функция возвращает 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_lwcsncpy_mbsncpy,_mbsncpy_l
_strnicmp, , _wcsnicmp_strnicmp_l_mbsnicmp_wcsnicmp_l,_mbsnicmp_l
strrchr, , wcsrchr_mbsrchr_mbsrchr_l
_strset, , _strset_l_wcsset_l_wcsset_mbsset,_mbsset_l
strspn, , wcsspn_mbsspn_mbsspn_l

Поделиться через

`strncat_s`, , `_strncat_s_l_wcsncat_s_lwcsncat_s_mbsncat_s`,`_mbsncat_s_l`

Синтаксис

Параметры

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

Условия ошибок

Замечания

Сопоставления подпрограмм универсального текста

Требования

Пример

См. также

Обратная связь

Дополнительные ресурсы

Поделиться через

strncat_s, , _strncat_s_l_wcsncat_s_lwcsncat_s_mbsncat_s,_mbsncat_s_l

Синтаксис

Параметры

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

Условия ошибок

Замечания

Сопоставления подпрограмм универсального текста

Требования

Пример

См. также

Обратная связь

Дополнительные ресурсы

`strncat_s`, , `_strncat_s_l_wcsncat_s_lwcsncat_s_mbsncat_s`,`_mbsncat_s_l`