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

Artikel
10/12/2023

Fügt einer Zeichenfolge Zeichen an. Diese Versionen von strncat, , wcsncat_strncat_l, _wcsncat_l, _mbsncathaben _mbsncat_l Sicherheitsverbesserungen, wie in den Sicherheitsfeatures in der CRT beschrieben.

Wichtig

_mbsncat_s und _mbsncat_s_l können nicht in Anwendungen verwendet werden, die in Windows-Runtime ausgeführt werden. Weitere Informationen finden Sie im Artikel CRT functions not supported in Universal Windows Platform apps (In Apps für die universelle Windows-Plattform nicht unterstützte CRT-Funktionen).

Syntax

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

Parameter

strDest
Auf NULL endende Zielzeichenfolge.

numberOfElements
Größe des Zielpuffers.

strSource
Mit NULL endende Quellzeichenfolge.

count
Anzahl der anzufügenden Zeichen oder _TRUNCATE.

locale
Zu verwendendes Gebietsschema.

Rückgabewert

Gibt bei Erfolg 0 (null) zurück und einen Fehlercode, wenn ein Fehler auftritt.

Fehlerbedingungen

`strDestination`	`numberOfElements`	`strSource`	Rückgabewert	Inhalt von `strDestination`
`NULL` oder nicht abgeschlossen	Beliebig	Beliebig	`EINVAL`	nicht geändert
Beliebig	Beliebig	`NULL`	`EINVAL`	nicht geändert
Beliebig	0 oder zu klein	Beliebig	`ERANGE`	nicht geändert

Hinweise

Diese Funktionen versuchen, die ersten D Zeichen von strSource an das Ende von strDest anzufügen, wobei D weniger als count und die Länge von strSource ist. Wenn das Anfügen dieser D Zeichen in strDest das Zeichen passt (dessen Größe angegeben numberOfElementsist) und weiterhin Platz für einen Null-Terminator bleibt, werden diese Zeichen angefügt, beginnend mit dem ursprünglichen Enden null von strDest, und eine neue endende Null wird angefügt. Andernfalls strDest[0] wird auf das Nullzeichen festgelegt, und der ungültige Parameterhandler wird aufgerufen, wie in der Parameterüberprüfung beschrieben.

Es gibt eine Ausnahme für den obigen Absatz. Wenn count dies der Wert ist _TRUNCATE, wird so viel strSource wie passt angefügt strDest , während der Raum bleibt, um eine beendete Null anzufügen.

Ein auf ein Objekt angewendeter

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

bedeutet, dass wir aufgefordert strncat_s werden, drei Zeichen an zwei Zeichen in einem Puffer fünf Zeichen lang anzufügen. Es würde kein Leerzeichen für den Null-Terminator hinterlassen, sodass strncat_s die Zeichenfolge null und der ungültige Parameterhandler aufgerufen wird.

Wenn ein Abschneideverhalten erforderlich ist, verwenden Sie _TRUNCATE, oder passen Sie den count-Parameter entsprechend an:

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

oder

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

In jedem Fall wird die Ergebniszeichenfolge mit einem NULL-Zeichen beendet. Wenn der Kopiervorgang zwischen Zeichenfolgen ausgeführt wird, die sich überschneiden, ist das Verhalten nicht definiert.

Wenn strSource oder strDest ist oder numberOfElements null istNULL, wird der ungültige Parameterhandler aufgerufen, wie in der Parameterüberprüfung beschrieben. Wenn die weitere Ausführung zugelassen wird, gibt die Funktion EINVAL zurück, ohne die Parameter zu ändern.

wcsncat_s und _mbsncat_s sind Breitzeichen- und Multibytezeichenversionen von strncat_s. Die Zeichenfolgenargumente und der Rückgabewert wcsncat_s sind Zeichenfolgen mit breitem Zeichen. Die Argumente und der Rückgabewert sind _mbsncat_s Multibyte-Zeichenfolgen. Diese drei Funktionen verhalten sich andernfalls identisch.

Der Ausgabewert wird durch die Einstellung der LC_CTYPE Kategorieeinstellung des Gebietsschemas beeinflusst. Weitere Informationen finden Sie unter setlocale. Die Versionen dieser Funktionen ohne das _l Suffix verwenden das aktuelle Gebietsschema für dieses gebietsschemaabhängige Verhalten. Die Versionen mit dem _l Suffix sind identisch, mit der Ausnahme, dass sie stattdessen den gebietsschemaparameter verwenden, der übergeben wird. Weitere Informationen finden Sie unter Locale.

In C++ wird die Verwendung dieser Funktionen durch Vorlagenüberladungen vereinfacht; die Überladungen können automatisch Rückschlüsse auf die Pufferlänge ziehen (wodurch kein Größenargument mehr angegeben werden muss), und sie können automatisch die älteren, nicht sicheren Funktionen durch ihre neueren, sicheren Entsprechungen ersetzen. Weitere Informationen finden Sie unter "Sichere Vorlagenüberladungen".

Die Debugbibliotheksversionen dieser Funktionen füllen zuerst den Puffer mit 0xFE. Verwenden Sie _CrtSetDebugFillThresholdzum Deaktivieren dieses Verhaltens .

Standardmäßig gilt der globale Zustand dieser Funktion für die Anwendung. Informationen zum Ändern dieses Verhaltens finden Sie im Global state in the CRT.

Generische Textroutinzuordnungen

TCHAR.H-Routine	`_UNICODE` und `_MBCS` nicht definiert	`_MBCS` Definiert	`_UNICODE` Definiert
`_tcsncat_s`	`strncat_s`	`_mbsnbcat_s`	`wcsncat_s`
`_tcsncat_s_l`	`_strncat_s_l`	`_mbsnbcat_s_l`	`_wcsncat_s_l`

_strncat_s_l und _wcsncat_s_l haben keine Gebietsschemaabhängigkeit; sie werden nur für _tcsncat_s_l.

Anforderungen

Routine	Erforderlicher Header
`strncat_s`	<string.h>
`wcsncat_s`	<string.h> oder <wchar.h>
`_mbsncat_s`, `_mbsncat_s_l`	<mbstring.h>

Weitere Informationen zur Kompatibilität finden Sie unter Kompatibilität.

Beispiel

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

Siehe auch

Zeichenfolgenmanipulation
Gebietsschema
Interpretation von Multibyte-Zeichensequenzen
_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`

Syntax

Parameter

Rückgabewert

Fehlerbedingungen

Hinweise

Generische Textroutinzuordnungen

Anforderungen

Beispiel

Siehe auch

Feedback

Feedback

Zusätzliche Ressourcen

strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l

Syntax

Parameter

Rückgabewert

Fehlerbedingungen

Hinweise

Generische Textroutinzuordnungen

Anforderungen

Beispiel

Siehe auch

Feedback

Feedback

Zusätzliche Ressourcen

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