strcpy_s, wcscpy_s, _mbscpy_s, _mbscpy_s_l

Copia uma cadeia de caracteres. Essas versões do , , _mbscpytêm aprimoramentos de segurança, wcscpyconforme descrito em Recursos de strcpysegurança na CRT.

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.

Retornar valor

Zero se for bem-sucedido; caso contrário, um código de erro.

Condições de erro

dest	dest_size	src	Retornar valor	Conteúdo de dest
NULL	qualquer	qualquer	EINVAL	não modificado
qualquer	qualquer	NULL	EINVAL	dest[0] definido como 0
qualquer	0 ou muito pequeno	qualquer	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 são cadeias de wcscpy_s 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 ou for um ponteiro nulo, ou src se o tamanho dest_size da cadeia de caracteres de destino for muito pequeno, o manipulador de parâmetros inválido será chamado, 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. Além disso, eles podem substituir automaticamente funções mais antigas e menos seguras por outras mais novas e mais 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, consulte Estado global na 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