wcstombs_s, _wcstombs_s_l

Articolo
06/09/2015

Converte una sequenza di caratteri di tipo "wide" a una corrispondente sequenza di caratteri multibyte. Una versione di wcstombs, _wcstombs_l con miglioramenti della sicurezza come descritto in Funzionalità di sicurezza in CRT.

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

Parametri

[out] pReturnValue
Numero di caratteri convertiti.
[out] mbstr
L'indirizzo di un buffer per la stringa convertita risultante di caratteri multibyte.
[in]sizeInBytes
La dimensione, in byte, del buffer mbstr.
[in] wcstr
Punta alla stringa di caratteri estesi da convertire.
[in] count
Il numero massimo di caratteri di tipo "wide" da memorizzare nel buffer mbstr, 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
mbstr è NULL e sizeInBytes > 0	EINVAL
wcstr è 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

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 wcstombs_s converte una stringa di caratteri di tipo "wide" puntati da wcstr nei caratteri multibyte memorizzati nel buffer puntato da mbstr. La conversione continuerà per ogni carattere finché non verrà soddisfatta una di queste condizioni:

Un carattere null di tipo "wide" viene rilevato
Un carattere di tipo "wide" che non può essere convertito viene rilevato
Il numero di byte memorizzati nel buffer mbstr equivale a count.

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

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

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

Se wcstombs_s rileva un carattere di tipo "wide" non può convertire in un carattere multibyte, viene inserito 0 in *pReturnValue, imposta il buffer di destinazione su una stringa vuota, imposta errno a EILSEQ, e restituisce EILSEQ.

Se le sequenze puntate da wcstr e sovrapposizione mbstr, il comportamento wcstombs_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 "wide" per la conversione.

wcstombs_s utilizza le impostazioni locali correnti per i comportamenti dipendenti dalle impostazioni locali; _wcstombs_s_l è identica a wcstombs, ad eccezione del fatto che utilizza il parametro delle impostazioni locali 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.

Requisiti

Routine	Intestazione obbligatoria
wcstombs_s	<stdlib.h>

Per ulteriori informazioni sulla compatibilità, vedere Compatibilità nell'Introduzione.

Esempio

Questo programma mostra il comportamento della funzione wcstombs_s.

// crt_wcstombs_s.c
// This example converts a wide character
// string to a multibyte character string.
#include <stdio.h>
#include <stdlib.h>
#include <assert.h>

#define BUFFER_SIZE 100

int main( void )
{
    size_t   i;
    char      *pMBBuffer = (char *)malloc( BUFFER_SIZE );
    wchar_t*pWCBuffer = L"Hello, world.";

    printf( "Convert wide-character string:\n" );

    // Conversion
    wcstombs_s(&i, pMBBuffer, (size_t)BUFFER_SIZE, 
               pWCBuffer, (size_t)BUFFER_SIZE );

    // Output
    printf("   Characters converted: %u\n", i);
    printf("    Multibyte character: %s\n\n",
     pMBBuffer );

    // Free multibyte character buffer
    if (pMBBuffer)
    {
    free(pMBBuffer);
    }
}