strcpy_s, wcscpy_s, _mbscpy_s, _mbscpy_s_l

Zkopíruje řetězec. Tyto verze strcpy, wcscpymají _mbscpy vylepšení zabezpečení, jak je popsáno v funkcích zabezpečení v CRT.

Důležité

_mbscpy_sa _mbscpy_s_l nelze je použít v aplikacích, které se spouští v prostředí Windows Runtime. Další informace najdete v tématu Funkce CRT, které nejsou v aplikacích Univerzální platforma Windows podporované.

Syntaxe

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
Umístění vyrovnávací paměti cílového řetězce.

dest_size
Velikost vyrovnávací paměti cílového řetězce v char jednotkách pro úzké a více bajtové funkce a wchar_t jednotky pro široké funkce. Tato hodnota musí být větší než nula a nesmí být větší než RSIZE_MAX. Ujistěte se, že tato velikost odpovídá ukončení NULL za řetězcem.

src
Vyrovnávací paměť zdrojového řetězce s ukončenou hodnotou null.

locale
Národní prostředí, které se má použít.

Vrácená hodnota

Nula v případě úspěchu; v opačném případě došlo k chybě.

Chybové podmínky

dest	dest_size	src	Vrácená hodnota	Obsah dest
NULL	jakékoliv	jakékoliv	EINVAL	neupraveno
jakékoliv	jakékoliv	NULL	EINVAL	dest[0] nastaveno na hodnotu 0
jakékoliv	0 nebo příliš malé	jakékoliv	ERANGE	dest[0] nastaveno na hodnotu 0

Poznámky

Funkce strcpy_s zkopíruje obsah v adrese src, včetně ukončujícího znak null, do umístění, které je určeno dest. 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 verze širokého znaku strcpy_sa _mbscpy_s je vícebajtovou verzí. Argumenty jsou řetězce širokého wcscpy_s znaku. Argumenty a _mbscpy_s_mbscpy_s_l jsou řetězce s vícebajtovými znaky. Tyto funkce se chovají stejně jinak. _mbscpy_s_l je identický s _mbscpy_s tím rozdílem, že používá parametr národního prostředí předaný místo aktuálního národního prostředí. Další informace najdete na webu locale.

Pokud dest je nebo src je ukazatel null nebo pokud je cílový řetězec dest_size příliš malý, vyvolá se neplatná obslužná rutina parametru, jak je popsáno v ověření parametru. Pokud je provádění povoleno pokračovat, tyto funkce se vrátí EINVAL a nastaví errno na EINVAL kdy dest nebo src je ukazatel null, a vrátí ERANGE a nastaví errno , ERANGE když je cílový řetězec příliš malý.

Po úspěšném spuštění je cílový řetězec vždy ukončen s hodnotou null.

V jazyce C++ je použití těchto funkcí zjednodušeno přetíženími šablon, které mohou odvodit délku vyrovnávací paměti automaticky, takže nemusíte zadávat argument velikosti. A můžou automaticky nahradit starší, méně zabezpečené funkce novějšími, bezpečnějšími protějšky. Další informace naleznete v tématu Přetížení šablon zabezpečení.

Verze knihovny ladění těchto funkcí nejprve vyplní vyrovnávací paměť 0xFE. Chcete-li toto chování zakázat, použijte _CrtSetDebugFillThreshold.

Ve výchozím nastavení je globální stav této funkce vymezen na aplikaci. Chcete-li toto chování změnit, přečtěte si téma Globální stav v CRT.

Mapování rutin obecného textu

TCHAR.H Rutinní	_UNICODE a _MBCS není definován	_MBCS Definovány	_UNICODE Definovány
_tcscpy_s	strcpy_s	_mbscpy_s	wcscpy_s

Požadavky

Rutina	Požadovaný hlavičkový soubor
strcpy_s	<string.h>
wcscpy_s	<string.h> nebo <wchar.h>
_mbscpy_s	<mbstring.h>

Tyto funkce jsou specifické pro Microsoft. Další informace o kompatibilitě najdete v tématu Kompatibilita.

Příklad

Na rozdíl od kódu kvality produkce tato ukázka volá zabezpečené řetězcové funkce bez kontroly chyb:

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

Při vytváření kódu jazyka C++ se verze šablon můžou snadněji používat.

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

Viz také

Manipulace s řetězci
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