strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l

Artikel
06/09/2015

Fügt einer Zeichenfolge Zeichen an. Diese Versionen von strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l enthalten Sicherheitserweiterungen wie unter Sicherheitsfunktionen 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 unter CRT-Funktionen nicht mit /ZW unterstützt.

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

[out] strDest
Auf NULL endende Zielzeichenfolge.
[in]numberOfElements
Größe des Zielpuffers.
[in]strSource
Mit NULL endende Quellzeichenfolge.
[in]count
Anzahl der anzufügenden Zeichen oder _TRUNCATE.
[in] 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	any	any	EINVAL	nicht geändert
any	any	NULL	EINVAL	nicht geändert
any	0 oder zu klein	any	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 Anhängen dieser D Zeichen in strDest passt (dessen Größe als numberOfElements angegeben ist) und dennoch Raum für einen NULL-Terminator vorhanden sein soll, werden diese Zeichen angehängt. Dabei ist der Startpunkt die ursprüngliche beendende NULL von strDest, und eine neue beendende NULL wird angehängt. Andernfalls wird strDest[0] auf das NULL-Zeichen festgelegt und der Handler für ungültige Parameter wird, wie in Parametervalidierung beschrieben, ausgelöst.

Zu der oberen Aufführung gibt es eine Ausnahme. Wenn count_TRUNCATE ist, wird so viel wie von strSource passt an strDest angehängt und weiterhin Platz zum Anhängen einer beendenden NULL gelassen.

Beispiel:

char dst[5];

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

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

bedeutet, dass strncat_s zum Anhängen von drei Zeichen an zwei Zeichen in einem fünf Zeichen langen Puffer aufgefordert wird. Dann wäre allerdings kein Platz mehr für den NULL-Terminator vorhanden. Daher weist strncat_s der Zeichenfolge NULL zu und ruft den Handler für ungültige Parameter auf.

Wenn ein Abschneideverhalten erforderlich ist, verwenden Sie _TRUNCATE, oder passen Sie den size-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 strDestNULL ist oder wenn numberOfElements NULL ist, wird, wie in Parametervalidierung beschrieben, der Handler für ungültige Parameter aufgerufen. 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 von wcsncat_s sind Zeichenfolgen mit Breitzeichen; die von _mbsncat_s sind Multibyte-Zeichenfolgen. Diese drei Funktionen verhalten sich andernfalls identisch.

Der Ausgabewert ist von der LC_CTYPE-Kategorieneinstellung des Gebietsschemas betroffen; weitere Informationen finden Sie unter setlocale. Die Versionen dieser Funktionen ohne das _l-Suffix verwenden das aktuelle Gebietsschema für dieses vom Gebietsschema abhängige Verhalten; die Versionen mit dem _l-Suffix sind beinahe identisch, verwenden jedoch stattdessen den ihnen übergebenen Gebietsschemaparameter. 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 Debugversionen dieser Funktionen füllen zunächst den Puffer mit "0xFD" auf. Mit _CrtSetDebugFillThreshold deaktivieren Sie dieses Verhalten.

Zuordnung generischer Textroutinen

TCHAR.H-Routine	_UNICODE & _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 sind nicht gebietsschemaabhängig. Sie werden nur für _tcsncat_s_l bereitgestellt.

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