strcpy_s, wcscpy_s, _mbscpy_s, _mbscpy_s_l

Kopiert eine Zeichenfolge. Diese Versionen von strcpy, wcscpy_mbscpy haben Sicherheitsverbesserungen, wie in sicherheitsfeatures im CRT beschrieben.

Wichtig

_mbscpy_s und _mbscpy_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 strcpy_s(
   char *dest,
   rsize_t dest_size,
   const char *src
);
errno_t wcscpy_s(
   wchar_t *dest,
   rsize_t dest_size,
   const wchar_t *src
);
errno_t _mbscpy_s(
   unsigned char *dest,
   rsize_t dest_size,
   const unsigned char *src
);
errno_t _mbscpy_s_l(
   unsigned char *dest,
   rsize_t dest_size,
   const unsigned char *src,
   _locale_t locale
);

// Template functions are C++ only:
template <size_t size>
errno_t strcpy_s(
   char (&dest)[size],
   const char *src
); // C++ only
template <size_t size>
errno_t wcscpy_s(
   wchar_t (&dest)[size],
   const wchar_t *src
); // C++ only
template <size_t size>
errno_t _mbscpy_s(
   unsigned char (&dest)[size],
   const unsigned char *src
); // C++ only
template <size_t size>
errno_t _mbscpy_s_l(
   unsigned char (&dest)[size],
   const unsigned char *src,
   _locale_t locale
); // C++ only

Parameter

dest
Speicherort des Zielzeichenfolgenpuffers.

dest_size
Größe des Zielzeichenfolgenpuffers in char Einheiten für schmale und Multi-Byte-Funktionen und wchar_t Einheiten für große Funktionen. Dieser Wert muss größer als Null und nicht größer als sein RSIZE_MAX. Stellen Sie sicher, dass diese Größe dem Beenden NULL nach der Zeichenfolge entspricht.

src
Auf NULL endender Quellzeichenfolgepuffer.

locale
Zu verwendendes Gebietsschema.

Rückgabewert

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

Fehlerbedingungen

dest	dest_size	src	Rückgabewert	Inhalt von dest
NULL	Beliebig	Beliebig	EINVAL	nicht geändert
Beliebig	Beliebig	NULL	EINVAL	dest[0], auf 0 festgelegt.
Beliebig	0 oder zu klein	Beliebig	ERANGE	dest[0], auf 0 festgelegt.

Hinweise

Die strcpy_s-Funktion kopiert den Inhalt der Adresse von src, einschließlich des abschließenden NULL-Zeichens, an den Speicherort, der von dest 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. Bei den Argumenten handelt es wcscpy_s sich um Zeichenfolgen mit breitem Zeichen. Die Argumente von _mbscpy_s und _mbscpy_s_l sind Multibyte-Zeichenfolgen. Anderenfalls verhalten sich diese Funktionen identisch. _mbscpy_s_l ist identisch mit _mbscpy_s der Ausnahme, dass der gebietsschemaparameter verwendet wird, der anstelle des aktuellen Gebietsschemas übergeben wird. Weitere Informationen finden Sie unter locale.

Wenn dest es sich um einen NULL-Zeiger handelt oder src die Größe der Zielzeichenfolge dest_size zu klein ist, wird der ungültige Parameterhandler aufgerufen, wie in der Parameterüberprüfung beschrieben. Wenn die Ausführung fortgesetzt werden darf, geben diese Funktionen EINVAL zurück und legen errno auf EINVAL fest, wenn dest oder src 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 die Pufferlänge automatisch ableiten können, sodass Sie kein Größenargument angeben müssen. Und sie können ältere, weniger sichere Funktionen automatisch durch neuere, sicherere Gegenstücke 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
_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>

Diese Funktionen sind microsoftspezifisch. Weitere Informationen zur Kompatibilität finden Sie unter Kompatibilität.

Beispiel

Im Gegensatz zu Produktionsqualitätscode ruft dieses Beispiel die Funktionen für sichere Zeichenfolgen auf, ohne auf Fehler zu prüfen:

// crt_strcpy_s.c
// Compile by using: cl /W4 crt_strcpy_s.c
// This program uses strcpy_s and strcat_s
// to build a phrase.

#include <string.h>     // for strcpy_s, strcat_s
#include <stdlib.h>     // for _countof
#include <stdio.h>      // for printf
#include <errno.h>      // for return values

int main(void)
{
    char stringBuffer[80];

    strcpy_s(stringBuffer, _countof(stringBuffer), "Hello world from ");
    strcat_s(stringBuffer, _countof(stringBuffer), "strcpy_s ");
    strcat_s(stringBuffer, _countof(stringBuffer), "and ");
    strcat_s(stringBuffer, _countof(stringBuffer), "strcat_s!");

    printf("stringBuffer = %s\n", stringBuffer);
}

stringBuffer = Hello world from strcpy_s and strcat_s!

Wenn Sie C++-Code erstellen, sind die Vorlagenversionen möglicherweise einfacher zu verwenden.

// crt_wcscpy_s.cpp
// Compile by using: cl /EHsc /W4 crt_wcscpy_s.cpp
// This program uses wcscpy_s and wcscat_s
// to build a phrase.

#include <cstring>  // for wcscpy_s, wcscat_s
#include <cstdlib>  // for _countof
#include <iostream> // for cout, includes <cstdlib>, <cstring>
#include <errno.h>  // for return values

int main(void)
{
    wchar_t stringBuffer[80];
    // using template versions of wcscpy_s and wcscat_s:
    wcscpy_s(stringBuffer, L"Hello world from ");
    wcscat_s(stringBuffer, L"wcscpy_s ");
    wcscat_s(stringBuffer, L"and ");
    // of course we can supply the size explicitly if we want to:
    wcscat_s(stringBuffer, _countof(stringBuffer), L"wcscat_s!");

    std::wcout << L"stringBuffer = " << stringBuffer << std::endl;
}

stringBuffer = Hello world from wcscpy_s and wcscat_s!

Siehe auch

Zeichenfolgenmanipulation
strcat, wcscat, _mbscat, _mbscat_l
strcmp, wcscmp, _mbscmp, _mbscmp_l
strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l
strncmp, wcsncmp, _mbsncmp, _mbsncmp_l
strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l
_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l
strrchr, wcsrchr, _mbsrchr, _mbsrchr_l
strspn, wcsspn, _mbsspn, _mbsspn_l