strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l

Artigo
06/09/2015

Acrescenta caracteres a uma cadeia de caracteres. Essas versões de strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l têm aprimoramentos de segurança, como descrito em Recursos de segurança no CRT.

Importante

_mbsncat_s e _mbsncat_s_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.

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

[saída] strDest
Cadeia de caracteres de destino terminada com Null.
[in]numberOfElements
Tamanho do buffer de destino.
[in]strSource
Cadeia de caracteres de origem terminada com Null.
[in]count
Número de caracteres a ser anexado, ou _TRUNCATE.
[entrada] locale
Localidade a ser usada.

Valor de retorno

Retornará 0 se tiver êxito, um código de erro da 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	não modificado
any	0, ou muito pequeno	any	ERANGE	não modificado

Comentários

Tentativa dessas funções para acrescentar os primeiros caracteres de D de strSource ao final de strDest, onde D é o menor de count e o comprimento de strSource. Se anexar esses caracteres de D caiba dentro de strDest (cujo tamanho é fornecido como numberOfElements) e deixar ainda de espaço para um terminador nulo, esses caracteres são anexados, a partir do original que encerra o zero de strDest, e um novo zero de término está anexado; caso contrário, strDest[0] é definido como o caractere nulo e o manipulador inválido do parâmetro é chamado, conforme descrito em Validação do parâmetro.

Há uma exceção no parágrafo anterior. Se count é _TRUNCATE em tão bem quanto de strSource caberá será anexada a strDest enquanto ainda deixar de espaço anexar um zero sendo encerrado.

Por exemplo,

char dst[5];

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

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

significa que nós estamos solicitando strncat_s para acrescentar por muito tempo três caracteres a dois caracteres em caracteres de um buffer cinco; isso não permite nenhum espaço para o terminador, portanto os zeros nulos de strncat_s para substituir a cadeia de caracteres e chama o manipulador inválido do parâmetro.

Se o comportamento de truncamento é necessário, use _TRUNCATE ou ajuste o parâmetro de size adequadamente:

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

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

Em todos os casos, a cadeia de caracteres resultante é encerrada com um caractere nulo. Se a cópia for feita entre cadeias de caracteres que se sobrepõem, o comportamento será indefinido.

Se strSource ou strDest são NULL, ou são numberOfElements for zero, o manipulador inválido do parâmetro será chamado, conforme descrito em Validação do parâmetro . Se a execução for permitida continuar, a função retornará EINVAL sem alterar seus parâmetros.

wcsncat_s e _mbsncat_s são versões de caracteres largos e de multibyte de strncat_s. Os argumentos da cadeia de caracteres e o valor de retorno de wcsncat_s são cadeias de caracteres largos; aqueles do _mbsncat_s 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++, 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

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 têm dependências de localidade; 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 informações adicionais de compatibilidade, consulte Compatibilidade.

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();
}