strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l

Artigo
08/25/2010

Acrescente uma seqüência de caracteres.Essas são sistema autônomo versões de strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l com aprimoramentos de segurança conforme descrito em Aprimoramentos de segurança no CRT.

errno_t strncat_s(
   char *strDest,
   size_t numberOfElements,
   const char *strSource,
   size_t count
);
errno_t _strncat_s_l(
   char *strDest,
   size_t numberOfElements,
   const char *strSource,
   size_t count,
   _locale_t locale
);
errno_t wcsncat_s(
   wchar_t *strDest,
   size_t numberOfElements,
   const wchar_t *strSource,
   size_t count 
);
errno_t _wcsncat_s_l(
   wchar_t *strDest,
   size_t numberOfElements,
   const wchar_t *strSource,
   size_t count,
   _locale_t locale
);
errno_t _mbsncat_s(
   unsigned char *strDest,
   size_t numberOfElements,
   const unsigned char *strSource,
   size_t count
);
errno_t _mbsncat_s_l(
   unsigned char *strDest,
   size_t numberOfElements,
   const unsigned char *strSource,
   size_t count,
   _locale_t locale
);
template <size_t size>
errno_t strncat_s(
   char (&strDest)[size],
   const char *strSource,
   size_t count
); // C++ only
template <size_t size>
errno_t _strncat_s_l(
   char (&strDest)[size],
   const char *strSource,
   size_t count,
   _locale_t locale
); // C++ only
template <size_t size>
errno_t wcsncat_s(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count 
); // C++ only
template <size_t size>
errno_t _wcsncat_s_l(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count,
   _locale_t locale
); // C++ only
template <size_t size>
errno_t _mbsncat_s(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count
); // C++ only
template <size_t size>
errno_t _mbsncat_s_l(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count,
   _locale_t locale
); // C++ only

Parâmetros

[out] strDest
Seqüência de caracteres terminada com caractere nulo de destino.
[in]numberOfElements
dimensionar do buffer de destino.
[in]strSource
Seqüência de caracteres terminada com caractere nulo de fonte.
[in]count
Número de caracteres para acrescentar ou _TRUNCATE.
[in]locale
Localidade usar.

Valor de retorno

Retorna 0 se obtiver êxito, um código de erro em caso de falha.

Condições de erro

strDestination	numberOfElements	strSource	Valor de Retorno	Contents of strDestination
NULL ou não finalizada	any	any	EINVAL	não modificado
any	any	NULL	EINVAL	não modificado
any	0 ou muito pequeno	any	ERANGE	não modificado

Comentários

Essas funções tentam acrescentar o primeiro D caracteres do strSource ao participante do strDest, onde D é inferior a count e o comprimento do strSource. Se acrescentar essas D caracteres irão caber dentro strDest (cujo dimensionar é fornecido sistema autônomo numberOfElements) e ainda deixar espaço para um terminador nulo, e, em seguida, esses caracteres são acrescentados, começando com o original nulo de terminação strDest, e um novo null terminação é acrescentada; caso contrário, strDest[0] é conjunto sistema autônomo o caractere nulo e o parâmetro inválido manipulador é chamado, conforme descrito em Validação de parâmetro.

Há uma exceção para o parágrafo acima.If count é _TRUNCATE em seguida, o máximo de strSource sistema autônomo será adequado é acrescentado ao strDest enquanto ainda deixa espaço para acrescentar uma terminação nula.

Por exemplo,

char dst[5];

strncpy_s(dst, _countof(dst), "12", 2);

strncat_s(dst, _countof(dst), "34567", 3);

significa que nós estão perguntando strncat_s Para acrescentar três caracteres de dois caracteres em um buffer de cinco caracteres longo; Isso deixaria nenhum espaço para que o terminador nulo, daí strncat_s zeros fora de seqüência e chama o manipulador de parâmetro inválido.

Se for necessário truncamento de comportamento, use _TRUNCATE ou ajustar a size parâmetro da mesma forma:

strncat_s(dst, _countof(dst), "34567", _TRUNCATE);

strncat_s(dst, _countof(dst), "34567", _countof(dst)-strlen(dst)-1);

Em 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.

If strSource ou strDest é NULL, ou é numberOfElements é zero, o manipulador de parâmetro inválido é invocado, sistema autônomo descrito em Validação de parâmetro . Se a execução terá permissão para continuar, a função retornará EINVAL sem modificar seus parâmetros.

wcsncat_s e _mbsncat_ssão versões de caractere largo e caracteres de multibyte de strncat_s. Os argumentos de seqüência de caractere e o valor retornado do wcsncat_ssão caractere largos strings; as de _mbsncat_s 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++, usando essas funções é simplificado pelo modelo sobrecargas; sobrecargas de podem inferir o comprimento do buffer automaticamente (eliminando a necessidade de especificar um argumento de dimensionar) e eles podem substituir automaticamente funções não seguras, mais antigas, com suas contrapartes mais recentes e seguras.Para obter mais informações, consulte Proteger overloads de modelo.

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

