_mbsnbset_s, _mbsnbset_s_l

Artigo
06/09/2015

Defina os primeiros bytes n de uma cadeia de caracteres multibyte como um caractere especificado. Essas versões de _mbsnbset, _mbsnbset_l têm aprimoramentos de segurança, como 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 _mbsnbset_s(
   unsigned char *str,
   size_t size,
   unsigned int c,
   size_t count 
);
errno_t _mbsnbset_s_l(
   unsigned char *str,
   size_t size,
   unsigned int c,
   size_t count,
   _locale_t locale
);
template <size_t size>
errno_t _mbsnbset_s(
   unsigned char (&str)[size],
   unsigned int c,
   size_t count 
); // C++ only
template <size_t size>
errno_t _mbsnbset_s_l(
   unsigned char (&str)[size],
   unsigned int c,
   size_t count,
   _locale_t locale
); // C++ only

Parâmetros

str
Cadeia de caracteres a ser alterada.
size
O tamanho do buffer de cadeia de caracteres.
c
Configuração de caractere de byte único ou multibyte.
count
Número de bytes a serem definidos.
locale
Localidade a ser usada.

Valor de retorno

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

Comentários

As funções _mbsnbset_s e _mbsnbset_s_l definem, no máximo, os primeiros count bytes de str para c. Se count for maior que o tamanho de str, o tamanho de str será usado no lugar de count. Se c é um caracteres multibyte e não pode ser definido total em bytes do último especificado por count, o byte o último é preenchido com um caractere em branco. _mbsnbset_s e _mbsnbset_s_l não usam um valor nulo encerrando no final de str.

_mbsnbset_s e _mbsnbset_s_l lembram a _mbsnset, exceto que define bytes de count em vez de caracteres de count de c.

Se str é NULL ou count for zero, essa função gerenciar uma exceção inválido do parâmetro, conforme descrito em Validação do parâmetro. Se a execução puder continuar, errno será definido como EINVAL e a função retornará NULL. Além disso, se c não for um caractere multibyte válido, errno será definido como EINVAL e será usado um espaço no lugar.

O valor de saída é afetado pela configuração da categoria LC_CTYPE de localidade. Para obter mais informações, consulte setlocale, _wsetlocale. A versão de _mbsnbset_s dessa função usa a localidade atual para este comportamento dependente de localidade; a versão de _mbsnbset_s_l é idêntica exceto que usa o parâmetro de localidade que é passado. 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. 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

Rotina Tchar.h	_UNICODE e _MBCS não definidos	_MBCS definido	_UNICODE definido
_tcsnset_s	_strnset_s	_mbsnbset_s	_wcsnset_s
_tcsnset_s_l	_strnset_s _l	_mbsnbset_s_l	_wcsnset_s_l

Requisitos

Rotina	Cabeçalho necessário
_mbsnbset_s	<mbstring.h>
_mbsnbset_s_l	<mbstring.h>

Para obter mais informações de compatibilidade, consulte Compatibilidade.

Exemplo

// crt_mbsnbset_s.c
#include <mbstring.h>
#include <stdio.h>

int main( void )
{
   char string[15] = "This is a test";
   /* Set not more than 4 bytes of string to be *'s */
   printf( "Before: %s\n", string );
   _mbsnbset_s( string, sizeof(string), '*', 4 );
   printf( "After:  %s\n", string );
}