strcpy_s, wcscpy_s, _mbscpy_s, _mbscpy_s_l

Копирует строку. Эти версии ,_mbscpywcscpyимеют улучшения безопасности, как описано в функциях strcpyбезопасности в CRT.

Важно!

Функции _mbscpy_s и _mbscpy_s_l не могут использоваться в приложениях, запускаемых в среде выполнения Windows. Дополнительные сведения: Функции CRT, которые не поддерживаются в приложениях универсальной платформы Windows.

Синтаксис

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

Параметры

dest
Расположение строкового буфера назначения.

dest_size
Размер строкового буфера назначения в единицах char для узкой и многобайтовых функций и в единицах wchar_t для расширенных функций. Это значение должно быть больше нуля, а не больше RSIZE_MAX. Убедитесь, что этот размер учитывается для конца NULL строки.

src
Исходная строка, завершающаяся нулем.

locale
Используемый языковой стандарт.

Возвращаемое значение

Ноль в случае успешного выполнения; в противном случае — код ошибки.

Условия ошибок

dest	dest_size	src	Возвращаемое значение	Содержимое dest
NULL	любое	любое	EINVAL	не изменено
любое	любое	NULL	EINVAL	dest[0] имеет значение 0;
любое	0 или слишком мал	любое	ERANGE	dest[0] имеет значение 0;

Замечания

Функция strcpy_s копирует содержимое по адресу src, включая завершающий символ нуля, в указанное расположение, заданное dest. Строка назначения должна быть достаточно велика для сохранения исходной строки и завершающего нуля. При перекрытии исходного и конечного буферов поведение strcpy_s не определено.

wcscpy_s является версией strcpy_s с расширенными символами, а _mbscpy_s — версией с многобайтовыми символами. Аргументы wcscpy_s являются строками расширенных символов. Аргументы _mbscpy_s и _mbscpy_s_l являются многобайтовыми строками. В остальном эти функции ведут себя одинаково. _mbscpy_s_l идентичен _mbscpy_s тому, что он использует параметр языкового стандарта, переданный вместо текущего языкового стандарта. Дополнительные сведения см. в разделе locale.

Если dest или src является пустым указателем или если размер dest_size целевой строки слишком мал, вызывается обработчик недопустимых параметров, как описано в разделе проверки параметров. Если выполнение может быть продолжено, эти функции возвращают EINVAL и задают для параметра errno значение EINVAL, если dest или src являются пустыми указателями. Они возвращают ERANGE и errno для ERANGE, если строка назначения слишком мала.

После успешного выполнения конечная строка всегда завершается нулем.

В C++использование этих функций упрощается перегрузками шаблонов, которые могут автоматически выводить длину буфера, чтобы не указывать аргумент размера. И они могут автоматически заменить старые, менее безопасные функции более новыми, более безопасными. Дополнительные сведения см. в разделе "Безопасные перегрузки шаблонов".

Версии библиотек отладки этих функций сначала заполняют буфер 0xFE. Чтобы отключить это поведение, используйте _CrtSetDebugFillThreshold.

По умолчанию глобальное состояние этой функции ограничивается приложением. Чтобы изменить это поведение, см . статью "Глобальное состояние" в CRT.

Сопоставления подпрограмм универсального текста

TCHAR.H Обычной	_UNICODE и _MBCS не определен	_MBCS Определенные	_UNICODE Определенные
_tcscpy_s	strcpy_s	_mbscpy_s	wcscpy_s

Требования

Маршрут	Обязательный заголовок
strcpy_s	<string.h>
wcscpy_s	<string.h> или <wchar.h>
_mbscpy_s	<mbstring.h>

Эти функции относятся к корпорации Майкрософт. Дополнительные сведения о совместимости см. в разделе Совместимость.

Пример

В отличие от кода качества рабочей среды, этот пример вызывает безопасные строковые функции без проверка ошибок:

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

При создании кода C++ версии шаблонов могут быть проще использовать.

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

См. также

Обработка строк
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