strcpy_s, wcscpy_s, _mbscpy_s

Artykuł
06/09/2015

Kopiuje ciąg.Te wersje strcpy, wcscpy, _mbscpy mają wzmocnienia zabezpieczeń, jak opisano w Funkcje zabezpieczeń w CRT.

Ważne
_mbscpy_s nie można używać w aplikacji, których wykonywanie w Środowisko wykonawcze systemu Windows.Aby uzyskać więcej informacji, zobacz Funkcje CRT nieobsługiwane przez /ZW.

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

Parametry

strDestination
Lokalizacja buforu ciągu miejsca docelowego.
numberOfElements
Rozmiar buforu ciągu miejsca docelowego.
strSource
Bufor ciągu źródła zakończony znakiem null.

Wartość zwracana

Zero, jeśli operacja się powiedzie; w przeciwnym razie, błąd.

Warunki błędów

strDestination	numberOfElements	strSource	Wartość zwrócona	ZawartośćstrDestination
NULL	jakakolwiek	jakakolwiek	EINVAL	nie zmodyfikowano
jakakolwiek	jakakolwiek	NULL	EINVAL	strDestination[0] ustawiony na 0
jakakolwiek	0 lub zbyt mały	jakakolwiek	ERANGE	strDestination[0] ustawiony na 0

Uwagi

Funkcja strcpy_s kopiuje zawartość adresu w strSource, łącznie z końcowym znakiem zerowym, do lokalizacji określonej przez strDestination.Ciąg docelowy musi być wystarczająco duży, aby pomieścić ciąg źródłowy i kończący go znak null.Zachowanie strcpy_s jest niezdefiniowane, jeżeli ciągi źródłowe i docelowe nakładają się.

wcscpy_s w wersji ze znakami dwubajtowymi strcpy_s, i _mbscpy_s jest wersją znaków wielobajtowych.Argumenty i wartość zwracana przez wcscpy_s są ciągami szerokich znaków; te z _mbscpy_s są ciągami znaków wielobajtowych.Te trzy funkcje w innych wypadkach zachowują się identycznie.

Jeśli wskaźnik strDestination lub strSource ma wartość null lub jeśli ciąg docelowy jest zbyt krótki, zostanie wywołany nieprawidłowy parametr uchwytu, zgodnie z opisem w Sprawdzanie poprawności parametru.Jeśli wykonanie może być kontynuowane, te funkcje zwracają EINVAL i ustawiają errno na EINVAL, kiedy strDestination lub strSource jest wskaźnikiem o wartości null, a także zwracają ERANGE i ustawiają errno na ERANGE, kiedy ciąg docelowy jest za krótki.

Przy pomyślnym wykonaniu, ciąg miejsca docelowego zawsze zakończony jest znakiem null.

W języku programowania C++ korzystanie z tych funkcji jest uproszczone przez przeciążania szablonu, które mogą automatycznie wywnioskować długość buforu tak, aby nie było konieczne określenie argumentu rozmiaru; ponadto, funkcje te mogą automatycznie zastąpić starsze, mniej bezpieczne funkcje nowszymi, bardziej bezpiecznymi odpowiednikami.Aby uzyskać więcej informacji, zobacz Przeciążenia bezpiecznych szablonów.

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

Rutynowe mapowania zwykłego tekstu

Procedura Tchar.h	_UNICODE & _MBCS nie zdefiniowano	_MBCS zdefiniowano	_UNICODE zdefiniowany
_tcscpy_s	strcpy_s	_mbscpy_s	wcscpy_s

Wymagania

Procedura	Wymagany nagłówek
strcpy_s	<Ciąg>
wcscpy_s	<ciągo.h> lub <wchar.h>
_mbscpy_s	<mbCiąg.h>

Dodatkowe informacje o zgodności – zobacz: Zgodność.

Przykład

// 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 );
}