strcpy_s
, wcscpy_s
, _mbscpy_s
, _mbscpy_s_l
Copia uma cadeia de caracteres. Essas versões do , , _mbscpy
têm aprimoramentos destrcpy
segurança, conforme descrito em Recursos de segurança no CRT. wcscpy
Importante
_mbscpy_s
e _mbscpy_s_l
não podem ser usados em aplicativos executados no Windows Runtime. Para obter mais informações, confira Funções do CRT sem suporte em aplicativos da Plataforma Universal do Windows.
Sintaxe
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
Parâmetros
dest
Local do buffer de cadeia de caracteres de destino.
dest_size
Tamanho do buffer de cadeia de caracteres de destino em unidades char
para funções estreitas e multibyte e em unidades wchar_t
para funções largas. Esse valor precisa ser maior que zero e não maior que RSIZE_MAX
. Verifique se esse tamanho é responsável pela terminação NULL
após a cadeia de caracteres.
src
Buffer de cadeia de caracteres de origem com terminação nula.
locale
Localidade a usar.
Valor retornado
Zero se for bem-sucedido; caso contrário, um código de erro.
Condições de erro
dest |
dest_size |
src |
Valor retornado | Conteúdo de dest |
---|---|---|---|---|
NULL |
any | any | EINVAL |
não modificado |
any | any | NULL |
EINVAL |
dest[0] definido como 0 |
any | 0 ou muito pequeno | any | ERANGE |
dest[0] definido como 0 |
Comentários
A função strcpy_s
copia o conteúdo no endereço do src
, incluindo o caractere nulo de terminação, para o local especificado pelo dest
. A cadeia de caracteres de destino deve ser grande o suficiente para conter a cadeia de caracteres de origem e o caractere nulo de terminação. O comportamento de strcpy_s
é indefinido se as cadeias de origem e destino se sobrepõem.
wcscpy_s
é a versão de caracteres largos de strcpy_s
e _mbscpy_s
é a versão de caracteres multibyte. Os argumentos de wcscpy_s
são cadeias de caracteres largos. Os argumentos de e _mbscpy_s_l
são cadeias de _mbscpy_s
caracteres multibyte. Caso contrário, essas funções se comportam de forma idêntica. _mbscpy_s_l
é idêntico a _mbscpy_s
, exceto que ele usa o parâmetro de localidade fornecido em vez da localidade atual. Para obter mais informações, consulte locale
.
Se dest
or src
for um ponteiro nulo, ou se o tamanho dest_size
da cadeia de caracteres de destino for muito pequeno, o manipulador de parâmetro inválido será invocado, conforme descrito em Validação de parâmetro. Se a execução puder continuar, essas funções retornarão EINVAL
e definirão errno
para EINVAL
quando dest
ou src
é um ponteiro nulo, além de retornarem ERANGE
e definirem errno
para ERANGE
quando a cadeia de caracteres de destino é muito pequena.
No caso de execução bem-sucedida, a cadeia de caracteres de destino é sempre terminada em nulo.
Em C++, o uso dessas funções é simplificado por sobrecargas de modelo que podem inferir o comprimento do buffer automaticamente, para que você não precise especificar um argumento de tamanho. E eles podem substituir automaticamente funções mais antigas e menos seguras por contrapartes mais novas e seguras. Para obter mais informações, consulte Sobrecargas de modelo seguras.
As versões de biblioteca de depuração dessas funções preenchem o buffer com 0xFE. Para desabilitar esse comportamento, use _CrtSetDebugFillThreshold
.
Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, confira Estado global no CRT.
Mapeamentos de rotina de texto genérico
Rotina TCHAR.H |
_UNICODE e _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> |
Essas funções são específicas da Microsoft. Para obter informações sobre compatibilidade, consulte Compatibilidade.
Exemplo
Ao contrário do código de qualidade de produção, este exemplo chama as funções de cadeia de caracteres seguras sem verificar se há erros:
// 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!
Quando você está criando código C++, as versões do modelo podem ser mais fáceis de usar.
// 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!
Confira também
Manipulação de cadeia de caracteres
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