strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l

 

Veröffentlicht: Juli 2016

Die neueste Dokumentation zu Visual Studio 2017 finden Sie unter Dokumentation zu Visual Studio 2017.

Fügt einer Zeichenfolge Zeichen an. Diese Versionen von Strncat, _strncat_l, Wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l wurde die Sicherheit wie unter Sicherheitsfunktionen in der CRT.

System_CAPS_ICON_important.jpg 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 In /ZW nicht unterstützte CRT-Funktionen.

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.

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

Fehlerbedingungen

strDestinationnumberOfElementsstrSourceRückgabewertInhalt von strDestination
NULL oder nicht abgeschlossenanyalleEINVALnicht geändert
anyalleNULLEINVALnicht geändert
any0 oder zu kleinalleERANGEnicht geändert

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 die Anfügen D Zeichen passt in strDest (vergeben, deren Größe numberOfElements) und noch Platz für eine null-Terminator und dann diese Zeichen beginnend mit der ursprünglichen Beenden von null angehängt werden, strDest, und ein neues abschließendes Null ist, angehängt ist, andernfalls strDest[0] festgelegt ist das Null-Zeichen und der ungültige Parameter Handler aufgerufen, wie in beschrieben Parametervalidierungsfunktionen.

Zu der oberen Aufführung gibt es eine Ausnahme. Wenn count ist _TRUNCATE wird so viel von strSource wie passt angehängt strDest wobei noch Platz zum Anhängen einer beendenden null.

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 strDest ist NULL, oder numberOfElements&0; ist, wird der Handler für ungültige Parameter aufgerufen, wie in beschrieben Parametervalidierungsfunktionen . 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 Breitzeichen-Zeichenfolgen, die von _mbsncat_s sind Multibyte Zeichenfolgen. Diese drei Funktionen verhalten sich andernfalls identisch.

Der Ausgabewert wird durch die Einstellung beeinflusst die LC_CTYPE -kategorieneinstellung des Gebietsschemas, siehe Setlocale Weitere Informationen. 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 Secure Template Overloads.

Die Debugversionen dieser Funktionen füllen zunächst den Puffer mit "0xFD" auf. Um dieses Verhalten zu deaktivieren, verwenden Sie _CrtSetDebugFillThreshold.

Zuordnung generischer Textroutinen

TCHAR.H-Routine_UNICODE und _MBCS nicht definiert._MBCS definiert_UNICODE definiert
_tcsncat_sstrncat_s_mbsnbcat_swcsncat_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.

RoutineErforderlicher 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.

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

System::String::concat

Zeichenfolgenbearbeitung
Gebietsschema
Interpretation von Multibyte-Zeichenfolgen
_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

Anzeigen: