strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l

Artigo
06/09/2015

Acrescenta caracteres de uma cadeia de caracteres. Estão disponíveis versões mais seguras dessas funções; consulte 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 Tempo de Execução do Windows.Para obter mais informações, consulte Funções CRT sem suporte pelo /ZW.

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 com Null.
strSource
Cadeia de caracteres de origem terminada com Null.
count
Número de caracteres para acrescentar.
locale
Localidade a ser usada.

Valor de retorno

Retorna um ponteiro para a cadeia de caracteres de destino. Nenhum valor de retorno é reservado para indicar um erro.

Comentários

A função strncat acrescenta, no máximo, os primeiros count caracteres de strSource a strDest. O caractere inicial de strSource substituirá o caractere nulo de terminação de strDest. Se um caractere nulo aparecer em strSource antes que os caracteres de count sejam acrescentados, strncat acrescenta todos os caracteres de strSource, até o caractere nulo. Se count for maior que o tamanho de strSource, o tamanho de strSource será usado no lugar de count. Em todos os casos, a cadeia de caracteres resultante é finalizada com um caractere nulo. Se a cópia for feita entre cadeias de caracteres que se sobrepõem, o comportamento será indefinido.

Observação de segurança
strncat não verifica se há espaço suficiente em strDest; é, portanto, uma causa potencial de estouros de buffer.Tenha em mente que count limita o número de caracteres acrescentados; não é um limite no tamanho de strDest.Consulte o exemplo abaixo.Para obter mais informações, consulte Evitando saturações de buffer.

wcsncat e _mbsncat são versões de caracteres largos e de multibyte de strncat. Os argumentos da cadeia de caracteres e o valor de retorno de wcsncat são cadeias de caracteres largos; aqueles do _mbsncat são cadeias de caracteres multibyte. Essas três funções se comportam de forma idêntica.

O valor de saída é afetado pela configuração da categoria LC_CTYPE de 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 dependente da localidade; as versões com o sufixo _l são idênticas, exceto que elas usam o parâmetro de localidade informado. Para obter mais informações, consulte Localidade.

No C++, essas funções tem sobrecargas de modelo. Para obter mais informações, consulte Sobrecargas de modelo seguras.

Mapeamentos da rotina de texto genérico

Rotina TCHAR.H	_UNICODE & _MBCS não definido	_MBCS definido	_UNICODE definido
_tcsncat	strncat	_mbsnbcat	wcsncat
_tcsncat_l	_strncat_l	_mbsnbcat_l	_wcsncat_l

Dica

_strncat_l e _wcsncat_l não têm dependência de localidade e não devem ser 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 informações adicionais de 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)

Observe que BadAppend causou um estouro de buffer.