_mbccpy_s, _mbccpy_s_l

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

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.

Valor retornado

Zero se for bem-sucedido; um código de erro em caso de falha. Se src ou dest for NULL, ou se mais de bytes forem copiados para dest, o manipulador de buffSizeinBytes parâmetro inválido será invocado, conforme descrito em Validação de 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 inicial de um caractere multibyte, conforme determinado por uma chamada implícita para _ismbblead, o único byte que src aponta para será copiado. Se src apontar para um byte principal, mas o byte seguinte for 0 e, portanto, inválido, 0 será copiado para dest, errno será definido como EILSEQe a função retornará EILSEQ.

_mbccpy_s não acrescenta um terminador nulo; No entanto, se src apontar para um caractere nulo, esse nulo será 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	Valor retornado
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 pressupõe 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, 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
_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