strcpy_s, wcscpy_s, _mbscpy_s

Artigo
03/12/2013

Copiar uma cadeia de caracteres.Essas são versões de strcpy, wcscpy, _mbscpy com aprimoramentos de segurança conforme descrito em Recursos de segurança no CRT.

Importante
_mbscpy_s não pode ser usado em aplicativos executados em Tempo de Execução do Windows.Para obter mais informações, consulte Funções de CRT não suportadas com /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

Parâmetros

strDestination
Local de armazenamento de cadeia de caracteres de destino
numberOfElements
Tamanho do buffer de cadeia de caracteres de destino.
strSource
Buffer NULL- terminado de cadeia de caracteres de origem.

Valor de retorno

Zero se com êxito; um erro de outra forma.

Condições de erro

strDestination	numberOfElements	strSource	Valor de Retorno	Conteúdo de strDestination
NULL	alguns	alguns	EINVAL	não modificado
alguns	alguns	NULL	EINVAL	[]strDestination0 definido como 0
alguns	0, ou muito pequeno	alguns	ERANGE	[]strDestination0 definido como 0

Comentários

A função de strcpy_s copia o conteúdo no endereço de strSource, incluindo o caractere de terminação zero, o local especificado por strDestination.A cadeia de caracteres de destino deve ser grande o suficiente para armazenar a cadeia de caracteres de origem, incluindo o caractere de terminação zero.O comportamento de strcpy_s é indefinido se as cadeias de caracteres de origem e de destino sobrepostos.

wcscpy_s e _mbscpy_s são versões de largo- caractere e o caractere multibyte- de strcpy_s respectivamente.Os argumentos e o valor de retorno de wcscpy_s são cadeias de caracteres; todo essas de _mbscpy_s são cadeias de caracteres de multibyte.Essas três funções se comportam de forma idêntica.

Se strDestination ou strSource são um ponteiro zero, ou se a cadeia de caracteres de destino é muito pequena, o manipulador inválido do parâmetro é chamado como descrito em Validação de parâmetro.Se a execução é permitida continuar, essas funções EINVAL de retorno e errno defina a EINVAL.

Após a execução bem-sucedida, a cadeia de caracteres de destino será sempre nula finalizada.

Em C++, usar essas funções é simplificada por sobrecargas de modelo; as sobrecargas podem interpretar o tamanho do buffer (automaticamente que elimina a necessidade de especificar um argumento de tamanho) e podem automaticamente substituir mais antigos, não funções de segurança mais recentes, com suas contrapartes seguros.Para obter mais informações, consulte Proteger Overloads de modelo.

As versões de depuração dessas funções preenchem primeiro o buffer com 0xFE.Para desativar esse comportamento, use _CrtSetDebugFillThreshold.

Mapeamentos da rotina de Genérico- texto

Rotina de TCHAR.H	_UNICODE & _MBCS não definidos	_MBCS definido	_UNICODE definido
_tcscpy_s	strcpy_s	_mbscpy_s	wcscpy_s

Requisitos

Rotina	Cabeçalho necessário
strcpy_s	<string.h>
wcscpy_s	<string.h> ou <wchar.h>
_mbscpy_s	<mbstring.h>

Para informações extras de compatibilidade Compatibilidade na introdução, consulte.

Exemplo

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