strcat_s, wcscat_s, _mbscat_s

Artigo
06/09/2015

Acrescenta uma cadeia de caracteres. Essas versões de strcat, wcscat, _mbscat têm aprimoramentos de segurança, como descrito em Recursos de segurança no CRT.

Importante

_mbscat_s não pode ser usado em aplicativos executados em Tempo de Execução do Windows.Para obter mais informações, consulte Funções CRT sem suporte pelo /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

Parâmetros

strDestination
Buffer com terminação nula de cadeia de caracteres de destino.
numberOfElements
Tamanho do buffer de cadeia de caracteres de destino.
strSource
Buffer de fonte de cadeia de caracteres terminado em zero.

Valor de retorno

Zero se tiver êxito; um código de erro em falha.

Condições de erro

strDestination	numberOfElements	strSource	Valor de retorno	Conteúdo de strDestination
NULL ou não terminado	any	any	EINVAL	não modificado
any	any	NULL	EINVAL	strDestination[0] definido como 0
any	0, ou muito pequeno	any	ERANGE	strDestination[0] definido como 0

Comentários

A função de strcat_s acrescenta strSource a strDestination e encerra a cadeia de caracteres resultante com um caractere nulo. O caractere inicial de strSource substituirá o caractere nulo de terminação de strDestination. O comportamento de strcat_s será indefinido se as cadeias de caracteres de origem e de destino se sobrepuserem.

Observe que o segundo parâmetro é o tamanho total do buffer, não o tamanho restantes:

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 multibyte de strcat_s. Os argumentos e o valor de retorno de wcscat_s são cadeias de caracteres largos; _mbscat_s são cadeias de caracteres de vários bytes. Essas três funções se comportam de forma idêntica.

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

No C++, o uso dessas funções é simplificado por sobrecargas de modelo; as sobrecargas podem interpretar o tamanho do buffer automaticamente (eliminando a necessidade de especificar um argumento de tamanho) e podem substituir automaticamente as funções menos seguras mais antigas por correspondentes mais seguras e mais recentes. Para obter mais informações, consulte Sobrecargas de modelo seguras.

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

Mapeamentos da rotina de texto genérico