mbstowcs_s, _mbstowcs_s_l

Articolo
06/09/2015

Converte una sequenza di caratteri multibyte in una corrispondente sequenza di caratteri wide. Versioni di mbstowcs, _mbstowcs_l con i miglioramenti della sicurezza come descritto in Funzionalità di sicurezza in CRT.

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

Parametri

[out] pReturnValue
Numero di caratteri convertiti.
[out] wcstr
L'indirizzo del buffer per la risultante stringa convertita con caratteri estesi.
[in] sizeInWords
Dimensione del buffer wcstr in parole.
[in]mbstr
L'indirizzo di una sequenza di caratteri multibyte con terminazione null.
[in] count
Il numero massimo di caratteri di tipo wide da memorizzare nel buffer wcstr, escluso il carattere di terminazione null, o _TRUNCATE.
[in] locale
Impostazioni locali da utilizzare.

Valore restituito

Zero se ha esito positivo, un codice di errore in caso di errore.

Condizione di errore	Valore di ritorno e errno
wcstr è NULL e sizeInWords > 0	EINVAL
mbstr è NULL.	EINVAL
Il buffer di destinazione è troppo piccolo per contenere la stringa convertita (a meno che count sia _TRUNCATE; vedere i commenti di seguito)	ERANGE
wcstr non è NULL e sizeInWords == 0	EINVAL

Se tutte le condizioni si verificano, l'eccezione del parametro non valido viene invocata come descritto in Convalida dei parametri. Se all'esecuzione è permesso continuare, la funzione restituisce un codice di errore e imposta errno come indicato nella tabella.

Note

La funzione mbstowcs_s converte una stringa di caratteri di tipo multibyte puntati da mbstr nei caratteri wide memorizzati nel buffer puntato da wcstr. La conversione continuerà per ogni carattere finché non verrà soddisfatta una di queste condizioni:

Viene rilevato un carattere null multibyte
Viene rilevato un carattere multibyte non valido
Il numero di caratteri wide memorizzati nel buffer wcstr equivale a count.

La stringa di destinazione è sempre con terminazione null (anche in caso di errore).

Se count è il valore speciale _TRUNCATE, allora mbstowcs_s converte la stringa finché ci sta nel buffer di destinazione, pur lasciando spazio per un terminatore null.

Se mbstowcs_s converte correttamente la stringa di origine, inserisce la dimensione in caratteri wide della stringa convertita, incluso il terminatore null, in *pReturnValue (il valore fornito pReturnValue non è NULL). Questo accade anche se l'argomento wcstr è NULL e consente di determinare la dimensione del buffer richiesto. Si noti che se wcstr è NULL, count viene ignorato e sizeInWords deve essere 0.

Se mbstowcs_s rileva un carattere multibyte non valido, inserisce 0 in *pReturnValue, imposta il buffer di destinazione con una stringa vuota, imposta errno a EILSEQ e restituisce EILSEQ.

Se le sequenze puntate da mbstr e sovrapposizione wcstr, il comportamento mbstowcs_s non è definito.

Nota sulla sicurezza
Assicurarsi che wcstr e mbstr non si sovrappongano e che count rifletta correttamente il numero di caratteri di tipo multibyte da convertire.

mbstowcs_s utilizza le impostazioni locali correnti per qualsiasi comportamento dipendente dalle impostazioni locali; _mbstowcs_s_l è identica, ad eccezione del fatto che utilizza il parametro delle impostazioni locali che viene passato. Per ulteriori informazioni, vedere Impostazioni locali.

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. Per ulteriori informazioni, vedere Overload di modelli sicuri.