strcat_s, wcscat_s, _mbscat_s

Статья
06/09/2015

Добавляет строку. В этих версиях strcat, wcscat, _mbscat усовершенствована безопасность, как описано в разделе Функции безопасности в CRT.

Важно!

_mbscat_s невозможно использовать в приложениях, запускаемых в среде выполнения Windows.Дополнительные сведения см. в статье Функции CRT, которые не поддерживаются с ключом /ZW.

errno_t strcat_s(
   char *strDestination,
   size_t numberOfElements,
   const char *strSource 
);
errno_t wcscat_s(
   wchar_t *strDestination,
   size_t numberOfElements,
   const wchar_t *strSource 
);
errno_t _mbscat_s(
   unsigned char *strDestination,
   size_t numberOfElements,
   const unsigned char *strSource 
);
template <size_t size>
errno_t strcat_s(
   char (&strDestination)[size],
   const char *strSource 
); // C++ only
template <size_t size>
errno_t wcscat_s(
   wchar_t (&strDestination)[size],
   const wchar_t *strSource 
); // C++ only
template <size_t size>
errno_t _mbscat_s(
   unsigned char (&strDestination)[size],
   const unsigned char *strSource 
); // C++ only

Параметры

strDestination
Буфер строки назначения с завершающим null.
numberOfElements
Размер буфера строки назначения.
strSource
Буфер строки источника с нулевым завершением.

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

Нуль, если успешно; код ошибки при неудаче.

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

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

Заметки

Функция strcat_s добавляет strSource к strDestination, а затем к результирующей строке завершающий символ null. Начальный символ strSource перезаписывает конечный символ null strDestination. При перекрытии исходной и конечной строк поведение инструкции strcat_s не определено.

Обратите внимание, что второй параметр содержит полный размер буфера, а не оставшийся свободным:

char buf[16];
strcpy_s(buf, 16, "Start");
strcat_s(buf, 16, " End");               // Correct
strcat_s(buf, 16 – strlen(buf), " End"); // Incorrect

wcscat_s и _mbscat_s являются версиями функции strcat_s для расширенных и многобайтовых символов. Аргументы и возвращаемое значение wcscat_s представляют собой двухбайтовые строки; аргументы и возвращаемое значение _mbscat_s представляют собой многобайтовые строки. В остальных случаях эти три функции ведут себя идентично.

Если strDestination является указателем на null или не содержит завершающего null, или если strSource является NULL указателем, или если строка назначения недостаточного размера, то вызывается обработчик недопустимого параметра, как описано в Проверка параметров. Если продолжение выполнения разрешено, эти функции возвращают EINVAL и устанавливают для errno значение EINVAL.

В C++ использование данных функций упрощено наличием шаблонных перегрузок; перегруженные методы могут автоматически определять длину буфера (что исключает необходимость указания аргумента с размером буфера), а также они могут автоматически заменять более старые, незащищенные функции их новыми безопасными аналогами. Дополнительные сведения см. в разделе Безопасные перегрузки шаблонов.

Отладочные версии этих функций сначала заполняют буфер значением 0xFD. Для отключения данного поведения используйте _CrtSetDebugFillThreshold.

Универсальное текстовое сопоставление функций