strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l

Artykuł
03/26/2013

Dołącz znaki na ciąg.Są to wersje strncat, _strncat_l, wcsncat, wcsncat_l, _mbsncat _mbsncat_l z ulepszeń zabezpieczeń, zgodnie z opisem w Funkcje zabezpieczeń w CRT.

Ważne
_mbsncat_si _mbsncat_s_l nie można używać w aplikacji, których wykonywanie w czasie wykonywania systemu Windows.Aby uzyskać więcej informacji, zobacz CRT funkcje nie obsł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

[Brak]strDest
Ciąg zakończony wartością zerową miejsca docelowego.
[in]numberOfElements
Rozmiar buforu docelowego.
[in]strSource
Ciąg zakończony wartością zerową źródła.
[in]count
Liczba znaków do dołączania, lub _TRUNCATE.
[in]locale
Ustawienia regionalne używane.

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	Zwracana wartość	ZawartośćstrDestination
NULLlub niezakończony	wszelkie	wszelkie	EINVAL	niemodyfikowane
wszelkie	wszelkie	NULL	EINVAL	niemodyfikowane
wszelkie	0 lub za mały	wszelkie	ERANGE	niemodyfikowane

Uwagi

Te funkcje spróbować dodać pierwszy D znaków z strSource na koniec strDest, gdzie D jest mniejsze od count i długość strSource.Jeśli dołączane tych D znaków zmieści się w ramach strDest (której rozmiar jest podawany jako numberOfElements) i nadal zostaw miejsce na znakiem null, a następnie te znaki są dołączane, począwszy od oryginału, kończące null z strDestoraz nowy zakończenie 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 danych, strSource jak dopasowanie jest dołączana do strDest pozostawiając 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 w tym zadaniu strncat_s Aby dołączyć trzy znaki do dwóch znaków w znakach buforu pięć długi; to pozostawi stąd ma miejsca na null terminator, strncat_s zerując ciągu i wymaga obsługi nieprawidłowy parametr.

Jeśli wymagane jest zachowanie obcinania, należy użyć _TRUNCATE lub korygowania size parametr 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 ciągami, które nakładają się, zachowanie jest niezdefiniowane.

Jeśli strSource lub strDest jest NULL, lub jest numberOfElements wynosi zero, program obsługi nieprawidłowy parametr jest wywoływana, 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_si _mbsncat_s szerokich znaków i znaków wielobajtowych wersje strncat_s.Argumenty ciąg znaków i wartość zwracana przez wcsncat_s są ciągami szerokich znaków; tych z _mbsncat_s są ciągami znaków wielobajtowych.Zmienia tych trzech funkcji zachowanie takich samych nazwach.

Wartość produkcji jest zależny od ustawienia z LC_CTYPE kategorii ustawienie regionalne tzn. zobacz setlocale Aby uzyskać więcej informacji.Wersje te funkcje, bez _l sufiks Użyj bieżących ustawień regionalnych tego zachowania zależne od ustawień lokalnych; wersje z _l sufiks są identyczne z tym, że używają zamiast przekazany parametr ustawień regionalnych.Aby uzyskać więcej informacji, zobacz Ustawienia regionalne.

W języku C++ korzystając z tych funkcji jest uproszczony przez przeciążenia szablonu; przeciążenia mogą wywnioskować długość buforu automatycznie (eliminując konieczność, aby określić argument rozmiar) i starszych, które nie są bezpieczne funkcje mogą automatycznie zastąpić z ich odpowiednikami nowsze, bezpieczne.Aby uzyskać więcej informacji, zobacz Secure, szablon Overloads.

Wersje do debugowania tych funkcji najpierw wypełnić bufor z 0xFD.Aby wyłączyć to zachowanie, należy użyć _CrtSetDebugFillThreshold.

Tekst rodzajowy rutynowych mapowania

TCHAR.Rozpoczęto wykonywanie procedury h	_UNICODE & _MBCS nie zdefiniowany	_MBCS, definicja	_UNICODE, definicja
_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

Rozpoczęto wykonywanie procedury	Wymaganego nagłówka
strncat_s	<string.h>
wcsncat_s	<string.h> lub <wchar.h>
_mbsncat_s, _mbsncat_s_l	<mbstring.h>

Aby uzyskać dodatkowe informacje o zgodności, zobacz zgodności we wprowadzeniu.

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