strncpy_s, _strncpy_s_l, , _wcsncpy_s_lwcsncpy_s, _mbsncpy_s, _mbsncpy_s_l, _tcsncpy_s, , , _tcsncpy_s_l, , _tcsnccpy_s_tcsnccpy_s_l

Kopiert Zeichen aus einer Zeichenfolge in eine andere. Diese Versionen von strncpy, , wcsncpy_strncpy_l, _wcsncpy_l, _mbsncpyhaben _mbsncpy_l Sicherheitsverbesserungen, wie in den Sicherheitsfeatures in der CRT beschrieben.

Wichtig

_mbsncpy_s und _mbsncpy_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).

For _tcsnccpy_s, _tcsnccpy_s_l, , _tcsnccpy_sand _tcsnccpy_s_l see Generic-text function mappings.

Syntax

errno_t strncpy_s(
   char *strDest,
   size_t numberOfElements,
   const char *strSource,
   size_t count
);
errno_t _strncpy_s_l(
   char *strDest,
   size_t numberOfElements,
   const char *strSource,
   size_t count,
   _locale_t locale
);
errno_t wcsncpy_s(
   wchar_t *strDest,
   size_t numberOfElements,
   const wchar_t *strSource,
   size_t count
);
errno_t _wcsncpy_s_l(
   wchar_t *strDest,
   size_t numberOfElements,
   const wchar_t *strSource,
   size_t count,
   _locale_t locale
);
errno_t _mbsncpy_s(
   unsigned char *strDest,
   size_t numberOfElements,
   const unsigned char *strSource,
   size_t count
);
errno_t _mbsncpy_s_l(
   unsigned char *strDest,
   size_t numberOfElements,
   const unsigned char *strSource,
   size_t count,
   _locale_t locale
);
template <size_t size>
errno_t strncpy_s(
   char (&strDest)[size],
   const char *strSource,
   size_t count
); // C++ only
template <size_t size>
errno_t _strncpy_s_l(
   char (&strDest)[size],
   const char *strSource,
   size_t count,
   _locale_t locale
); // C++ only
template <size_t size>
errno_t wcsncpy_s(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count
); // C++ only
template <size_t size>
errno_t _wcsncpy_s_l(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count,
   _locale_t locale
); // C++ only
template <size_t size>
errno_t _mbsncpy_s(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count
); // C++ only
template <size_t size>
errno_t _mbsncpy_s_l(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count,
   _locale_t locale
); // C++ only

Parameter

strDest
Zielzeichenfolge.

numberOfElements
Die Größe der Zielzeichenfolge in Zeichen.

strSource
Quellzeichenfolge.

count
Anzahl der zu kopierenden Zeichen oder _TRUNCATE.

locale
Das zu verwendende Gebietsschema.

Rückgabewert

Null wenn erfolgreich, STRUNCATE bei abgeschnittenen Daten, andernfalls ein Fehlercode.

Fehlerbedingungen

strDest	numberOfElements	strSource	Rückgabewert	Inhalt von strDest
NULL	any	any	EINVAL	nicht geändert
any	any	NULL	EINVAL	strDest[0], auf 0 festgelegt.
any	0	any	EINVAL	nicht geändert
nicht NULL	zu klein	any	ERANGE	strDest[0], auf 0 festgelegt.

Hinweise

Diese Funktionen versuchen, die ersten D-Zeichen aus strSource nach strDest zu kopieren. D ist dabei geringer an count und die Länge von strSource. Wenn diese D Zeichen in strDest die Zeichen passen (deren Größe angegeben numberOfElementsist) und weiterhin Platz für einen Null-Terminator hinterlassen, werden diese Zeichen kopiert und eine endende Null angefügt. Andernfalls strDest[0] wird 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. Ist count dies _TRUNCATEder Grund, wird so viel strSource kopiert, wie es hineinpasst strDest , während noch Platz für das beendende Null bleibt, was immer angefügt wird.

Beispiel:

char dst[5];
strncpy_s(dst, 5, "a long string", 5);

bedeutet, dass strncpy_s fünf Zeichen in einen 5-Byte-Puffer kopiert werden. Diese Kopie würde keinen Leerraum für den Null-Terminator hinterlassen, sodass strncpy_s die Zeichenfolge null ist und der ungültige Parameterhandler aufgerufen wird.

Wenn das Abschneiden erforderlich ist, verwenden _TRUNCATE Oder (size - 1):

strncpy_s(dst, 5, "a long string", _TRUNCATE);
strncpy_s(dst, 5, "a long string", 4);

Im Gegensatz dazu strncpy, wenn count die Länge größer als die Länge ist strSource, wird die Zielzeichenfolge NICHT mit NULL-Zeichen bis zur Länge countaufgefüllt.

Wenn sich Quell- und Zielzeichenfolgen überlappen, ist das Verhalten von strncpy_s undefiniert.

Wenn strDest oder strSource oder NULL ist oder numberOfElements 0 ist, wird der Handler für ungültige Parameter aufgerufen. Wenn die weitere Ausführung zugelassen wird, gibt die Funktion EINVAL zurück und setzt errno auf EINVAL.

wcsncpy_s und _mbsncpy_s sind Breitzeichen- und Multibytezeichenversionen von strncpy_s. Die Argumente und der Rückgabewert von wcsncpy_s und mbsncpy_s variieren entsprechend. Diese sechs 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 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 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. Wie Sie dieses Verhalten ändern, erfahren Sie unter Globaler Status in der CRT.

Zuordnungen generischer Textfunktionen

