strcpy_s, wcscpy_s, _mbscpy_s

Artigo
06/09/2015

Copia uma cadeia de caracteres. Essas versões de strcpy, wcscpy, _mbscpy têm aprimoramentos de segurança, como descrito em Recursos de segurança no CRT.

Importante

_mbscpy_s não pode ser usado em aplicativos que executam no Tempo de Execução do Windows.Para obter mais informações, consulte Funções CRT sem suporte pelo /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 do buffer de cadeia de caracteres de destino.
numberOfElements
Tamanho do buffer de cadeia de caracteres de destino.
strSource
Buffer de fonte de cadeia de caracteres terminado em zero.

Valor de retorno

Zero se tiver êxito; caso contrário, um erro.

Condições de erro

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

Comentários

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

wcscpy_s é a versão de caractere largo do strcpy_s, e _mbscpy_s é a versão de múltiplos caracteres. Os argumentos e o valor de retorno de wcscpy_s são cadeias de caracteres largos; _mbscpy_s são cadeias de caracteres de vários bytes. Essas três funções se comportam de forma idêntica.

Se strDestination ou strSource forem ponteiros nulos ou se a cadeia de caracteres de destino for muito pequena, o manipulador de parâmetro inválido será invocado, conforme descrito em Validação do parâmetro. Se a execução puder continuar, essas funções retornam EINVAL e definem errno para EINVAL quando strDestination ou strSource são um ponteiro nulo e retornam ERANGE e definem errno para ERANGE quando a cadeia de caracteres de destino é muito pequena.

Após a execução bem-sucedida, a cadeia de caracteres de destino terminará sempre com nulo.

No C++, o uso dessas funções é simplificado por sobrecargas de modelo que podem interpretar o tamanho do buffer automaticamente para que você não tenha que especificar um argumento de tamanho, e podem automaticamente substituir funções menos seguras mais antigas por correspondentes mais seguras e mais recentes. Para obter mais informações, consulte Sobrecargas de modelo seguras.

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

Mapeamentos da rotina de texto genérico

Rotina TCHAR.H	_UNICODE & _MBCS não definido	_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 obter informações adicionais sobre compatibilidade, consulte Compatibilidade.

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