`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, , `_mbsncat_s_l`

Artigo
08/03/2024

Acrescenta caracteres a uma cadeia de caracteres. Essas versões do , _strncat_l, , _wcsncat_lwcsncat, _mbsncat, _mbsncat_l têm aprimoramentos de strncatsegurança, conforme descrito em Recursos de segurança no CRT.

Importante

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

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

strDest
Cadeia de caracteres de destino terminada em nulo.

numberOfElements
Tamanho do buffer de destino.

strSource
Cadeia de caracteres de origem com terminação nula.

count
Número de caracteres a serem acrescentados ou _TRUNCATE.

locale
Localidade a usar.

Valor retornado

Retornará 0 se for bem-sucedido; um código de erro em caso de falha.

Condições de erro

`strDestination`	`numberOfElements`	`strSource`	Valor retornado	Conteúdo de `strDestination`
`NULL` ou não finalizado	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 anexar os primeiros D caracteres de strSource ao final do strDest, em que D é inferior a count e o comprimento de strSource. Se a anexação desses D caracteres couber em strDest (cujo tamanho é fornecido como numberOfElements) e ainda deixar espaço para um terminador nulo, esses caracteres serão anexados, começando no nulo de terminação original de , e um novo nulo de terminação será acrescentado; caso contrário, strDest[0] será definido como o caractere nulo e o manipulador de parâmetro inválido será invocado, conforme descrito em Validação de strDestparâmetro.

Há uma exceção ao parágrafo acima. Se count for _TRUNCATE, então o máximo que strSource couber é anexado enquanto strDest ainda deixa espaço para anexar um nulo de terminação.

Por exemplo,

char dst[5];
strncpy_s(dst, _countof(dst), "12", 2);
strncat_s(dst, _countof(dst), "34567", 3);

significa que estamos pedindo strncat_s para acrescentar três caracteres a dois caracteres em um buffer de cinco caracteres; isso não deixaria espaço para o terminador nulo, portanto strncat_s , zera a cadeia de caracteres e chama o manipulador de parâmetro inválido.

Se for necessário o comportamento de truncamento, use _TRUNCATE ou ajuste o parâmetro count 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 ocorrer cópia entre cadeias de caracteres que se sobrepõem, o comportamento será indefinido.

Se strSource ou strDest for NULL, ou numberOfElements for zero, o manipulador de parâmetro inválido será invocado, conforme descrito em Validação de parâmetro. Se a execução puder continuar, a função retornará EINVAL sem modificar seus parâmetros.

wcsncat_s e _mbsncat_s são versões de caracteres largos e de caracteres multibyte de strncat_s. Os argumentos da cadeia de caracteres e o valor de retorno de wcsncat_s são cadeias de caracteres largos. Os argumentos e o valor retornado de são cadeias de _mbsncat_s caracteres multibyte. 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 _l sufixo usam a localidade atual para esse comportamento dependente de localidade; as versões com o _l sufixo são idênticas, exceto que usam o parâmetro locale passado. Para obter mais informações, consulte Localidade.

Em C++, o uso dessas funções é simplificado pelas sobrecargas de modelo; as sobrecargas podem inferir o tamanho do buffer automaticamente (eliminando a necessidade de especificar um argumento de tamanho) e podem substituir automaticamente funções mais antigas e não seguras por suas equivalentes mais recentes e seguras. Para obter mais informações, consulte Sobrecargas de modelo seguras.

As versões de biblioteca de depuração dessas funções preenchem o buffer com 0xFE. Para desabilitar esse comportamento, use _CrtSetDebugFillThreshold.

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_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ência local; eles são apenas fornecidos 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 sobre 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();
}

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: ''

Confira também

Manipulação de cadeia de caracteres
Localidade
Interpretação de sequências de caracteres multibyte
_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

Partilhar via

`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, , `_mbsncat_s_l`

Sintaxe

Parâmetros

Valor retornado

Condições de erro

Comentários

Mapeamentos de rotina de texto genérico

Requisitos

Exemplo

Confira também

Comentários

Recursos adicionais

Partilhar via

strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, , _mbsncat_s_l

Sintaxe

Parâmetros

Valor retornado

Condições de erro

Comentários

Mapeamentos de rotina de texto genérico

Requisitos

Exemplo

Confira também

Comentários

Recursos adicionais

`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, , `_mbsncat_s_l`