`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`

Artykuł
10/12/2023

Dołącza znaki do ciągu. Te wersje programu strncat, _strncat_l, _wcsncat_lwcsncat, _mbsncat_mbsncat_l mają ulepszenia zabezpieczeń zgodnie z opisem w temacie Funkcje zabezpieczeń w narzędziu CRT.

Ważne

_mbsncat_snie można jej _mbsncat_s_l używać w aplikacjach wykonywanych w środowisko wykonawcze systemu Windows. Aby uzyskać więcej informacji, zobacz Funkcje CRT nieobsługiwane w aplikacjach platforma uniwersalna systemu Windows.

Składnia

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
Ciąg docelowy zakończony wartością null.

numberOfElements
Rozmiar buforu docelowego.

strSource
Ciąg źródłowy zakończony wartością null.

count
Liczba znaków do dołączenia lub _TRUNCATE.

locale
Ustawienia regionalne do użycia.

Wartość zwracana

Zwraca wartość 0, jeśli operacja powiedzie się, kod błędu w przypadku błędu.

Warunki błędu

`strDestination`	`numberOfElements`	`strSource`	Wartość zwracana	Zawartość `strDestination`
`NULL` lub nieokreślone	dowolny	dowolny	`EINVAL`	niezmodyfikowane
dowolny	dowolny	`NULL`	`EINVAL`	niezmodyfikowane
dowolny	0 lub za mała	dowolny	`ERANGE`	niezmodyfikowane

Uwagi

Te funkcje próbują dołączyć pierwsze D znaki na końcu strDest, gdzie D jest mniejsza i count długość strSourcestrSource . Jeśli dołączanie tych D znaków będzie mieścić się w obrębie strDest (którego rozmiar jest podany jako numberOfElements) i nadal pozostawia miejsce na terminator o wartości null, dołączane są te znaki, począwszy od oryginalnego zakończenia wartości strDestnull , a nowa wartość null zakończenia jest dołączana; w przeciwnym razie strDest[0] jest ustawiona na znak null, a nieprawidłowa procedura obsługi parametrów jest wywoływana, zgodnie z opisem w temacie Walidacja parametru.

Istnieje wyjątek od powyższego akapitu. Jeśli count parametr ma _TRUNCATEwartość , do parametru strSource jest dołączana strDest tyle, ile będzie pasować, podczas gdy nadal pozostawia miejsce, aby dołączyć wartość null zakończenia.

Przykład:

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

Oznacza to, że prosimy strncat_s o dołączenie trzech znaków do dwóch znaków w buforze o długości pięciu znaków; nie pozostawiłoby to miejsca dla terminatora o wartości null, więc strncat_s zeruje ciąg i wywołuje nieprawidłową procedurę obsługi parametrów.

Jeśli wymagane jest zachowanie obcięcia, należy użyć _TRUNCATE lub odpowiednio dostosować count parametr:

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 jest zakończony znakiem null. Jeśli kopiowanie odbywa się między ciągami nakładającymi się, zachowanie jest niezdefiniowane.

Jeśli strSource wartość lub strDest ma NULLwartość lub numberOfElements jest równa zero, wywoływana jest nieprawidłowa procedura obsługi parametrów, zgodnie z opisem w temacie Weryfikacja parametru . Jeśli wykonywanie jest dozwolone do kontynuowania, funkcja zwraca EINVAL wartość bez modyfikowania jego parametrów.

wcsncat_si _mbsncat_s są wersjami znaków wielobajtowych i wielobajtowych .strncat_s Argumenty ciągu i wartość zwracana wartości wcsncat_s to ciągi wieloznakowe. Argumenty i wartość zwracana wartości to ciągi wielobajtowe _mbsncat_s znaków. Te trzy funkcje zachowują się identycznie inaczej.

Na wartość wyjściową ma wpływ ustawienie LC_CTYPE ustawienia kategorii ustawień regionalnych. W celu uzyskania więcej informacji, zobacz następujący temat: setlocale. Wersje tych funkcji bez sufiksu _l używają bieżących ustawień regionalnych dla tego zachowania zależnego od ustawień regionalnych. Wersje z _l sufiksem są identyczne, z wyjątkiem używania parametru ustawień regionalnych przekazanych w zamian. Aby uzyskać więcej informacji, zobacz Ustawienia regionalne.

W języku C++używanie tych funkcji jest uproszczone przez przeciążenia szablonu; przeciążenia mogą automatycznie wnioskować długość buforu (eliminując konieczność określenia argumentu rozmiaru) i mogą automatycznie zastępować starsze, niezabezpieczone funkcje nowszymi, bezpiecznymi odpowiednikami. Aby uzyskać więcej informacji, zobacz Bezpieczne przeciążenia szablonów.

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

Domyślnie stan globalny tej funkcji jest zakresem aplikacji. Aby zmienić to zachowanie, zobacz Stan globalny w CRT.

Mapowania procedur tekstu ogólnego

Procedura TCHAR.H	`_UNICODE` i `_MBCS` niezdefiniowane	`_MBCS` Zdefiniowane	`_UNICODE` Zdefiniowane
`_tcsncat_s`	`strncat_s`	`_mbsnbcat_s`	`wcsncat_s`
`_tcsncat_s_l`	`_strncat_s_l`	`_mbsnbcat_s_l`	`_wcsncat_s_l`

_strncat_s_l i _wcsncat_s_l nie mają zależności od ustawień regionalnych; są one udostępniane tylko dla _tcsncat_s_l.

Wymagania

Procedura	Wymagany nagłówek
`strncat_s`	<string.h>
`wcsncat_s`	<string.h> lub <wchar.h>
`_mbsncat_s`, `_mbsncat_s_l`	<mbstring.h>

Aby uzyskać więcej informacji 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();
}

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

Zobacz też

Manipulowanie ciągami
ustawienia regionalne
Interpretacja sekwencji znaków wielobajtowych
_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

`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`

Składnia

Parametry

Wartość zwracana

Warunki błędu

Uwagi

Mapowania procedur tekstu ogólnego

Wymagania

Przykład

Zobacz też

Opinia

Opinia

Dodatkowe zasoby

strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l

Składnia

Parametry

Wartość zwracana

Warunki błędu

Uwagi

Mapowania procedur tekstu ogólnego

Wymagania

Przykład

Zobacz też

Opinia

Opinia

Dodatkowe zasoby

`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`