_mbsnbcpy_s, _mbsnbcpy_s_l

Artigo
06/09/2015

Copia n bytes de uma cadeia de caracteres para uma cadeia de caracteres de destino. Essas versões de _mbsnbcpy, _mbsnbcpy_l têm aprimoramentos de segurança, como descrito em Recursos de segurança no CRT.

Importante

Esta API não pode ser usada 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 _mbsnbcpy_s(
   unsigned char * strDest,
   size_t sizeInBytes,
   const unsigned char * strSource,
   size_t count 
);
errno_t _mbsnbcpy_s_l(
   unsigned char * strDest,
   size_t sizeInBytes,
   const unsigned char * strSource,
   size_t count,
   _locale_t locale
);
template <size_t size>
errno_t _mbsnbcpy_s(
   unsigned char (&strDest)[size],
   const unsigned char * strSource,
   size_t count 
); // C++ only
template <size_t size>
errno_t _mbsnbcpy_s_l(
   unsigned char (&strDest)[size],
   const unsigned char * strSource,
   size_t count,
   _locale_t locale
); // C++ only

Parâmetros

strDest
Destino da cadeia de caracteres a ser copiada.
sizeInBytes
Tamanho do buffer de destino.
strSource
Cadeia de caracteres a ser copiada.
count
Número de bytes a serem copiados.
locale
Localidade a ser usada.

Valor de retorno

Zero se com êxito; EINVAL se um parâmetro inválido foi passado.

Comentários

A função _mbsnbcpy_s copia count bytes de strSource para strDest. Se count exceder o tamanho de strDest, uma as cadeias de caracteres de entrada for um ponteiro nulo, ou sizeInBytes ou count for 0, a função chamará o manipulador de parâmetro inválido conforme descrito em Validação do parâmetro. Se a execução puder continuar, a função retornará EINVAL. Se as cadeias de caracteres de origem e de destino se sobrepuserem, o comportamento de _mbsnbcpy_s será indefinido.

O valor de saída é afetado pela configuração da categoria LC_CTYPE de localidade. Para obter mais informações, consulte setlocale. As versões dessas funções sem o sufixo _l usam a localidade atual para esse comportamento dependente da localidade; as versões com o sufixo _l são idênticas, exceto que elas usam o parâmetro de localidade informado. Para obter mais informações, consulte Localidade.

Dica

Ao contrário da versão não segura dessa função, _mbsnbcpy_s não faz nenhum preenchimento de nulo e nulo sempre encerra a cadeia de caracteres.

No C++, o uso dessas funções é simplificado por sobrecargas de modelo; as sobrecargas podem interpretar o tamanho do buffer automaticamente (eliminando a necessidade de especificar um argumento de tamanho) e podem substituir automaticamente as 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 0xFD. Para desabilitar esse comportamento, use _CrtSetDebugFillThreshold.

Mapeamentos da rotina de texto genérico