strcat_s, wcscat_s, _mbscat_s, _mbscat_s_l

Acrescenta uma cadeia de caracteres. Essas versões do , , _mbscattêm aprimoramentos de segurança, wcscatconforme descrito em Recursos de strcatsegurança na CRT.

Importante

_mbscat_s e _mbscat_s_l não podem ser usados em aplicativos executados no Windows Runtime. Para obter mais informações, confira Funções do CRT sem suporte em aplicativos da Plataforma Universal do Windows.

Sintaxe

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
);
errno_t _mbscat_s_l(
   unsigned char *strDestination,
   size_t numberOfElements,
   const unsigned char *strSource,
   _locale_t locale
);
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
template <size_t size>
errno_t _mbscat_s_l(
   unsigned char (&strDestination)[size],
   const unsigned char *strSource,
   _locale_t locale
); // C++ only

Parâmetros

strDestination
Buffer de cadeia de caracteres de destino terminada em nulo.

numberOfElements
Tamanho do buffer de cadeia de caracteres de destino.

strSource
Buffer de cadeia de caracteres de origem com terminação nula.

locale
Localidade a usar.

Retornar valor

Zero se for bem-sucedido; um código de erro em caso de falha.

Condições de erro

strDestination	numberOfElements	strSource	Retornar valor	Conteúdo de strDestination
NULL ou não finalizado	qualquer	qualquer	EINVAL	não modificado
qualquer	qualquer	NULL	EINVAL	strDestination[0] definido como 0
qualquer	0 ou muito pequeno	qualquer	ERANGE	strDestination[0] definido como 0

Comentários

A função strcat_s acrescenta strSource para strDestination e encerra a cadeia de caracteres resultante com um caractere nulo. O caractere inicial de strSource substitui o caractere nulo de terminação de strDestination. O comportamento de strcat_s é indefinido se as cadeias de origem e destino se sobrepõem.

O segundo parâmetro é o tamanho total do buffer, não o tamanho restante:

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

wcscat_s e _mbscat_s são versões de caracteres largos e de caracteres multibyte de strcat_s. Os argumentos e o valor de retorno de são cadeias de wcscat_s caracteres largos. Os argumentos e o valor de retorno de são cadeias de _mbscat_s caracteres multibyte. Caso contrário, essas três funções se comportam de forma idêntica.

Se strDestination for um ponteiro nulo, ou não for terminado em nulo, ou se for um NULL ponteiro, ou se strSource a cadeia de caracteres de destino for muito pequena, o manipulador de parâmetros inválido será chamado, conforme descrito em Validação de parâmetro. Se a execução puder continuar, essas funções retornarão EINVAL e definirão errno para EINVAL.

As versões das funções que têm o sufixo _l usam têm o mesmo comportamento, mas usam o parâmetro de localidade passado em vez da localidade atual. Para obter mais informações, consulte Localidade.

Em C++, o uso dessas funções é simplificado pelas sobrecargas de modelo; as sobrecargas podem inferir o tamanho do buffer automaticamente (eliminando a necessidade de especificar um argumento de tamanho) e podem substituir automaticamente funções mais antigas e não seguras por suas equivalentes mais recentes e seguras. Para obter mais informações, consulte Sobrecargas de modelo seguras.

As versões de biblioteca de depuração dessas funções preenchem o buffer com 0xFE. Para desabilitar esse comportamento, use _CrtSetDebugFillThreshold.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, consulte Estado global na CRT.

Mapeamentos de rotina de texto genérico

Rotina TCHAR.H	_UNICODE e _MBCS não definidos	_MBCS definido	_UNICODE definido
_tcscat_s	strcat_s	_mbscat_s	wcscat_s

Requisitos

Rotina	Cabeçalho necessário
strcat_s	<string.h>
wcscat_s	<string.h> ou <wchar.h>
_mbscat_s	<mbstring.h>

Para obter informações sobre compatibilidade, consulte Compatibilidade.

Exemplo

Confira o exemplo de código emstrcpy_s, wcscpy_s_mbscpy_s.

Confira também

Manipulação de cadeia de caracteres
strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l
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
strspn, wcsspn, _mbsspn, _mbsspn_l