mbstowcs_s, _mbstowcs_s_lmbstowcs_s, _mbstowcs_s_l

Converte una sequenza di caratteri multibyte in una sequenza di caratteri wide corrispondente.Converts a sequence of multibyte characters to a corresponding sequence of wide characters. Versioni di mbstowcs, _mbstowcs_l con miglioramenti per la sicurezza, come descritto in Funzionalità di sicurezza in CRT.Versions of mbstowcs, _mbstowcs_l with security enhancements as described in Security Features in the CRT.

SintassiSyntax

errno_t mbstowcs_s(  
   size_t *pReturnValue,  
   wchar_t *wcstr,  
   size_t sizeInWords,  
   const char *mbstr,  
   size_t count   
);  
errno_t _mbstowcs_s_l(  
   size_t *pReturnValue,  
   wchar_t *wcstr,  
   size_t sizeInWords,  
   const char *mbstr,  
   size_t count,  
   _locale_t locale  
);  
template <size_t size>  
errno_t mbstowcs_s(  
   size_t *pReturnValue,  
   wchar_t (&wcstr)[size],  
   const char *mbstr,  
   size_t count   
); // C++ only  
template <size_t size>  
errno_t _mbstowcs_s_l(  
   size_t *pReturnValue,  
   wchar_t (&wcstr)[size],  
   const char *mbstr,  
   size_t count,  
   _locale_t locale  
); // C++ only  

ParametriParameters

[out] pReturnValue[out] pReturnValue
Numero di caratteri convertiti.The number of characters converted.

[out] wcstr[out] wcstr
Indirizzo del buffer per la stringa di caratteri wide convertita risultante.Address of buffer for the resulting converted wide character string.

[in] sizeInWords[in] sizeInWords
Dimensioni del buffer wcstr in parole.The size of the wcstr buffer in words.

[in]mbstr[in]mbstr
Indirizzo di una sequenza di caratteri multibyte con terminazione Null.The address of a sequence of null terminated multibyte characters.

[in] count[in] count
Numero massimo di caratteri wide da archiviare nel buffer wcstr, escluso il carattere Null di terminazione o _TRUNCATE.The maximum number of wide characters to store in the wcstr buffer, not including the terminating null, or _TRUNCATE.

[in] locale[in] locale
Impostazioni locali da usare.The locale to use.

Valore restituitoReturn Value

Zero in caso di esito positivo, un codice di errore in caso di esito negativo.Zero if successful, an error code on failure.

Condizione di erroreError condition Valore restituito e errnoReturn value and errno
wcstr è NULL e sizeInWords > 0wcstr is NULL and sizeInWords > 0 EINVAL
mbstr è NULLmbstr is NULL EINVAL
Il buffer di destinazione è troppo piccolo per contenere la stringa convertita (a meno che count non sia _TRUNCATE; vedere la sezione Note di seguito)The destination buffer is too small to contain the converted string (unless count is _TRUNCATE; see Remarks below) ERANGE
wcstr non è NULL e sizeInWords == 0wcstr is not NULL and sizeInWords == 0 EINVAL

Se si verifica una di queste condizioni, viene richiamata l'eccezione di parametro non valido come descritto in Convalida dei parametri.If any of these conditions occurs, the invalid parameter exception is invoked as described in Parameter Validation . Se l'esecuzione può continuare, la funzione restituisce un codice errore e imposta errno come indicato nella tabella.If execution is allowed to continue, the function returns an error code and sets errno as indicated in the table.

NoteRemarks

