strcpy_s, wcscpy_s, _mbscpy_s

Článek
06/09/2015

Zkopíruje řetězec.Tyto verze strcpy, wcscpy, _mbscpy mají rozšíření zabezpečení popsaná v tématu Funkce zabezpečení v CRT.

Důležité
_mbscpy_s nelze použít v aplikacích, které jsou spuštěny ve prostředí Windows Runtime.Další informace naleznete v tématu CRT funkce nejsou podporovány s /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
Umístění vyrovnávací paměti pro řetězec cílového umístění.
numberOfElements
Velikost vyrovnávací paměti pro řetězec cílového umístění.
strSource
Vyrovnávací paměť pro zdrojový řetězec zakončený hodnotou null.

Vrácená hodnota

Nula v případě úspěchu; jinak chyba.

Chybové podmínky

strDestination	numberOfElements	strSource	Návratová hodnota	Obsah strDestination
NULL	any	any	EINVAL	nezměněno
any	any	NULL	EINVAL	strDestination[0] nastavit na 0
any	0 nebo příliš nízká hodnota	any	ERANGE	strDestination[0] nastavit na 0

Poznámky

Funkce strcpy_s zkopíruje obsah v adrese strSource, včetně ukončujícího nulového znaku do umístění zadaného pomocí parametru strDestination.Cílový řetězec musí být dostatečně velký, aby mohl obsahovat zdrojový řetězec a jeho ukončující znak null.Chování strcpy_s není definováno, pokud se zdrojový a cílový řetězec překrývají.

wcscpy_s je širokoznaká verzí strcpy_s, a _mbscpy_s je vícebajtová znaková verze.Argumenty a vrácené hodnoty wcscpy_s jsou širokoznaké řetězce. Hodnoty _mbscpy_s jsou vícebajtové znakové řetězce.Tyto tři funkce se chovají identicky jinak.

Pokud strDestination nebo strSource je ukazatel s hodnotou null, nebo pokud cílový řetězec je příliš malý, je vyvolána obslužná rutina neplatného parametru, jak je popsáno v Ověření parametru.Pokud provádění může pokračovat, vrátí tyto funkce EINVAL a nastaví errno na EINVAL při strDestination nebo strSource je nulový ukazatel, a vrátí ERANGE a nastaví errno na ERANGE, pokud cílový řetězec je příliš malý.

Po úspěšném spuštění cílového řetězce je vždy je zakončen znakem null.

V jazyce C++ je použití těchto funkcí zjednodušeno díky přetížení šablon, které dokážou odvodit velikost vyrovnávací paměti automaticky tak, že není nutné zadat argument velikosti, a dokážou automaticky nahradit starší, méně zabezpečené funkce jejími novějšími, bezpečnějšími protějšky.Další informace naleznete v tématu Přetížení zabezpečení šablony.

Ladicí verze těchto funkcí nejprve naplní vyrovnávací paměť hodnotou 0xFE.Chcete-li zakázat toto chování, použijte _CrtSetDebugFillThreshold.

Rutinní mapování obecného textu

Rutina TCHAR.H	_UNICODE & _MBCS není definováno	_MBCS definováno	_UNICODE definováno
_tcscpy_s	strcpy_s	_mbscpy_s	wcscpy_s

Požadavky

Rutina	Požadované záhlaví
strcpy_s	<string.h>
wcscpy_s	<string.h> nebo <wchar.h>
_mbscpy_s	<mbstring.h>

Další informace o kompatibilitě naleznete v tématu Kompatibilita.

Příklad

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