_strnset_s, _strnset_s_l, _wcsnset_s, _wcsnset_s_l, _mbsnset_s, _mbsnset_s_l

Artigo
06/09/2015

Inicializa os caracteres de uma cadeia de caracteres para um determinado caractere. Essas versões de _strnset, _strnset_l, _wcsnset, _wcsnset_l, _mbsnset, _mbsnset_l têm aprimoramentos de segurança, como descrito em Recursos de segurança no CRT.

Importante

_mbsnset_s e _mbsnset_s_l não podem ser usados 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 _strnset_s(
   char *str,
   size_t numberOfElements,
   int c,
   size_t count 
);
errno_t _strnset_s_l(
   char *str,
   size_t numberOfElements,
   int c,
   size_t count,
   locale_t locale
);
errno_t _wcsnset_s(
   wchar_t *str,
   size_t numberOfElements,
   wchar_t c,
   size_t count 
);
errno_t _wcsnset_s_l(
   wchar_t *str,
   size_t numberOfElements,
   wchar_t c,
   size_t count,
   _locale_t locale
);
errno_t _mbsnset_s(
   unsigned char *str,
   size_t numberOfElements,
   unsigned int c,
   size_t count 
);
errno_t _mbsnset_s_l(
   unsigned char *str,
   size_t numberOfElements,
   unsigned int c,
   size_t count,
   _locale_t locale
);

Parâmetros

str
Cadeia de caracteres a ser alterada.
numberOfElements
O tamanho do buffer str.
c
Configuração de caracteres.
count
Número de caracteres a serem definidos.
locale
Localidade a ser usada.

Valor de retorno

Zero se tiver êxito, caso contrário, um código de erro.

Essas funções validam seus argumentos. Se str não for uma cadeia de caracteres válida terminada em nulo ou o argumento de tamanho for menor ou igual a 0, o manipulador de parâmetro inválido á chamado, conforme descrito em Validação do parâmetro. Se a exceção puder continuar, essas funções retornarão um código de erro e definirão errno como código de erro. O código de erro padrão é EINVAL se um valor mais específico não se aplicar.

Comentários

Essas funções definem, no máximo, os primeiros caracteres count de str a c. Se count for maior que o tamanho de str, o tamanho de str será usado no lugar de count. Um erro ocorrerá se count for maior que numberOfElements e ambos os parâmetros forem maiores que o tamanho de str.

_wcsnset_s e _mbsnset_s são versões de caracteres largos e de multibyte de _strnset_s. O argumento de cadeia de caracteres de _wcsnset_s é uma cadeia de caracteres largos; enquanto _mbsnset_s é uma cadeia de caracteres multibyte. Essas três funções se comportam de forma idêntica.

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.

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 & _MBCS não definido	_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
_strnset_s	<string.h>
_strnset_s_l	<tchar.h>
_wcsnset_s	<string.h> ou <wchar.h>
_wcsnset_s_l	<tchar.h>
_mbsnset_s, _mbsnset_s_l	<mbstring.h>

Para informações adicionais de compatibilidade, consulte Compatibilidade.

Exemplo

// crt_strnset_s.c
#include <string.h>
#include <stdio.h>

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