strcpy_s, , wcscpy_s, , _mbscpy_s_mbscpy_s_l

Kopiuje ciąg. Te wersje programu wcscpy_mbscpystrcpy, mają ulepszenia zabezpieczeń zgodnie z opisem w temacie Funkcje zabezpieczeń w narzędziu CRT.

Składnia

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

Parametry

dest
Lokalizacja buforu ciągu docelowego.

dest_size
Rozmiar buforu ciągu docelowego w char jednostkach dla wąskich i wielobajtowych funkcji oraz wchar_t jednostek dla szerokich funkcji. Ta wartość musi być większa niż zero i nie większa niż RSIZE_MAX. Upewnij się, że ten rozmiar odpowiada za kończeniem NULL ciągu.

src
Bufor ciągu źródłowego zakończony o wartości null.

locale
Ustawienia regionalne do użycia.

Wartość zwracana

Zero w przypadku powodzenia; w przeciwnym razie błąd.

Warunki błędu

Uwagi

Funkcja strcpy_s kopiuje zawartość w adresie src, w tym znak null zakończenia, do lokalizacji określonej przez dest. Ciąg docelowy musi być wystarczająco duży, aby przechowywać ciąg źródłowy i jego kończący znak null. Zachowanie elementu strcpy_s jest niezdefiniowane, jeśli ciągi źródłowe i docelowe nakładają się na siebie.

wcscpy_s jest wersją wielobajtową typu strcpy_s, a _mbscpy_s jest wersją wielobajtową. Argumenty to wcscpy_s ciągi o szerokim znaku. Argumenty i są ciągami wielobajtowymi _mbscpy_s _mbscpy_s_l znaków. Te funkcje zachowują się identycznie inaczej. _mbscpy_s_l jest identyczny z _mbscpy_s tą różnicą, że używa parametru ustawień regionalnych przekazanych zamiast bieżących ustawień regionalnych. Aby uzyskać więcej informacji, zobacz locale.

Jeśli dest lub src jest wskaźnikiem o wartości null lub jeśli rozmiar dest_size ciągu docelowego jest zbyt mały, wywoływana jest nieprawidłowa procedura obsługi parametrów, zgodnie z opisem w temacie Weryfikacja parametrów. Jeśli wykonywanie jest dozwolone do kontynuowania, te funkcje zwracają EINVAL i ustawiają wartość EINVAL errno , gdy dest lub src jest wskaźnikiem o wartości null, a następnie zwracają ERANGE i ustawiają wartość errno , ERANGE gdy ciąg docelowy jest zbyt mały.

Po pomyślnym wykonaniu ciąg docelowy jest zawsze zakończony wartością null.

W języku C++użycie tych funkcji jest uproszczone przez przeciążenia szablonów, które mogą automatycznie wnioskować długość buforu, dzięki czemu nie trzeba określać argumentu rozmiaru. Ponadto mogą automatycznie zastępować starsze, mniej bezpieczne funkcje nowszymi, bardziej bezpiecznymi odpowiednikami. Aby uzyskać więcej informacji, zobacz Bezpieczne przeciążenia szablonów.

Wersje biblioteki debugowania tych funkcji najpierw wypełniają bufor 0xFE. Aby wyłączyć to zachowanie, użyj polecenia _CrtSetDebugFillThreshold.

Domyślnie stan globalny tej funkcji jest zakresem aplikacji. Aby zmienić to zachowanie, zobacz Stan globalny w CRT.

Mapowania procedur tekstu ogólnego

Wymagania

Te funkcje są specyficzne dla firmy Microsoft. Aby uzyskać więcej informacji o zgodności, zobacz Zgodność.

Przykład

W przeciwieństwie do kodu jakości produkcyjnej ten przykład wywołuje funkcje bezpiecznego ciągu bez sprawdzania błędów:

// 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!

Podczas kompilowania kodu C++ wersje szablonów mogą być łatwiejsze w użyciu.

// 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!

Zobacz też

Manipulowanie ciągami
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