_mbsnbcat_s, _mbsnbcat_s_l

Artigo
06/09/2015

Anexa a uma cadeia de caracteres multibyte, no máximo, os primeiros bytes de n de outra cadeia de caracteres de multibyte- caractere. Essas são as versões de _mbsnbcat, _mbsnbcat_l que têm os aprimoramentos de segurança, conforme descrito em Recursos de segurança no CRT.

Importante

Não é possível usar essa API em aplicativos executados no Tempo de Execução do Windows.Para obter mais informações, consulte Funções CRT sem suporte pelo /ZW.

errno_t _mbsnbcat_s(
   unsigned char *dest,
   size_t sizeInBytes,
   const unsigned char *src,
   size_t count 
);
errno_t _mbsnbcat_s_l(
   unsigned char *dest,
   size_t sizeInBytes,
   const unsigned char *src,
   size_t count,
   _locale_t locale
);
template <size_t size>
errno_t _mbsnbcat_s(
   unsigned char (&dest)[size],
   const unsigned char *src,
   size_t count 
); // C++ only
template <size_t size>
errno_t _mbsnbcat_s_l(
   unsigned char (&dest)[size],
   const unsigned char *src,
   size_t count,
   _locale_t locale
); // C++ only

Parâmetros

dest
Cadeia de caracteres de destino com caractere multibyte terminado com Null.
sizeInBytes
Tamanho do buffer de dest em bytes.
src
Cadeia de caracteres de origem com caractere multibyte terminado com Null.
Count
Número de bytes de src a serem acrescentados a dest.
locale
Localidade a ser usada.

Valor de retorno

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

Condições de erro

Dest	sizeInBytes	src	Valor de retorno
NULL	any	any	EINVAL
Alguns	<= 0	any	EINVAL
Alguns	any	NULL	EINVAL

Se qualquer uma das condições de erro ocorrer, a função gerencie um erro inválido do parâmetro, conforme descrito em Validação do parâmetro. Se o erro for tratado, a função retornará EINVAL e definirá errno como EINVAL.

Comentários

A função de _mbsnbcat_s anexa a dest, no máximo, os primeiros bytes de count de src. Se o byte que precede imediatamente o caractere nulo em dest é um byte inicial, ele é substituído por byte inicial de src. Caso contrário, o byte inicial de src substituirá o caractere nulo de terminação de dest. Se um byte nulo é exibido em src antes que os bytes de count sejam adicionados, _mbsnbcat_s acrescentará todos os bytes de src, até o caractere nulo. Se count for maior que o tamanho de src, o tamanho de src será usado no lugar de count. A cadeia de caracteres resultante é finalizada por um caractere nulo. Se a cópia for feita entre cadeias de caracteres que se sobrepõem, o comportamento será indefinido.

O valor de saída é afetado pela configuração da categoria LC_CTYPE de localidade. Para obter mais informações, consulte setlocale, _wsetlocale. As versões dessas funções são idênticas, exceto aquelas que não têm o sufixo _l usam a localidade atual e aquelas que têm o sufixo _l, ao contrário, usam o parâmetro de localidade que foi informado. Para obter mais informações, consulte Localidade.

Em C++, o uso dessas funções é simplificado por sobrecargas do modelo; as sobrecargas pode deduzir o comprimento do buffer automaticamente e assim eliminar a necessidade de especificar um argumento de tamanho, e podem usar automaticamente o mais novas funções, mais seguro para substituir mais antigos, funções de menos segura. 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