strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l

Článek
06/09/2015

Připojí znaky do řetězce.Tyto verze strncat, _strncat_l, wcsncat, wcsncat_l, _mbsncat _mbsncat_l mají rozšíření zabezpečení popsaná v tématu Funkce zabezpečení v CRT.

Důležité
_mbsncat_s a _mbsncat_s_l nelze použít v aplikacích, které jsou spouštěny v modulu Windows Runtime.Další informace naleznete v tématu CRT funkce nejsou podporovány s /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

Parametry

[out] strDest
Řetězec cíle zakončený hodnotou null.
[v]numberOfElements
Velikost vyrovnávací paměti pro cílové umístění.
[v]strSource
Zdrojový řetězec zakončený hodnotou null.
[v]count
Počet znaků, které chcete přidat, nebo _TRUNCATE.
[in] locale
Použité národní prostředí.

Vrácená hodnota

Vrátí hodnotu 0 v případě úspěchu, kód chyby při selhání.

Chybové podmínky

strDestination	numberOfElements	strSource	Návratová hodnota	Obsah strDestination
NULL nebo neukončený	any	any	EINVAL	nezměněno
any	any	NULL	EINVAL	nezměněno
any	0 nebo příliš nízká hodnota	any	ERANGE	nezměněno

Poznámky

Tyto funkce se pokusí připojit první D znaky strSource na konec strDest, kde D je menší z count a strSource.Pokud připojení těch D znaků vejde do strDest (jejichž velikost je uvedena jako numberOfElements) a ponechat prostor pro zakončení null, pak jsou připojeny tyto znaky počínaje původní ukončení hodnotu null pro strDesta nový je připojeno ukončující null; jinak strDest[0] je znakem null a neplatný parametr je vyvolána obslužná rutina, jak je popsáno v Ověření parametru.

Existuje výjimka z výše uvedeného odstavce.Pokud count je _TRUNCATE potom tolik strSource jako bude fit připojen k strDest a nechat prostor pro přidání ukončení hodnotu null.

Příklad:

char dst[5];

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

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

znamená, že jsme s dotazem strncat_s připojit tři znaky dvou znaků vyrovnávací paměti pět znaků; to není místo pro null zakončení ponecháte tedy strncat_s program je zaměřen mimo řetězec a zavolá obslužnou rutinu neplatný parametr.

Potřeby krácení chování pomocí _TRUNCATE nebo upravit size parametru odpovídajícím způsobem:

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

nebo

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

Ve všech případech je výsledný řetězec ukončený znakem null.Pokud ke kopírování dojde mezi řetězci, které se překrývají, chování není definováno.

Pokud strSource nebo strDest je NULL, nebo numberOfElements je nulová, je vyvolána neplatný parametr obslužné rutiny, jak je popsáno v Ověření parametru .Pokud je povoleno zpracování pokračovat, vrátí funkce EINVAL beze změny jeho parametry.

wcsncat_s a _mbsncat_s jsou širokoznaká verze a vícebajtová znaková verze strncat_s.Argumenty řetězce a vrácené hodnoty wcsncat_s jsou širokoznaké řetězce. Hodnoty _mbsncat_s jsou vícebajtové znakové řetězce.Tyto tři funkce se chovají identicky jinak.

Výstupní hodnota je ovlivněna nastavením kategorie LC_CTYPE národního prostředí; viz setlocale pro další informace.Verze těchto funkcí bez přípony _l používají aktuální národní prostředí pro toto chování závislé na národním prostředí. Verze s příponou _l jsou stejné s tím rozdílem, že používají předaný parametr národního prostředí.Další informace naleznete v tématu Národní prostředí.

V jazyce C++ je použití těchto funkcí zjednodušeno díky přetížení šablon; přetížení dokáží odvodit velikost vyrovnávací paměti automaticky (tak, že eliminují potřebu zadat argument velikosti) a automaticky nahradit starší, nezabezpečené funkce jejími novějšími, bezpečnějšími protějšky.Další informace naleznete v tématu Přetížení zabezpečení šablony.

Ladicí verze těchto funkcí nejprve naplní vyrovnávací paměť hodnotou 0xFD.Chcete-li zakázat toto chování, použijte _CrtSetDebugFillThreshold.

Rutinní mapování obecného textu

Rutina TCHAR.H	_UNICODE & _MBCS není definováno	_MBCS definováno	_UNICODE definováno
_tcsncat_s	strncat_s	_mbsnbcat_s	wcsncat_s
_tcsncat_s_l	_strncat_s_l	_mbsnbcat_s_l	_wcsncat_s_l

_strncat_s_la _wcsncat_s_l mít závislost národního prostředí; jsou poskytovány pouze pro _tcsncat_s_l.

Požadavky

Rutina	Požadované záhlaví
strncat_s	<string.h>
wcsncat_s	<string.h> nebo <wchar.h>
_mbsncat_s, _mbsncat_s_l	<mbstring.h>

Další informace o kompatibilitě naleznete v tématu Kompatibilita.

Příklad

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