strcpy_s, wcscpy_s, _mbscpy_s

Artikel
06/09/2015

Kopiert eine Zeichenfolge. Diese Versionen von strcpy, wcscpy, _mbscpy enthalten Sicherheitserweiterungen wie unter Sicherheitsfunktionen in der CRT beschrieben.

Wichtig

_mbscpy_s kann in Anwendungen nicht verwendet werden, die im Windows-Runtime ausgeführt werden.Weitere Informationen finden Sie unter CRT-Funktionen nicht mit /ZW unterstützt.

errno_t strcpy_s(
   char *strDestination,
   size_t numberOfElements,
   const char *strSource 
);
errno_t wcscpy_s(
   wchar_t *strDestination,
   size_t numberOfElements,
   const wchar_t *strSource 
);
errno_t _mbscpy_s(
   unsigned char *strDestination,
   size_t numberOfElements,
   const unsigned char *strSource 
);
template <size_t size>
errno_t strcpy_s(
   char (&strDestination)[size],
   const char *strSource 
); // C++ only
template <size_t size>
errno_t wcscpy_s(
   wchar_t (&strDestination)[size],
   const wchar_t *strSource 
); // C++ only
template <size_t size>
errno_t _mbscpy_s(
   unsigned char (&strDestination)[size],
   const unsigned char *strSource 
); // C++ only

Parameter

strDestination
Speicherort des Zielzeichenfolgenpuffers.
numberOfElements
Größe des Zielzeichenfolgenpuffers.
strSource
Auf NULL endender Quellzeichenfolgepuffer.

Rückgabewert

Null (0), wenn erfolgreich; andernfalls ein Fehler.

Fehlerbedingungen

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

Hinweise

Die strcpy_s-Funktion kopiert den Inhalt der Adresse von strSource, einschließlich des abschließenden NULL-Zeichens, an den Speicherort, der von strDestination angegeben wird. Die Zielzeichenfolge muss groß genug sein, um die Quellzeichenfolge und ihr beendendes NULL-Zeichen zu enthalten. Wenn sich Quell- und Zielzeichenfolgen überlappen, ist das Verhalten von strcpy_s undefiniert.

wcscpy_s ist die Breitzeichen-Version von strcpy_s, und _mbscpy_s ist die Mehrbytezeichen-Version. Die Argumente und der Rückgabewert von wcscpy_s sind Breitzeichen-Zeichenfolgen; die von _mbscpy_s sind Mehrbyte-Zeichenfolgen. Diese drei Funktionen verhalten sich andernfalls identisch.

Wenn strDestination oder strSource ein NULL-Zeiger ist oder die Zielzeichenfolge zu klein ist, wird der ungültige Parameterhandler, wie in Parametervalidierung beschrieben, aufgerufen. Wenn die Ausführung fortgesetzt werden darf, geben diese Funktionen EINVAL zurück und legen errno auf EINVAL fest, wenn strDestination oder strSource ein NULL-Zeiger ist und sie ERANGE zurückgeben und errno auf ERANGE festlegen, wenn die Zielzeichenfolge zu klein ist.

Nach erfolgreicher Ausführung endet die Zielzeichenfolge immer auf NULL.

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, weniger sicheren Funktionen durch ihre neueren, sichereren Entsprechungen ersetzen. Weitere Informationen finden Sie unter Sichere Vorlagenüberladungen.

Die Debugversionen dieser Funktionen füllen zunächst den Puffer mit "0xFE" auf. Mit _CrtSetDebugFillThreshold deaktivieren Sie dieses Verhalten.

Zuordnung generischer Textroutinen

TCHAR.H-Routine	_UNICODE & _MBCS nicht definiert	_MBCS definiert	_UNICODE definiert
_tcscpy_s	strcpy_s	_mbscpy_s	wcscpy_s

Anforderungen

Routine	Erforderlicher Header
strcpy_s	<string.h>
wcscpy_s	<string.h> oder <wchar.h>
_mbscpy_s	<mbstring.h>

Zusätzliche Informationen zur Kompatibilität finden Sie unter Kompatibilität.

Beispiel

// crt_strcpy_s.cpp
// This program uses strcpy_s and strcat_s
// to build a phrase.
//

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

int main( void )
{
   char string[80];
   // using template versions of strcpy_s and strcat_s:
   strcpy_s( string, "Hello world from " );
   strcat_s( string, "strcpy_s " );
   strcat_s( string, "and " );
   // of course we can supply the size explicitly if we want to:
   strcat_s( string, _countof(string), "strcat_s!" );
   
   printf( "String = %s\n", string );
}