Die Funktion in der tchar.h Spalte ist der Funktion in den anderen Spalten abhängig von dem Zeichensatz zugeordnet, der zur Kompilierungszeit definiert ist.

tchar.h-Routine	_UNICODE und _MBCS nicht definiert	_MBCS definiert	_UNICODE definiert
_tcsncpy_s	strncpy_s	_mbsnbcpy_s	wcsncpy_s
_tcsncpy_s_l	_strncpy_s_l	_mbsnbcpy_s_l	_wcsncpy_s_l
_tcsnccpy_s	strncpy_s	_mbsncpy_s	_wcsncpy_s
_tcsnccpy_s_l	_strncpy_s_l	_mbsncpy_s_l	_wcsncpy_s_l

Hinweis

_strncpy_s_lund _wcsncpy_s_l _mbsncpy_s_l haben keine Gebietsschemaabhängigkeit. Sie werden nur für _tcsncpy_s_l sie bereitgestellt und sollen nicht direkt aufgerufen werden.

Anforderungen

Routine	Erforderlicher Header
strncpy_s, _strncpy_s_l	<string.h>
wcsncpy_s, _wcsncpy_s_l	<string.h> oder <wchar.h>
_mbsncpy_s, _mbsncpy_s_l	<mbstring.h>

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

Beispiel: Kopieren von Zeichen in einen Puffer

// crt_strncpy_s_1.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 strncpy_s_tester( const char * src,
                          int count )
{
   char dest[10];

   printf( "\n" );

   if ( count == _TRUNCATE )
      printf( "Copying '%s' to %d-byte buffer dest with truncation semantics\n",
               src, _countof(dest) );
   else
      printf( "Copying %d chars of '%s' to %d-byte buffer dest\n",
              count, src, _countof(dest) );

   errno_t err = strncpy_s( dest, _countof(dest), src, count );

   printf( "    new contents of dest: '%s'\n", dest );

   return err;
}

void Examples()
{
   strncpy_s_tester( "howdy", 4 );
   strncpy_s_tester( "howdy", 5 );
   strncpy_s_tester( "howdy", 6 );

   printf( "\nDestination buffer too small:\n" );
   strncpy_s_tester( "Hi there!!", 10 );

   printf( "\nTruncation examples:\n" );

   errno_t err = strncpy_s_tester( "How do you do?", _TRUNCATE );
   printf( "    truncation %s occur\n", err == STRUNCATE ? "did"
                                                       : "did not" );

   err = strncpy_s_tester( "Howdy.", _TRUNCATE );
   printf( "    truncation %s occur\n", err == STRUNCATE ? "did"
                                                       : "did not" );

   printf( "\nSecure template overload example:\n" );

   char dest[10];
   strncpy( dest, "very very very long", 15 );
   // With secure template overloads enabled (see #defines at
   // top of file), the preceding line is replaced by
   //    strncpy_s( dest, _countof(dest), "very very very long", 15 );
   // Instead of causing a buffer overrun, strncpy_s invokes
   // the invalid parameter handler.
   // If secure template overloads were disabled, strncpy would
   // copy 15 characters and overrun the dest buffer.
   printf( "    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(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();
}

Copying 4 chars of 'howdy' to 10-byte buffer dest
    new contents of dest: 'howd'

Copying 5 chars of 'howdy' to 10-byte buffer dest
    new contents of dest: 'howdy'

Copying 6 chars of 'howdy' to 10-byte buffer dest
    new contents of dest: 'howdy'

Destination buffer too small:

Copying 10 chars of 'Hi there!!' to 10-byte buffer dest
Invalid parameter handler invoked: (L"Buffer is too small" && 0)
    new contents of dest: ''

Truncation examples:

Copying 'How do you do?' to 10-byte buffer dest with truncation semantics
    new contents of dest: 'How do yo'
    truncation did occur

Copying 'Howdy.' to 10-byte buffer dest with truncation semantics
    new contents of dest: 'Howdy.'
    truncation did not occur

Secure template overload example:
Invalid parameter handler invoked: (L"Buffer is too small" && 0)
    new contents of dest: ''

Beispiel: strncpy und strncpy_s

// crt_strncpy_s_2.c
// contrasts strncpy and strncpy_s

#include <stdio.h>
#include <stdlib.h>

int main( void )
{
   char a[20] = "test";
   char s[20];

   // simple strncpy usage:

   strcpy_s( s, 20, "dogs like cats" );
   printf( "Original string:\n   '%s'\n", s );

   // Here we can't use strncpy_s since we don't
   // want null termination
   strncpy( s, "mice", 4 );
   printf( "After strncpy (no null-termination):\n   '%s'\n", s );
   strncpy( s+5, "love", 4 );
   printf( "After strncpy into middle of string:\n   '%s'\n", s );

   // If we use strncpy_s, the string is terminated
   strncpy_s( s, _countof(s), "mice", 4 );
   printf( "After strncpy_s (with null-termination):\n   '%s'\n", s );

}

Original string:
   'dogs like cats'
After strncpy (no null-termination):
   'mice like cats'
After strncpy into middle of string:
   'mice love cats'
After strncpy_s (with null-termination):
   'mice'

Siehe auch

Zeichenfolgenbearbeitung
Gebietsschema
Interpretation von Multibytezeichensequenzen
_mbsnbcpy, _mbsnbcpy_l
strcat_s, wcscat_s_mbscat_s
strcmp, wcscmp_mbscmp
strcpy_s, wcscpy_s_mbscpy_s
strncat_s, , _strncat_s_lwcsncat_s, _wcsncat_s_l, , _mbsncat_s_mbsncat_s_l
strncmp, , wcsncmp_mbsncmp_mbsncmp_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