Freigeben über

strcpy_s, , wcscpy_s_mbscpy_s_mbscpy_s_l

  • Artikel

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 any any EINVAL nicht geändert
any any NULL EINVAL dest[0], auf 0 festgelegt.
any 0 oder zu klein any 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 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.

Mapping generischer Textroutinen

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

Zeichenfolgenbearbeitung
strcat, , wcscat_mbscat_mbscat_l
strcmp, , wcscmp_mbscmp_mbscmp_l
strncat_s, , _strncat_s_lwcsncat_s, _wcsncat_s_l, , _mbsncat_s_mbsncat_s_l
strncmp, , wcsncmp_mbsncmp_mbsncmp_l
strncpy_s, , _strncpy_s_lwcsncpy_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