strcpy_s, wcscpy_s, _mbscpy_s

Статья
06/09/2015

Копирует строку. В этих версиях strcpy, wcscpy, _mbscpy усовершенствована безопасность, как описано в разделе Функции безопасности в CRT.

Важно!

_mbscpy_s невозможно использовать в приложениях, выполняемых в Среда выполнения Windows.Дополнительные сведения см. в статье Функции CRT, которые не поддерживаются с ключом /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

Параметры

strDestination
Расположение буфера строки назначения.
numberOfElements
Размер буфера строки назначения.
strSource
Буфер строки источника с нулевым завершением.

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

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

Условия возникновения ошибки

strDestination	numberOfElements	strSource	Возвращаемое значение	Содержимое strDestination.
NULL	any	any	EINVAL	без изменений
any	any	NULL	EINVAL	strDestination[0] задан равным 0
any	0 или слишком мало	any	ERANGE	strDestination[0] задан равным 0

Заметки

Функция strcpy_s копирует содержимое в адресе strSource, включая конечный символ null, в расположение, указанное strDestination. Строка назначения должна быть достаточно велика для хранения строки источника и его конечное нуль-символ. При перекрытии исходной и конечной строк поведение инструкции strcpy_s не определено.

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

Если strDestination или strSource является указателем null или целевая строка слишком мала, вызывается обработчик недопустимых параметров, как описано в Проверка параметров. Если среда выполнения может продолжить, эти функции возвращают EINVAL и задают для errno значение EINVAL, если параметр strDestination или strSource — указатель null, и возвращают ERANGE и задают errno равным ERANGE, если строка назначения слишком мала.

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

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

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

Универсальное текстовое сопоставление функций

Подпрограмма 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.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 );
}