`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, , `_mbsncat_s_mbsncat_s_l`

Článek
08/03/2024

Připojí znaky k řetězci. Tyto verze , , _strncat_lwcsncat, _wcsncat_l, _mbsncatmají _mbsncat_lvylepšení zabezpečení, jak je popsáno v funkcích zabezpečení v CRT.strncat

Důležité

_mbsncat_sa _mbsncat_s_l nelze je použít v aplikacích, které se spouští v prostředí Windows Runtime. Další informace najdete v tématu Funkce CRT, které nejsou v aplikacích Univerzální platforma Windows podporované.

Syntaxe

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

strDest
Cílový řetězec ukončený hodnotou null.

numberOfElements
Velikost cílové vyrovnávací paměti.

strSource
Zdrojový řetězec ukončený hodnotou null.

count
Počet znaků, které se mají připojit, nebo _TRUNCATE.

locale
Národní prostředí, které se má použít.

Vrácená hodnota

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

Chybové podmínky

`strDestination`	`numberOfElements`	`strSource`	Vrácená hodnota	Obsah `strDestination`
`NULL` nebo neukončeno	jakékoliv	jakékoliv	`EINVAL`	neupraveno
jakékoliv	jakékoliv	`NULL`	`EINVAL`	neupraveno
jakékoliv	0 nebo příliš malé	jakékoliv	`ERANGE`	neupraveno

Poznámky

Tyto funkce se snaží připojit první D znaky na konec strDest, kde D je menší a count délka strSourcestrSource . Pokud se k těmto D znakům strDest připojíte (jejíž velikost je zadána jako numberOfElements) a ponecháte místo pro ukončovací znak null, připojí se tyto znaky, počínaje původní koncovou hodnotou null strDesta připojí se nová ukončující hodnota null. Jinak strDest[0] se nastaví na znak null a vyvolá se obslužná rutina neplatných parametrů, jak je popsáno v ověření parametru.

Existuje výjimka z výše uvedeného odstavce. Pokud count je _TRUNCATE, pak tolik, strSource jak bude fit připojen, strDest zatímco stále opustit prostor připojit ukončující hodnotu null.

Příklad:

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

Znamená, že žádáme strncat_s o připojení tří znaků k dvěma znakům v vyrovnávací paměti o délce pěti znaků; neunechá žádné místo pro ukončovací znak null, takže strncat_s vynuluje řetězec a zavolá neplatnou obslužnou rutinu parametru.

Pokud je potřeba zkrátit chování, použijte _TRUNCATE nebo upravte count parametr 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 probíhá kopírování mezi řetězci, které se překrývají, chování není definováno.

Pokud strSource je nebo je nebo numberOfElements strDest je NULLnula, je vyvolána neplatná obslužná rutina parametru, jak je popsáno v ověření parametru . Pokud je provádění povoleno pokračovat, vrátí funkce beze EINVAL změny jeho parametrů.

wcsncat_sa _mbsncat_s jsou širokoznakové a vícebajtové verze .strncat_s Řetězcové argumenty a návratová hodnota jsou řetězce širokého znaku wcsncat_s . Argumenty a návratová _mbsncat_s hodnota jsou řetězce s vícebajtovými znaky. Tyto tři funkce se chovají stejně jinak.

Výstupní hodnota je ovlivněna nastavením LC_CTYPE nastavení kategorie národního prostředí. Další informace najdete na webu setlocale. Verze těchto funkcí bez _l přípony 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 shodné s tím rozdílem, že místo toho 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 přetíženími šablon; přetížení mohou automaticky odvodit délku vyrovnávací paměti (eliminuje potřebu zadat argument velikosti) a mohou automaticky nahradit starší, nezabezpečené funkce jejich novějšími zabezpečenými protějšky. Další informace naleznete v tématu Přetížení šablon zabezpečení.

Verze knihovny ladění těchto funkcí nejprve vyplní vyrovnávací paměť 0xFE. Chcete-li toto chování zakázat, použijte _CrtSetDebugFillThreshold.

Ve výchozím nastavení je globální stav této funkce vymezen na aplikaci. Chcete-li toto chování změnit, přečtěte si téma Globální stav v CRT.

Mapování rutin obecného textu

Rutina TCHAR.H	`_UNICODE` a `_MBCS` není definován	`_MBCS` definovaný	`_UNICODE` definovaný
`_tcsncat_s`	`strncat_s`	`_mbsnbcat_s`	`wcsncat_s`
`_tcsncat_s_l`	`_strncat_s_l`	`_mbsnbcat_s_l`	`_wcsncat_s_l`

_strncat_s_l a _wcsncat_s_l nemají žádnou závislost na národním prostředí; jsou poskytovány _tcsncat_s_lpouze pro .

Požadavky

Rutina	Požadovaný hlavičkový soubor
`strncat_s`	<string.h>
`wcsncat_s`	<string.h> nebo <wchar.h>
`_mbsncat_s`, `_mbsncat_s_l`	<mbstring.h>

Další informace o kompatibilitě najdete 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();
}

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

Viz také

Manipulace s řetězci
Národní prostředí
Interpretace vícebajtových sekvencí znaků
_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

Sdílet prostřednictvím

`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, , `_mbsncat_s_mbsncat_s_l`

Syntaxe

Parametry

Vrácená hodnota

Chybové podmínky

Poznámky

Mapování rutin obecného textu

Požadavky

Příklad

Viz také

Váš názor

Další materiály

Sdílet prostřednictvím

strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, , _mbsncat_s_mbsncat_s_l

Syntaxe

Parametry

Vrácená hodnota

Chybové podmínky

Poznámky

Mapování rutin obecného textu

Požadavky

Příklad

Viz také

Váš názor

Další materiály

`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, , `_mbsncat_s_mbsncat_s_l`