strcat, strcat_s

Определено в заголовочном файле `<string.h>`
char* strcat( char* dest, const char* src );	(1)	(до C99)
char* strcat( char* restrict dest, const char* restrict src );	(1)		(начиная с C99)
errno_t strcat_s(char* restrict dest, rsize_t destsz, const char* restrict src);	(2)	(начиная с C11)

1) Добавляет копию строки байтов с завершающим нулевым символом, на которую указывает src, в конец строки байтов с завершающим нулевым символом, на которую указывает dest. Символ src[0] заменяет нулевой терминатор в конце dest. Полученная строка байтов завершается нулевым символом.

Поведение не определено, если массив назначения недостаточно велик для содержимого обеих строк src и dest и завершающего нулевого символа. Поведение не определено, если строки перекрываются. Поведение не определено, если dest или src не является указателем на строку байтов с завершающим нулевым символом.

2) То же, что и (1), за исключением того, что функция может изменить остальную часть массива назначения (от последнего записанного символа до destsz), присвоив ей неопределённые значения, а также во время выполнения обнаруживаются следующие ошибки и вызывается текущий установленный обработчик нарушений ограничений:

src или dest является нулевым указателем
destsz равно нулю или превышает RSIZE_MAX
в первых destsz байтах dest нет нулевого терминатора
произошло бы усечение (доступного места в конце dest не хватило бы для записи всех символов src, включая нулевой терминатор)
исходная и целевая строки перекрываются

Поведение не определено, если размер массива символов, на который указывает dest, меньше strlen(dest)+strlen(src)+1 и меньше либо равен destsz; иными словами, ошибочное значение destsz не позволяет обнаружить надвигающееся переполнение буфера.

Как и все функции с проверкой границ, strcat_s гарантированно доступна только в том случае, если реализация определяет __STDC_LIB_EXT1__, а пользователь определяет __STDC_WANT_LIB_EXT1__ целочисленной константой 1 до включения <string.h>.

Параметры

dest	-	указатель на строку байтов с завершающим нулевым символом, в которую нужно добавить данные
src	-	указатель на строку байтов с завершающим нулевым символом, из которой нужно скопировать данные
destsz	-	максимальное число символов для записи, обычно размер буфера назначения

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

1) возвращает копию dest

2) при успешном выполнении возвращает ноль, при ошибке — ненулевое значение. Кроме того, при ошибке записывает ноль в dest[0] (если только dest не является нулевым указателем или destsz не равно нулю или не превышает RSIZE_MAX).

Примечания

Поскольку при каждом вызове strcat необходимо находить конец dest, объединять множество строк в одну с помощью strcat неэффективно.

Для повышения эффективности strcat_s может изменять массив назначения от последнего записанного символа до destsz: функция может копировать данные блоками, а затем проверять наличие нулевых байтов.

Функция strcat_s похожа на функцию BSD strlcat, но

strlcat усекает исходную строку, чтобы она поместилась в строку назначения
strlcat не выполняет все проверки во время выполнения, которые выполняет strcat_s
strlcat не делает ошибки очевидными, записывая нулевую строку в строку назначения или вызывая обработчик в случае сбоя.

Хотя strcat_s запрещает усечение из-за связанных с ним потенциальных рисков безопасности, строку можно усечь с помощью strncat_s с проверкой границ.

Пример

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

int main(void)
{
    char str[50] = "Hello ";
    char str2[50] = "World!";
    strcat(str, str2);
    strcat(str, " ...");
    strcat(str, " Goodbye World!");
    puts(str);

#ifdef __STDC_LIB_EXT1__
    set_constraint_handler_s(ignore_handler_s);
    int r = strcat_s(str, sizeof str, " ... ");
    printf("str = \"%s\", r = %d\n", str, r);
    r = strcat_s(str, sizeof str, " and this is too much");
    printf("str = \"%s\", r = %d\n", str, r);
#endif
}

Возможный вывод:

Hello World! ... Goodbye World!
str = "Hello World! ... Goodbye World! ... ", r = 0
str = "", r = 22

Ссылки

Стандарт C23 (ISO/IEC 9899:2024):

7.24.3.1 Функция strcat (с. TBD)
K.3.7.2.1 Функция strcat_s (с. TBD)

Стандарт C17 (ISO/IEC 9899:2018):

7.24.3.1 Функция strcat (с. TBD)
K.3.7.2.1 Функция strcat_s (с. TBD)

Стандарт C11 (ISO/IEC 9899:2011):

7.24.3.1 Функция strcat (с. 364)
K.3.7.2.1 Функция strcat_s (с. 617-618)

Стандарт C99 (ISO/IEC 9899:1999):

7.21.3.1 Функция strcat (с. 327)

Стандарт C89/C90 (ISO/IEC 9899:1990):

4.11.3.1 Функция strcat

См. также

strncatstrncat_s (C11)	объединяет заданное количество символов двух строк (функция)
strcpystrcpy_s (C11)	копирует одну строку в другую (функция)
memccpy (C23)	копирует один буфер в другой, останавливаясь после указанного разделителя (функция)
Документация по C++ для `strcat`

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/c/string/byte/strcat