mbstowcs_s, _mbstowcs_s_l

Articolo
03/05/2013

Converte una sequenza di caratteri multibyte in una sequenza di caratteri "wide" corrispondente.Le versioni di mbstowcs, _mbstowcs_l con miglioramenti della protezione 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
Il numero di caratteri convertiti.
[out] wcstr
Convertire l'indirizzo del buffer per la stringa di caratteri estesi.
[in] sizeInWords
La dimensione del wcstr buffer in parole.
[in]mbstr
L'indirizzo di una sequenza di null è terminato caratteri multibyte.
[in] count
Il numero massimo di caratteri estesi per memorizzare nel wcstr buffer, escluso il valore null di terminazione o _TRUNCATE.
[in] locale
Impostazioni internazionali da utilizzare.

Valore restituito

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

Condizione di errore	Valore restituito eerrno
wcstris NULL and sizeInWords > 0	EINVAL
mbstr è NULL.	EINVAL
Il buffer di destinazione è troppo piccolo per contenere la stringa convertita (a meno che non count è _TRUNCATE; vedere la sezione Osservazioni riportata di seguito)	ERANGE
wcstris not NULL and sizeInWords == 0	EINVAL

Se una di queste condizioni si verifica, l'eccezione di parametro non valido viene richiamato come descritto in Convalida dei parametri .Se è consentito continuare l'esecuzione, la funzione restituisce un codice di errore e imposta errno come indicato nella tabella.

Note

Il mbstowcs_s funzione converte una stringa di caratteri multibyte a cui fa riferimento mbstr in caratteri wide memorizzati nel buffer a cui fa riferimento wcstr.La conversione continuerà per ogni carattere fino a quando non viene soddisfatta una delle seguenti condizioni:

Viene rilevato un valore null di caratteri multibyte
Viene rilevato un carattere multibyte non valido
Il numero di caratteri estesi, memorizzati nel wcstr buffer è uguale a count.

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

Se count è il valore speciale _TRUNCATE, quindi mbstowcs_s converte la maggior parte della stringa venga adatta nel buffer di destinazione, lasciando ancora spazio per un carattere di terminazione null.

Se mbstowcs_s correttamente converte la stringa di origine, inserisce la dimensione in caratteri "wide" della stringa convertita, includendo il terminatore null, in *pReturnValue (purché pReturnValue non NULL).Questo problema si verifica anche se il wcstr argomento è NULL e fornisce un modo per determinare la dimensione del buffer necessaria.Note that if wcstr is NULL, count is ignored, and sizeInWords must be 0.

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

Se le sequenze a cui fa riferimento mbstr e wcstr si sovrappongono, il comportamento di mbstowcs_s non è definito.

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

mbstowcs_sutilizza le impostazioni internazionali correnti per qualsiasi comportamento dipendente dalle impostazioni internazionali; _mbstowcs_s_lè identico ad eccezione del fatto che utilizza le impostazioni internazionali passata.Per ulteriori informazioni, vedere Impostazioni locali.

In C++, utilizzando queste funzioni viene semplificata dall'overload del modello; gli overload possono dedurre automaticamente la lunghezza di buffer (eliminando la necessità di specificare un argomento size) e possono sostituire automaticamente le funzioni meno recenti, non protetta con le rispettive controparti più recente e sicure.Per ulteriori informazioni, vedere Assicurarsi che gli overload del modello.