strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l

Artykuł
06/09/2015

Dołącza znaki do ciągu.Te wersje strncat, _strncat_l, wcsncat, wcsncat_l, _mbsncat _mbsncat_l mają wzmocnienia zabezpieczeń, jak opisano w Funkcje zabezpieczeń w CRT.

Ważne
_mbsncat_s i _mbsncat_s_l nie można używać w aplikacjach korzystających ze środowiska wykonawczego systemu Windows.Aby uzyskać więcej informacji, zobacz Funkcje CRT nieobsługiwane przez /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

[poza] strDest
Ciąg docelowy zakończony wartością null.
[w]numberOfElements
Rozmiar buforu miejsca docelowego.
[w]strSource
Ciąg źródłowy zakończony wartością null.
[w]count
Liczba znaków do dołączania, lub _TRUNCATE.
[w] locale
Ustawienia regionalne do użycia.

Wartość zwracana

Zwraca wartość 0, jeśli kończy się pomyślnie, kod błędu w przypadku awarii.

Warunki błędów

strDestination	numberOfElements	strSource	Wartość zwrócona	ZawartośćstrDestination
NULL lub niezakończony	jakakolwiek	jakakolwiek	EINVAL	nie zmodyfikowano
jakakolwiek	jakakolwiek	NULL	EINVAL	nie zmodyfikowano
jakakolwiek	0 lub zbyt mały	jakakolwiek	ERANGE	nie zmodyfikowano

Uwagi

Te funkcje spróbować dodać pierwszy D znaków z strSource do końca strDest, gdzie D jest mniejsze od count i długość strSource.Jeśli dołączane tych D znaków mieści się w ramach strDest (których rozmiar jest określony jako numberOfElements) i nadal zostaw miejsce na znakiem null, a następnie te znaki są dołączane, zaczynając od oryginalnego kończące null z strDestoraz nowy zakończeń null jest dołączony; w przeciwnym razie strDest[0] jest ustawiony znak null i nieprawidłowy parametr zostanie wywołany program obsługi, zgodnie z opisem w Sprawdzanie poprawności parametru.

Istnieje wyjątek od powyższego akapitu.Jeśli count jest _TRUNCATE następnie tyle strSource jak będzie dopasowanie jest dołączana do strDest pozostawiając nadal miejsca, aby dołączyć kończące null.

Na przykład:

char dst[5];

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

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

oznacza, że prosimy o strncat_s Aby dołączyć trzy znaki do dwóch znaków w buforze pięć znaków długości; to mogłoby nie pozostawiają miejsca na null terminator, tym samym strncat_s zerując ciągu i wymaga obsługi nieprawidłowy parametr.

Jeśli wymagane jest zachowanie obcinania, użyj _TRUNCATE lub dopasować size parametru odpowiednio:

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

lub

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

We wszystkich przypadkach wynikowy ciąg znaków jest zakończony znakiem null.Jeśli kopiowanie odbywa się między nakładającymi się ciągami, zachowanie jest niezdefiniowane.

Jeśli strSource lub strDest jest NULL, lub numberOfElements wynosi zero, obsługi nieprawidłowy parametr jest wywoływany, zgodnie z opisem w Sprawdzanie poprawności parametru .Jeśli wykonanie może w dalszym ciągu, funkcja zwraca EINVAL bez modyfikowania jego parametry.

wcsncat_s i _mbsncat_s są wersjami znaków dwubajtowych i znaków wielobajtowych strncat_s.Argumenty ciągu i wartość zwracana przez wcsncat_s są ciągami znaków dwubajtowych; te z _mbsncat_s są ciągami znaków wielobajtowych.Te trzy funkcje w innych wypadkach zachowują się identycznie.

Wartość wyjściowa jest zależna od konfiguracji ustawień kategorii LC_CTYPE ustawień regionalnych; zobacz setlocale, aby uzyskać więcej informacji.Wersje tych funkcji, które nie mają przyrostka _l używają bieżących ustawień regionalnych dla wszelkich zachowań zależnych od ustawień lokalnych; wersje, które mają przyrostek _l są identyczne, z tą różnicą, że w zamian korzystają z przekazanego parametru ustawień regionalnych.Aby uzyskać więcej informacji, zobacz Regionalne.

W języku programowania C++ korzystanie z tych funkcji jest uproszczone przez przeciążania szablonu; przeciążania mogą automatycznie wywnioskować długość buforu (tak, aby nie było konieczne określenie argumentu rozmiaru), ponadto te funkcje mogą automatycznie zastąpić starsze, niezabezpieczone funkcje nowszymi, bardziej bezpiecznymi odpowiednikami.Aby uzyskać więcej informacji, zobacz Przeciążenia bezpiecznych szablonów.

Wersje debugowania tych funkcji najpierw wypełniają bufor 0xFD.Aby wyłączyć to zachowanie, użyj _CrtSetDebugFillThreshold.

Rutynowe mapowania zwykłego tekstu

Procedura Tchar.h	_UNICODE & _MBCS nie zdefiniowano	_MBCS zdefiniowano	_UNICODE zdefiniowany
_tcsncat_s	strncat_s	_mbsnbcat_s	wcsncat_s
_tcsncat_s_l	_strncat_s_l	_mbsnbcat_s_l	_wcsncat_s_l

_strncat_s_li _wcsncat_s_l mają ma zależności ustawień regionalnych; są dostarczane tylko dla _tcsncat_s_l.

Wymagania

Procedura	Wymagany nagłówek
strncat_s	<Ciąg>
wcsncat_s	<ciągo.h> lub <wchar.h>
_mbsncat_s, _mbsncat_s_l	<mbCiąg.h>

Dodatkowe informacje o zgodności – zobacz: Zgodność.

Przykład

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