`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`

Artikel
10/12/2023

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

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`	Beliebig	Beliebig	`EINVAL`	nicht geändert
Beliebig	Beliebig	`NULL`	`EINVAL`	`strDest[0]`, auf 0 festgelegt.
Beliebig	0	Beliebig	`EINVAL`	nicht geändert
nicht `NULL`	zu klein	Beliebig	`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.

Ein auf ein Objekt angewendeter

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 "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
`_tcsncpy_s`	`strncpy_s`	`_mbsnbcpy_s`	`wcsncpy_s`
`_tcsncpy_s_l`	`_strncpy_s_l`	`_mbsnbcpy_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

Zeichenfolgenmanipulation
Gebietsschema
Interpretation von Multibyte-Zeichensequenzen
_mbsnbcpy, _mbsnbcpy_l
strcat_s, wcscat_s, _mbscat_s
strcmp, wcscmp, _mbscmp
strcpy_s, wcscpy_s, _mbscpy_s
strncat_s, _strncat_s_l, wcsncat_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

`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`

Syntax

Parameter

Rückgabewert

Fehlerbedingungen

Hinweise

Generische Textroutinzuordnungen

Anforderungen

Beispiel: Kopieren von Zeichen in einen Puffer

Beispiel: `strncpy` und `strncpy_s`

Siehe auch

Feedback

Feedback

Zusätzliche Ressourcen

strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l

Syntax

Parameter

Rückgabewert

Fehlerbedingungen

Hinweise

Generische Textroutinzuordnungen

Anforderungen

Beispiel: Kopieren von Zeichen in einen Puffer

Beispiel: strncpy und strncpy_s

Siehe auch

Feedback

Feedback

Zusätzliche Ressourcen

`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`

Beispiel: `strncpy` und `strncpy_s`