strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l

Článek
03/26/2013

Připojte řetězec znaků.Jedná se o verze strncat, _strncat_l, wcsncat, wcsncat_l, _mbsncat _mbsncat_l s vylepšení zabezpečení, jak je popsáno v Funkce zabezpečení v CRT.

Důležité
_mbsncat_sa _mbsncat_s_l nelze použít v aplikacích, které jsou spuštěny v systému 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

[výstup]strDest
Řetězec zakončený hodnotou Null cílové.
[v]numberOfElements
Velikost cílové vyrovnávací paměti.
[v]strSource
Řetězec zakončený hodnotou Null zdroje.
[v]count
Počet znaků, které chcete připojit, nebo _TRUNCATE.
[v]locale
Chcete-li národní prostředí pro použití.

Vrácená hodnota

Vrátí hodnotu 0, pokud je úspěšná, kód chyby při selhání.

Chybové stavy

strDestination	numberOfElements	strSource	Vrácená hodnota	ObsahstrDestination
NULLnebo neukončený	všechny	všechny	EINVAL	Nezměněno
všechny	všechny	NULL	EINVAL	Nezměněno
všechny	0 nebo příliš malá.	všechny	ERANGE	Nezměněno

Poznámky

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

Existuje výjimka do výše uvedeného odstavce.Pokud count je _TRUNCATE poté, co největší část strSource jako vůli přizpůsobit připojen k strDest při stále zůstalo místo připojová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 požadavkem strncat_s připojit tři znaky dvou znaků vyrovnávací paměti pět znaků; To by zanechala není místo pro null zakončení, tedy strncat_s souvislou mimo řetězec a zavolá obslužnou rutinu neplatný parametr.

Potřeby zkrá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 kopírování probíhá mezi řetězce, které se překrývají, chování není definován.

Pokud strSource nebo strDest je NULL, nebo je numberOfElements je rovna nule, je vyvolána obslužná rutina neplatný parametr, jak je popsáno v Ověření parametrů .Pokud je povoleno zpracování, chcete-li pokračovat, vrátí funkce EINVAL beze změny jeho parametry.

wcsncat_sa _mbsncat_s jsou verze širokého znaku a vícebajtové znakové sady strncat_s.Řetězcové argumenty a vrácené hodnoty wcsncat_s jsou řetězci širokého znaku; u _mbsncat_s jsou vícebajtové znakové řetězce.Tyto tři funkce chovat identicky jinak.

Výstupní hodnota je ovlivněna nastavením LC_CTYPE kategorie nastavení národního prostředí; Viz setlocale pro další informace.Verze těchto funkcí, aniž by _l příponu použít aktuální národní prostředí pro toto chování závislé na národním prostředí; verze s _l s tím rozdílem, že používají místo něho předán parametr locale shodná přípona.Další informace naleznete v tématu Národní prostředí.

V jazyce C++ pomocí těchto funkcí je zjednodušeno díky přetížení šablony; přetížení můžete automaticky odvodit velikost vyrovnávací paměti (není tedy třeba zadat argument velikost) a starší, nezabezpečené funkce lze automaticky nahradí s jejich protějšky novější, bezpečné.Další informace naleznete v tématu Přetížení šablony zabezpečení.

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

Mapování rutiny obecného textu

TCHAR.Byla zahájena rutina h	_UNICODE & _MBCS není definováno	_MBCS, definice	_UNICODE definována
_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

Byla zahájena 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ě, viz Compatibility v úvodu.

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