_mbccpy_s, _mbccpy_s_l

Copia um caractere multibyte de uma cadeia de caracteres para outra. Essas versões do , têm aprimoramentos de segurança, conforme descrito em Recursos de _mbccpysegurança na CRT. _mbccpy_l

Importante

Esta API não pode ser usada 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 _mbccpy_s(
   unsigned char *dest,
   size_t buffSizeInBytes,
   int * pCopied,
   const unsigned char *src
);
errno_t _mbccpy_s_l(
   unsigned char *dest,
   size_t buffSizeInBytes,
   int * pCopied,
   const unsigned char *src,
   _locale_t locale
);
template <size_t size>
errno_t _mbccpy_s(
   unsigned char (&dest)[size],
   int * pCopied,
   const unsigned char *src
); // C++ only
template <size_t size>
errno_t _mbccpy_s_l(
   unsigned char (&dest)[size],
   int * pCopied,
   const unsigned char *src,
   _locale_t locale
); // C++ only

Parâmetros

dest
Destino da cópia.

buffSizeInBytes
Tamanho do buffer de destino.

pCopied
Preenchido com o número de bytes copiados (1 ou 2 se for bem-sucedido). Passe NULL se você não se importa com o número.

src
Caracteres multibyte para copiar.

locale
Localidade a usar.

Retornar valor

Zero se for bem-sucedido; um código de erro em caso de falha. Se src ou for NULL, ou dest se mais de bytes forem copiados para dest, o manipulador de parâmetros inválido será chamado, conforme descrito em Validação de buffSizeinBytes parâmetro. Se a execução tiver permissão para continuar, as funções retornarão EINVALe errno serão definidas como EINVAL.

Comentários

A função _mbccpy_s copia um caractere multibyte de src para dest. Se src não apontar para o byte principal de um caractere multibyte, conforme determinado por uma chamada implícita para , o byte único para _ismbbleado qual src aponta será copiado. Se src aponta para um byte principal, mas o byte a seguir é 0 e, portanto, inválido, 0 é copiado para dest, é definido como EILSEQ, errno e a função retorna EILSEQ.

_mbccpy_s não acrescenta um terminador nulo; no entanto, se src aponta para um caractere nulo, esse nulo é copiado para dest (como uma cópia regular de byte único).

O valor em pCopied é preenchido com o número de bytes copiados. Os valores possíveis são 1 e 2 se a operação for bem-sucedida. Se NULL for passado, esse parâmetro será ignorado.

src	copiado para dest	pCopied	Retornar valor
byte não inicial	byte não inicial	1	0
0	0	1	0
byte inicial seguido por um valor diferente de 0	byte inicial seguido por um valor diferente de 0	2	0
byte inicial seguido por 0	0	1	EILSEQ

A segunda linha é apenas um caso especial da primeira linha. A tabela assume buffSizeInBytes>= pCopied.

_mbccpy_s usa a localidade atual para qualquer comportamento que dependa da localidade. _mbccpy_s_l é idêntico a _mbccpy_s, exceto que _mbccpy_s_l usa a localidade passada para qualquer comportamento dependente de localidade.

No C++, o uso dessas funções é simplificado por sobrecargas de modelo. As sobrecargas podem inferir automaticamente o tamanho do buffer, eliminando a necessidade de especificar um argumento de tamanho. Para obter mais informações, consulte Sobrecargas de modelo seguras.

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
_tccpy_s	É mapeado para um macro ou uma função embutida.	_mbccpy_s	É mapeado para um macro ou uma função embutida.

Requisitos

Rotina	Cabeçalho necessário
_mbccpy_s	<mbstring.h>
_mbccpy_s_l	<mbstring.h>

Para obter informações sobre compatibilidade, consulte Compatibilidade.

Confira também

Localidade
Interpretação de sequências de caracteres multibyte
_mbclen, mblen, _mblen_l