strncat_s
, _strncat_s_l
, wcsncat_s
, _wcsncat_s_l
, _mbsncat_s
, _mbsncat_s_l
Присоединяет символы к строке. Эти версии strncat
, _strncat_l
, wcsncat
, _wcsncat_l
, _mbsncat
, имеют _mbsncat_l
улучшения безопасности, как описано в разделе Функции безопасности в 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 или без признака завершения |
any | any | EINVAL |
не изменено |
any | any | NULL |
EINVAL |
не изменено |
any | 0 или слишком мал | any | ERANGE |
не изменено |
Комментарии
Эти функции пытаются добавить первые D
символов строки strSource
в конец строки strDest
, где D
— это меньшее из величины count
и длины strSource
. Если добавление этих D
символов поместится в strDest
(размер которого присваивается как numberOfElements
) и по-прежнему оставляет место для конца null, эти символы добавляются, начиная с исходного завершающего значения NULL , и добавляется новое завершающее значение NULL; в противном случае strDest[0]
устанавливается символ NULL и вызывается обработчик недопустимого strDest
параметра, как описано в разделе Проверка параметров.
Существует исключение из приведенного выше абзаца. Если count
параметр имеет _TRUNCATE
значение , к добавляется strDest
столько значенийstrSource
, сколько подходит, при этом остается место для добавления завершающего значения 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
имеет значение NULL
, или numberOfElements
равно нулю, вызывается обработчик недопустимых параметров, как описано в разделе Проверка параметров . Если выполнение может быть продолжено, функция возвращает EINVAL
без изменения своих параметров.
Функцииwcsncat_s
и _mbsncat_s
are wide-character и multibyte-character versions of 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> |
Дополнительные сведения о совместимости см. в разделе Compatibility.
Пример
// 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
Обратная связь
https://aka.ms/ContentUserFeedback.
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделеОтправить и просмотреть отзыв по