Mapeamentos de rotina de texto genérica

Rotina TCHAR.H	_UNICODE & _MBCS não definido	_MBCS definido	_UNICODE definido
_tcsncat_s	strncat_s	_mbsnbcat_s	wcsncat_s
_tcsncat_s_l	_strncat_s_l	_mbsnbcat_s_l	_wcsncat_s_l

_strncat_s_l e _wcsncat_s_l não ter nenhuma dependência da localidade; eles são fornecidos somente para _tcsncat_s_l.

Requisitos

Rotina	Cabeçalho necessário
strncat_s	<string.h>
wcsncat_s	<string.h> ou <wchar.h>
_mbsncat_s, _mbsncat_s_l	<mbstring.h>

Para obter informações adicionais compatibilidade, consulte Compatibilidade na introdução.

Exemplo

// crt_strncat_s.cpp
// compile with: /MTd

// These #defines enable secure template overloads
// (see last part of Examples() below)
#define _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES 1 
#define _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT 1

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <crtdbg.h>  // For _CrtSetReportMode
#include <errno.h>

// This example uses a 10-byte destination buffer.

errno_t strncat_s_tester( const char * initialDest,
                          const char * src,
                          int count )
{
   char dest[10];
   strcpy_s( dest, _countof(dest), initialDest );

   printf_s( "\n" );

   if ( count == _TRUNCATE )
      printf_s( "Appending '%s' to %d-byte buffer dest with truncation semantics\n",
               src, _countof(dest) );
   else
      printf_s( "Appending %d chars of '%s' to %d-byte buffer dest\n",
              count, src, _countof(dest) );

   printf_s( "    old contents of dest: '%s'\n", dest );

   errno_t err = strncat_s( dest, _countof(dest), src, count );

   printf_s( "    new contents of dest: '%s'\n", dest );

   return err;
}


void Examples()
{
   strncat_s_tester( "hi ", "there", 4 );
   strncat_s_tester( "hi ", "there", 5 );
   strncat_s_tester( "hi ", "there", 6 );

   printf_s( "\nDestination buffer too small:\n" );
   strncat_s_tester( "hello ", "there", 4 );

   printf_s( "\nTruncation examples:\n" );

   errno_t err = strncat_s_tester( "hello ", "there", _TRUNCATE );
   printf_s( "    truncation %s occur\n", err == STRUNCATE ? "did"
                                                       : "did not" );

   err = strncat_s_tester( "hello ", "!", _TRUNCATE );
   printf_s( "    truncation %s occur\n", err == STRUNCATE ? "did"
                                                       : "did not" );

   printf_s( "\nSecure template overload example:\n" );

   char dest[10] = "cats and ";
   strncat( dest, "dachshunds", 15 );
   // With secure template overloads enabled (see #define
   // at top of file), the preceding line is replaced by
   //    strncat_s( dest, _countof(dest), "dachshunds", 15 );
   // Instead of causing a buffer overrun, strncat_s invokes
   // the invalid parameter handler.
   // If secure template overloads were disabled, strncat would
   // append "dachshunds" and overrun the dest buffer.
   printf_s( "    new contents of dest: '%s'\n", dest );
}

void myInvalidParameterHandler(
   const wchar_t* expression,
   const wchar_t* function, 
   const wchar_t* file, 
   unsigned int line, 
   uintptr_t pReserved)
{
   wprintf_s(L"Invalid parameter handler invoked: %s\n", expression);
}

int main( void )
{
   _invalid_parameter_handler oldHandler, newHandler;

   newHandler = myInvalidParameterHandler;
   oldHandler = _set_invalid_parameter_handler(newHandler);
   // Disable the message box for assertions.
   _CrtSetReportMode(_CRT_ASSERT, 0);

   Examples();
}

 Appending 4 chars of 'there' to 10-byte buffer dest     old contents of dest: 'hi '     new contents of dest: 'hi ther'  Appending 5 chars of 'there' to 10-byte buffer dest     old contents of dest: 'hi '     new contents of dest: 'hi there'  Appending 6 chars of 'there' to 10-byte buffer dest     old contents of dest: 'hi '     new contents of dest: 'hi there'  Destination buffer too small:  Appending 4 chars of 'there' to 10-byte buffer dest     old contents of dest: 'hello ' Invalid parameter handler invoked: (L"Buffer is too small" && 0)     new contents of dest: ''  Truncation examples:  Appending 'there' to 10-byte buffer dest with truncation semantics     old contents of dest: 'hello '     new contents of dest: 'hello the'     truncation did occur  Appending '!' to 10-byte buffer dest with truncation semantics     old contents of dest: 'hello '     new contents of dest: 'hello !'     truncation did not occur  Secure template overload example: Invalid parameter handler invoked: (L"Buffer is too small" && 0)     new contents of dest: ''