La funzione mbstowcs_s converte una stringa di caratteri multibyte a cui punta mbstr in caratteri wide archiviati nel buffer a cui punta wcstr.The mbstowcs_s function converts a string of multibyte characters pointed to by mbstr into wide characters stored in the buffer pointed to by wcstr. La conversione continuerà per ogni carattere fino a quando non viene soddisfatta una delle seguenti condizioni:The conversion will continue for each character until one of these conditions is met:

  • Viene rilevato un carattere Null multibyteA multibyte null character is encountered

  • Viene rilevato un carattere multibyte non validoAn invalid multibyte character is encountered

  • Il numero di caratteri wide archiviati nel buffer wcstr è uguale a count.The number of wide characters stored in the wcstr buffer equals count.

    La stringa di destinazione termina sempre con Null, anche in caso di errore.The destination string is always null-terminated (even in the case of an error).

    Se count è il valore speciale _TRUNCATE, mbstowcs_s converte la parte di stringa più ampia possibile che può rientrare nel buffer di destinazione, lasciando però spazio per un carattere di terminazione Null.If count is the special value _TRUNCATE, then mbstowcs_s converts as much of the string as will fit into the destination buffer, while still leaving room for a null terminator.

    Se mbstowcs_s converte correttamente la stringa di origine, inserisce la dimensione in caratteri wide della stringa convertita, incluso il carattere di terminazione Null, in *pReturnValue, a condizione che pReturnValue non sia NULL.If mbstowcs_s successfully converts the source string, it puts the size in wide characters of the converted string, including the null terminator, into *pReturnValue (provided pReturnValue is not NULL). Ciò si verifica anche se l'argomento wcstr è NULL e consente di determinare le dimensioni del buffer richieste.This occurs even if the wcstr argument is NULL and provides a way to determine the required buffer size. Si noti che se wcstr è NULL, count viene ignorato e sizeInWords deve essere 0.Note that if wcstr is NULL, count is ignored, and sizeInWords must be 0.

    Se mbstowcs_s rileva un carattere multibyte non valido, inserisce 0 in *pReturnValue, imposta il buffer di destinazione su una stringa vuota, imposta errno su EILSEQ e restituisce EILSEQ.If mbstowcs_s encounters an invalid multibyte character, it puts 0 in *pReturnValue, sets the destination buffer to an empty string, sets errno to EILSEQ, and returns EILSEQ.

    Se le sequenze a cui punta mbstr e wcstr si sovrappongono, il comportamento di mbstowcs_s non è definito.If the sequences pointed to by mbstr and wcstr overlap, the behavior of mbstowcs_s is undefined.

Importante

Verificare che wcstr e mbstr non si sovrappongano e che count rispecchi correttamente il numero di caratteri multibyte da convertire.Ensure that wcstr and mbstr do not overlap, and that count correctly reflects the number of multibyte characters to convert.

mbstowcs_s usa le impostazioni locali correnti per qualsiasi comportamento dipendente dalle impostazioni locali. La funzione _mbstowcs_s_l è identica, ma usa le impostazioni locali passate.mbstowcs_s uses the current locale for any locale-dependent behavior; _mbstowcs_s_l is identical except that it uses the locale passed in instead. Per altre informazioni, vedere Locale.For more information, see Locale.

In C++ l'utilizzo di queste funzioni è semplificato dagli overload dei modelli. Gli overload possono dedurre la lunghezza del buffer automaticamente (eliminando la necessità di specificare un argomento di dimensione) e possono sostituire automaticamente le funzioni precedenti e non sicure con le controparti più recenti e sicure.In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. Per altre informazioni, vedere Secure Template Overloads.For more information, see Secure Template Overloads.

RequisitiRequirements

RoutineRoutine Intestazione obbligatoriaRequired header
mbstowcs_s <stdlib.h><stdlib.h>
_mbstowcs_s_l <stdlib.h><stdlib.h>

Per altre informazioni sulla compatibilità, vedere la sezione Compatibilità nell'introduzione.For additional compatibility information, see Compatibility in the Introduction.

Vedere ancheSee Also

Data Conversion (Conversione dei dati)Data Conversion
Locale (Impostazioni locali)Locale
MultiByteToWideChar MultiByteToWideChar
Interpretazione di sequenze di caratteri multibyte Interpretation of Multibyte-Character Sequences
_mbclen, mblen, _mblen_l _mbclen, mblen, _mblen_l
mbtowc, _mbtowc_l mbtowc, _mbtowc_l
wcstombs, _wcstombs_l wcstombs, _wcstombs_l
wctomb, _wctomb_lwctomb, _wctomb_l