wcstombs_s, _wcstombs_s_l

Converte una sequenza di caratteri wide in una sequenza di caratteri multibyte corrispondente. Versione di , _wcstombs_lcon miglioramenti della wcstombssicurezza, come descritto in Funzionalità di sicurezza in CRT.

Sintassi

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

pReturnValue
Dimensione in byte della stringa convertita, incluso il carattere di terminazione Null.

mbstr
Indirizzo di un buffer per la stringa di caratteri multibyte convertita risultante.

sizeInBytes
Dimensione del buffer mbstr, in byte.

wcstr
Punta alla stringa di caratteri wide da convertire.

count
Numero massimo di byte da archiviare nel mbstr buffer, non incluso il carattere Null di terminazione o _TRUNCATE.

locale
Impostazioni locali da usare.

Valore restituito

Zero in caso di esito positivo, un codice di errore in caso di esito negativo.

Condizione di errore	Valore restituito 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 non sia _TRUNCATE; vedere la sezione Note di seguito)	ERANGE

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

Osservazioni:

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

• Viene rilevato un carattere Null wide

• Viene rilevato un carattere wide che non può essere convertito

• Il numero di byte archiviati nel buffer mbstr è uguale a count.

La stringa di destinazione è sempre con terminazione Null (anche se si verifica un errore).

Se count è il valore _TRUNCATEspeciale , wcstombs_s converte la maggior parte della stringa che verrà inserita nel buffer di destinazione, lasciando allo stesso tempo spazio per un terminatore Null. Se la stringa viene troncata, il valore restituito è STRUNCATEe la conversione viene considerata riuscita.

Se wcstombs_s la stringa di origine viene convertita correttamente, inserisce le dimensioni in byte della stringa convertita, incluso il terminatore Null, in *pReturnValue (specificato pReturnValue non NULLè ). La dimensione viene calcolata anche se l'argomento mbstr è NULL; fornisce un modo per determinare le dimensioni del buffer necessarie. Se mbstr è NULL, count viene ignorato.

Se wcstombs_s rileva un carattere wide che non può convertire in un carattere multibyte, inserisce 0 in , imposta il buffer di destinazione su *ReturnValueuna stringa vuota, imposta errno su EILSEQe restituisce EILSEQ.

Se le sequenze a cui punta wcstr e mbstr si sovrappongono, il comportamento di wcstombs_s non è definito.

Importante

Verificare che wcstr e mbstr non si sovrappongano e che count rispecchi correttamente il numero di caratteri wide da convertire.

wcstombs_s usa le impostazioni locali correnti per qualsiasi comportamento dipendente dalle impostazioni locali. La funzione _wcstombs_s_l è identica a wcstombs, ma usa le impostazioni locali passate. Per altre informazioni, vedere 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. Per altre informazioni, vedere Proteggere gli overload dei modelli.

Per impostazione predefinita, lo stato globale di questa funzione è limitato all'applicazione. Per modificare questo comportamento, vedere Stato globale in CRT.

Requisiti

Ciclo	Intestazione obbligatoria
wcstombs_s	<stdlib.h>

Per altre informazioni sulla compatibilità, vedere Compatibility (Compatibilità).

Esempio

Questo programma illustra 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 );
    const 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 - 1); // -1 so the appended NULL doesn't fall outside the allocated buffer

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

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

Convert wide-character string:
   Characters converted: 14
    Multibyte character: Hello, world.

Vedi anche

Conversione dei dati
impostazioni locali
_mbclen, mblen, _mblen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
wctomb_s, _wctomb_s_l
WideCharToMultiByte