strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l
Acrescenta caracteres a uma cadeia de caracteres. Estão disponíveis versões mais seguras dessas funções. Para obter informações, confira strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l.
Importante
_mbsncat e _mbsncat_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
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
Parâmetros
strDest
Cadeia de caracteres de destino terminada em nulo.
strSource
Cadeia de caracteres de origem com terminação nula.
count
O número de caracteres a serem acrescentados.
locale
Localidade a usar.
Valor retornado
Retorna um ponteiro para a cadeia de caracteres de destino. Nenhum valor retornado é reservado para indicar um erro.
Comentários
A função strncat acrescenta, no máximo, os primeiros count caracteres de strSource para strDest. O caractere inicial de strSource substitui o caractere nulo de terminação de strDest. Se aparecer um caractere nulo no strSource antes de count caracteres serem acrescentados, strncat acrescenta todos os caracteres de strSource, até o caractere nulo. Se count for maior que o comprimento de strSource, o comprimento de strSource será usado no lugar de count. Em todos os casos, a cadeia de caracteres resultante é encerrada com um caractere nulo. Se ocorrer cópia entre cadeias de caracteres que se sobrepõem, o comportamento será indefinido.
Importante
strncat não verifica se há espaço suficiente em strDest; portanto, é uma causa potencial de sobrecargas de buffer. Tenha em mente que count limita o número de caracteres acrescentado; não é um limite no tamanho de strDest. Veja o exemplo abaixo. Para obter mais informações, confira Como evitar sobrecargas de buffer.
wcsncat e _mbsncat são versões de caracteres largos e de caracteres multibyte de strncat. Os argumentos da cadeia de caracteres e o valor de retorno de wcsncat são cadeias de caracteres largos. Os argumentos da cadeia de caracteres e o valor de retorno de _mbsncat são cadeias de caracteres com vários bytes. Caso contrário, essas três funções se comportam de forma idêntica.
O valor de saída é afetado pela configuração da categoria LC_CTYPE da localidade. Para obter mais informações, consulte setlocale. As versões dessas funções sem o sufixo _l usam a localidade atual para esse comportamento que depende da localidade. As versões com o sufixo _l são idênticas, com exceção de que, em vez disso, usam o parâmetro de localidade fornecido. Para obter mais informações, consulte Localidade.
No C++, essas funções têm sobrecargas de modelo. Para obter mais informações, consulte Sobrecargas de modelo seguras.
Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, confira Estado global no CRT.
Mapeamentos de rotina de texto genérico
Rotina TCHAR.H |
_UNICODE e _MBCS não definidos |
_MBCS definido |
_UNICODE definido |
|---|---|---|---|
_tcsncat |
strncat |
_mbsnbcat |
wcsncat |
_tcsncat_l |
_strncat_l |
_mbsnbcat_l |
_wcsncat_l |
Observação
_strncat_l e _wcsncat_l não têm dependência de localidade e não se destinam a serem chamados diretamente. Eles são fornecidos para uso interno por _tcsncat_l.
Requisitos
| Rotina | Cabeçalho necessário |
|---|---|
strncat |
<string.h> |
wcsncat |
<string.h> ou <wchar.h> |
_mbsncat |
<mbstring.h> |
_mbsncat_l |
<mbstring.h> |
Para obter informações sobre compatibilidade, consulte Compatibilidade.
Exemplo
// 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) );
}
Saída
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)
Você pode ver que BadAppend causou um estouro de buffer.
Confira também
Manipulação de cadeia de caracteres
_mbsnbcat, _mbsnbcat_l
strcat, wcscat, _mbscat
strcmp, wcscmp, _mbscmp
strcpy, wcscpy, _mbscpy
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
_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l
strspn, wcsspn, _mbsspn, _mbsspn_l
Localidade
Interpretação de sequências de caracteres multibyte