_mbsnbset_s, _mbsnbset_s_l

Articolo
06/09/2015

Imposta i primi n byte di una stringa di caratteri multibyte a un carattere specificato. Queste versioni di _mbsnbset, _mbsnbset_l contengono i miglioramenti della sicurezza come descritto in Funzionalità di sicurezza in CRT.

Importante

Questa API non può essere utilizzata nelle applicazioni eseguite in Windows Runtime.Per ulteriori informazioni, vedere Funzioni CRT non supportate con /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

Parametri

str
Stringa da modificare.
size
La dimensione del buffer della stringa.
c
Impostazione a byte singolo o a caratteri multibyte.
count
Numero di byte da impostare.
locale
Impostazioni locali da utilizzare.

Valore restituito

Zero in caso di esito positivo; un codice di errore altrimenti.

Note

Le funzioni _mbsnbset_s e _mbsnbset_s_l impostano, al massimo, i primi count byte di str a c. Se count è maggiore della lunghezza di str, la lunghezza di str viene utilizzata al posto di count. Se c è un carattere multibyte e non può essere impostato interamente nell'ultimo byte specificato da count, l'ultimo byte viene riempito con un carattere vuoto. _mbsnbset_s e _mbsnbset_s_l non pongono un carattere di terminazione null alla fine di str.

_mbsnbset_s e _mbsnbset_s_l assomigliano a _mbsnset, con la differenza che impostano i byte di count anziché i caratteri di count di c.

Se str è NULL o count è zero, questa funzione genera un'eccezione di parametro non valido come descritto in Convalida dei parametri. Se l'esecuzione può continuare, errno viene impostato su EINVAL e la funzione restituisce NULL. Inoltre, se c non è un carattere multibyte valido, errno è impostato su EINVAL ed, invece, viene utilizzato uno spazio.

Il valore di output è interessato dall'impostazione dell'impostazione della categoria LC_CTYPE delle impostazioni locali. Vedere setlocale, _wsetlocale per ulteriori informazioni. La versione _mbsnbset_s di questa funzione utilizza le impostazioni locali correnti per questo comportamento dipendente dalle impostazioni locali; la versione _mbsnbset_s_l è identica ad eccezione che essa utilizza il parametro delle impostazioni locali che gli viene passato. Per ulteriori informazioni, vedere Impostazioni locali.

In C++, l'utilizzo di queste funzioni viene semplificato dagli overload del modello; gli overload possono dedurre la lunghezza del buffer automaticamente, eliminando la necessità di specificare un argomento per la dimensione. Per ulteriori informazioni, vedere Overload di modelli sicuri.

La versione di debug di queste funzioni per prima cosa riempiono il buffer con il valore 0xFD. Per disattivare questo comportamento, utilizzare _CrtSetDebugFillThreshold.

Mapping di routine di testo generico

Routine Tchar.h	_UNICODE e _MBCS non definiti	_MBCS definito	_UNICODE definito
_tcsnset_s	_strnset_s	_mbsnbset_s	_wcsnset_s
_tcsnset_s_l	_strnset_s _l	_mbsnbset_s_l	_wcsnset_s_l

Requisiti

Routine	Intestazione obbligatoria
_mbsnbset_s	<mbstring.h>
_mbsnbset_s_l	<mbstring.h>

Per ulteriori informazioni sulla compatibilità, vedere Compatibilità.

Esempio

// 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 );
}