strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l

Artikel
03/12/2013

Fügen Sie Zeichen in eine Zeichenfolge.Diese sind Versionen von strncat, _strncat_l, wcsncat, wcsncat_l, _mbsncat _mbsncat_l mit Sicherheitserweiterungen, wie in Sicherheitsfeatures im CRT beschrieben.

Wichtig
_mbsncat_s und _mbsncat_s_l können in Anwendungen nicht verwendet werden, die in der Windows Runtime ausführen.Weitere Informationen finden Sie unter CRT-Funktionen unterstützt nicht mit /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

Parameter

[out] strDest
Auf NULL endende Zielzeichenfolge.
[in] numberOfElements
Größe des Zielpuffers.
[in] strSource
Auf NULL endende Quellzeichenfolge.
[in] count
Zahl anzufügen Zeichen oder _TRUNCATE.
[in] locale
Zu verwendende Gebietsschema.

Rückgabewert

Gibt 0 zurück, wenn erfolgreich, ein Fehlercode auf Fehler.

Fehlerbedingungen

strDestination	numberOfElements	strSource	Rückgabewert	Inhalt von strDestination
NULL oder nicht abgeschlossenen	any	any	EINVAL	nicht geändert
any	any	NULL	EINVAL	nicht geändert
any	0 oder zu kleines	any	ERANGE	nicht geändert

Hinweise

Diese Funktionen versuchen, die ersten D Zeichen aus strSource an das Ende von strDest anzufügen, in dem D die kleinere von count und der Länge von strSource ist.Wenn das Anhängen dieser D Zeichen innerhalb strDest (dessen Größe als numberOfElements angegeben ist) und Platz für ein abschließendes noch werden passt, werden diese Zeichen angefügt und beginnen beim ursprünglichen abschließendes NULL-Zeichen von strDest, und ein neues abschließendes NULL-Zeichen wird angefügt; andernfalls wird strDest[0] zum NULL-Zeichen und den ungültigen Parameterhandler aufgerufen wird festgelegt, wie in Parametervalidierung beschrieben.

Es gibt eine Ausnahme an den oben genannten Absatz.Wenn count_TRUNCATE dann so ist, wird ein großer von strSource wie passt, zu strDest beim Platz Anwendungsentwicklern weiterhin, ein abschließendes NULL-Zeichen anzufügen angefügt.

Beispiel:

char dst[5];

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

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

bedeutet, dass wir um strncat_s anfordern, um drei Zeichen bis zwei Zeichen in Zeichen eines Puffers fünf lang anzufügen, dieses würde kein Platz für das NULL-Zeichen, was die strncat_s Nullen standardmäßig die Zeichenfolge und die Aufrufe der ungültige Parameterhandler lassen.

Wenn Abschneidenverhalten erforderlich ist, verwenden Sie _TRUNCATE oder Anpassen des size-Parameter entsprechend:

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

oder

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

In allen Fällen ist die Ergebniszeichenfolge mit einem NULL-Zeichen beendet.Wenn das Kopieren zwischen Zeichenfolgen stattfindet, die sich überschneiden, wird das Verhalten nicht definiert.

Wenn strSource oder strDestNULL ist oder numberOfElements ist null ist, wird der ungültige Parameterhandler aufgerufen, wie in Parametervalidierung beschrieben.Wenn die Ausführung zulässig ist, um fortzufahren, gibt die Funktion EINVAL zurück, ohne die Parameter zu ändern.

wcsncat_s und _mbsncat_s sind Breitzeich und Mehrbytezeichen-Versionen von strncat_s.Die Zeichenfolgenargumente und der Rückgabewert von wcsncat_s sind Breitzeichen-Zeichenfolgen; die von _mbsncat_s sind Mehrbyte-Zeichenfolgen.Diese drei Funktionen verhalten sich andernfalls identisch.

Der Ausgabewert wird durch die Einstellung der LC_CTYPE Kategorieneinstellung des Gebietsschemas betroffen; setlocale finden Sie weitere Informationen.Die Versionen dieser Funktionen ohne das _l Suffix verwenden das aktuelle Gebietsschema für dieses Verhalten abhängig; die Versionen mit dem _l Suffix sind identisch, allerdings verwenden den Gebietsschemaparameter, der in stattdessen übergeben wird.Weitere Informationen finden Sie unter Gebietsschema.

In C++ mithilfe dieser Funktionen wird durch Vorlagenüberladungen vereinfacht; die Überladungen können die Pufferlänge (die Anforderung automatisch beseitigend ableiten, ein Größenargument anzugeben) und können die älteren, nicht-sicheren Funktionen durch ihre späteren, sicheren Entsprechungen automatisch ersetzen.Weitere Informationen finden Sie unter Speichern Sie Vorlagen-Überladungen.

Die Debugversionen dieser Funktionen füllen zuerst den Puffer mit den Wert aus.Um dieses Verhalten zu deaktivieren, verwenden Sie _CrtSetDebugFillThreshold.

Zuordnung generische 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 haben keine Gebietsschemaabhängigkeit; 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>

So zusätzlicher Kompatibilitätsinformation finden Sie unter Kompatibilität in der Einführung.

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