strcat_s, wcscat_s, _mbscat_s

Artykuł
06/09/2015

Dołącza ciąg znaków.Te wersje strcat, wcscat, _mbscat mają wzmocnienia zabezpieczeń, jak opisano w Funkcje zabezpieczeń w CRT.

Ważne
Funkcja _mbscat_s nie może być używana w aplikacjach, które wykonują się w środowisku wykonawczym systemu Windows.Aby uzyskać więcej informacji, zobacz Funkcje CRT nieobsługiwane przez /ZW.

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

Parametry

strDestination
Bufor ciągu docelowego zakończony wartością null.
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, kod błędu.

Warunki błędów

strDestination	numberOfElements	strSource	Wartość zwrócona	ZawartośćstrDestination
NULL lub niezakończony	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 strcat_s dołącza strSource do strDestination i kończy ciąg wynikowy znakiem null.Początkowy charakter strSource zastępuje kończący znak null z strDestination.Zachowanie strcat_s jest niezdefiniowane, jeżeli ciągi źródłowe i docelowe nakładają się.

Zauważ, że drugi parametr to całkowity, a nie pozostały rozmiar buforu:

char buf[16];
strcpy_s(buf, 16, "Start");
strcat_s(buf, 16, " End");               // Correct
strcat_s(buf, 16 – strlen(buf), " End"); // Incorrect

wcscat_s i _mbscat_s są wersjami znaków dwubajtowych i znaków wielobajtowych strcat_s.Argumenty i wartość zwracana przez wcscat_s są ciągami szerokich znaków; te z _mbscat_s są ciągami znaków wielobajtowych.Te trzy funkcje w innych wypadkach zachowują się identycznie.

Jeśli strDestination jest pustym wskaźnikiem albo nie jest zakończony znakiem null lub strSource jest wskaźnikiem NULL albo ciąg docelowy jest za mały, wywołana zostanie obsługa nieprawidłowego parametru, zgodnie z opisem w Sprawdzanie poprawności parametru.Jeśli wykonanie może być kontynuowane, te funkcje zwracają EINVAL i ustawiają errno na EINVAL.

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

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

Rutynowe mapowania zwykłego tekstu