strcat_s
, wcscat_s
, _mbscat_s
, _mbscat_s_l
Acrescenta uma cadeia de caracteres. Essas versões do , , _mbscat
têm aprimoramentos de segurança, wcscat
conforme descrito em Recursos de strcat
seguranç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
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de