strncat, , _strncat_l_wcsncat_lwcsncat_mbsncat,_mbsncat_l

Добавляет символы строки. Доступны более безопасные версии этих функций; seestrncat_s, _strncat_s_l_mbsncat_s_lwcsncat_s_mbsncat_s_wcsncat_s_l.

Внимание

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

Синтаксис

char *strncat(
   char *strDest,
   const char *strSource,
   size_t count
);
wchar_t *wcsncat(
   wchar_t *strDest,
   const wchar_t *strSource,
   size_t count
);
unsigned char *_mbsncat(
   unsigned char *strDest,
   const unsigned char *strSource,
   size_t count
);
unsigned char *_mbsncat_l(
   unsigned char *strDest,
   const unsigned char *strSource,
   size_t count,
   _locale_t locale
);
template <size_t size>
char *strncat(
   char (&strDest)[size],
   const char *strSource,
   size_t count
); // C++ only
template <size_t size>
wchar_t *wcsncat(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count
); // C++ only
template <size_t size>
unsigned char *_mbsncat(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count
); // C++ only
template <size_t size>
unsigned char *_mbsncat_l(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count,
   _locale_t locale
); // C++ only

Параметры

strDest
Строка назначения, завершающаяся нуль-символом.

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

count
Количество символов для добавления.

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

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

Возвращает указатель на целевую строку символов. Нет зарезервированных возвращаемых значений для указания ошибки.

Замечания

Функция strncat в основном добавляет первые символы countstrSource в strDest. Начальный символ строки strSource переопределяет завершающий символ NULL строки strDest. Если нуль-символ встречается в строке strSource до того, как будет добавлено count символов, функция strncat добавляет все символы из строки strSource вплоть до нуль-символа. Если значение count больше длины строки strSource, вместо параметра strSource используется длина строки count. Во всех случаях результирующая строка завершается нуль-символом. Если копирование производится между перекрывающимися строками, поведение не определено.

Внимание

strncat не проверяет, достаточно ли места в строке strDest, в связи с чем может возникнуть ошибка переполнения буфера. Помните, что count ограничивает количество добавляемых символов, но не размер strDest. См. пример ниже. Дополнительные сведения см. в разделе "Избегание переполнения буфера".

Функции wcsncat и _mbsncat являются версиями функции strncat для расширенных и многобайтовых символов. Строковые аргументы и возвращаемое значение wcsncat являются строками с широкими символами. Строковые аргументы и возвращаемое значение _mbsncat являются многобайтовыми строками. В остальном эти три функции ведут себя идентично.

Выходное значение зависит от параметра LC_CTYPE категории языкового стандарта. Дополнительные сведения см. в разделе setlocale. Версии этих функций без _l суффикса используют текущий языковой стандарт для этого поведения, зависяющего от языкового стандарта. Версии с суффиксом _l идентичны, за исключением того, что они используют переданный параметр языкового стандарта. Дополнительные сведения см. в разделе Locale.

В C++ эти функции имеют шаблонные перегрузки. Дополнительные сведения см. в разделе "Безопасные перегрузки шаблонов".

По умолчанию глобальное состояние этой функции ограничивается приложением. Чтобы изменить это поведение, см . статью "Глобальное состояние" в CRT.

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

TCHAR.H Обычной	_UNICODE и _MBCS не определен	_MBCS Определенные	_UNICODE Определенные
_tcsncat	strncat	_mbsnbcat	wcsncat
_tcsncat_l	_strncat_l	_mbsnbcat_l	_wcsncat_l

Примечание.

Функции _strncat_l и _wcsncat_l не зависят от языкового стандарта и не предназначены для непосредственного вызова. Они предназначены для внутреннего использования _tcsncat_l.

Требования

Маршрут	Обязательный заголовок
strncat	<string.h>
wcsncat	<string.h> или <wchar.h>
_mbsncat	<mbstring.h>
_mbsncat_l	<mbstring.h>

Дополнительные сведения о совместимости см. в разделе Совместимость.

Пример

// crt_strncat.c
// Use strcat and strncat to append to a string.
#include <stdlib.h>

#define MAXSTRINGLEN 39

char string[MAXSTRINGLEN+1];
// or char *string = malloc(MAXSTRINGLEN+1);

void BadAppend( char suffix[], int n )
{
   strncat( string, suffix, n );
}

void GoodAppend( char suffix[], size_t n )
{
   strncat( string, suffix, __min( n, MAXSTRINGLEN-strlen(string)) );
}

int main( void )
{
   string[0] = '\0';
   printf( "string can hold up to %d characters\n", MAXSTRINGLEN );

   strcpy( string, "This is the initial string!" );
   // concatenate up to 20 characters...
   BadAppend( "Extra text to add to the string...", 20 );
   printf( "After BadAppend :  %s (%d chars)\n", string, strlen(string) );

   strcpy( string, "This is the initial string!" );
   // concatenate up to 20 characters...
   GoodAppend( "Extra text to add to the string...", 20 );
   printf( "After GoodAppend:  %s (%d chars)\n", string, strlen(string) );
}

Выходные данные

string can hold up to 39 characters
After BadAppend :  This is the initial string!Extra text to add to (47 chars)
After GoodAppend:  This is the initial string!Extra text t (39 chars)

Вы можете увидеть, что BadAppend вызвало переполнение буфера.

См. также

Обработка строк
_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
Локаль
Интерпретация последовательностей многобайтовых символов