strncat, _strncat_l, wcsncat, wcsncat_l, _mbsncat _mbsncat_l

Artigo
08/25/2010

acrescentar caracteres de uma seqüência de caracteres.Versões mais seguras dessas funções estão disponível, consulte strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l.

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
Seqüência de caracteres terminada com caractere nulo de destino.
strSource
Seqüência de caracteres terminada com caractere nulo de fonte.
count
Número de caracteres para acrescentar.
locale
Localidade usar.

Valor de retorno

Retorna um ponteiro para a seqüência de caracteres de destino.Nenhum valor retornado é reservado para indicar um erro.

Comentários

The strncat função anexa, no máximo, o primeiro count caracteres do strSource para strDest. O caractere inicial de strSource substitui o caractere nulo de terminação de strDest. Se aparecer um caractere nulo em strSource antes de count caracteres são anexados, strncat acrescenta todos os caracteres desde strSource, até o caractere nulo. If count é maior do que o comprimento de strSource, o tamanho de strSource usado no lugar de count. Todos os casos, a seqüência de caracteres resultante é finalizada com um caractere nulo.Se copiar ocorre entre cadeias de caracteres que se sobrepõem, o comportamento é indefinido.

Observação de segurança:
strncat não verifica a existência de espaço suficiente no strDest; Portanto, é uma causa potencial de saturações de buffer. Tenha em mente que count limita o número de caracteres acrescentada; não é um limite no dimensionar do strDest. Consulte o exemplo abaixo.Para obter mais informações, consulte Evitar saturações de buffer.

wcsncat e _mbsncatsão versões de caractere largo e caracteres de multibyte de strncat. Os argumentos de seqüência de caractere e o valor retornado do wcsncatsão caractere largos strings; as de _mbsncat são seqüências de caractere de multibyte. Especifique estas três funções identicamente outro comportam.

O valor de saída é afetado pela configuração do LC_CTYPE categoria de configuração da localidade; consulte setlocale para obter mais informações.As versões dessas funções sem o _l sufixo use a localidade corrente para esse comportamento dependente de localidade; as versões com o _l sufixo são idênticas exceto que usarem o parâmetro de localidade passado em vez disso. Para obter mais informações, consulte Localidade.

No C++, essas funções têm sobrecargas de modelo.Para obter mais informações, consulte Proteger overloads de modelo.

Mapeamentos de rotina de texto genérica

Rotina TCHAR.H	_UNICODE & _MBCS não definido	_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 ter nenhuma dependência de localidade e não pretendem ser chamado 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 adicionais compatibilidade, consulte Compatibilidade na introdução.

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.