`wcsrtombs_s`

Articolo
10/12/2023

Converte una stringa di caratteri wide nella relativa rappresentazione di stringa di caratteri multibyte. Versione di con miglioramenti della wcsrtombs sicurezza, come descritto in Funzionalità di sicurezza in CRT.

Sintassi

errno_t wcsrtombs_s(
   size_t *pReturnValue,
   char *mbstr,
   size_t sizeInBytes,
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
);
template <size_t size>
errno_t wcsrtombs_s(
   size_t *pReturnValue,
   char (&mbstr)[size],
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
); // 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 o _TRUNCATE.

mbstate
Puntatore a un oggetto stato di conversione mbstate_t.

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, l'eccezione di parametro non valida viene richiamata 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 wcsrtombs_s converte una stringa di caratteri wide a cui punta wcstr in caratteri multibyte archiviati nel buffer a cui punta mbstr, usando lo stato di conversione contenuto in mbstate. 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 , wcsrtombs_s converte la maggior parte della stringa che verrà inserita nel buffer di destinazione, lasciando allo stesso tempo spazio per un terminatore Null.

Se wcsrtombs_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 wcsrtombs_s rileva un carattere wide che non può convertire in un carattere multibyte, inserisce -1 in , imposta il buffer di destinazione su *pReturnValueuna stringa vuota, imposta errno su EILSEQe restituisce EILSEQ.

Se le sequenze a cui punta wcstr e mbstr si sovrappongono, il comportamento di wcsrtombs_s non è definito. wcsrtombs_s viene influenzato dalla categoria LC_TYPE delle impostazioni locali correnti.

Importante

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

La wcsrtombs_s funzione differisce da wcstombs_s, _wcstombs_s_l in base alla riavviibilità. Lo stato di conversione viene archiviato in mbstate per le chiamate successive alle stesse o ad altre funzioni riavviabili. I risultati non sono definiti quando si usano insieme funzioni riavviabili e non riavviabili. Ad esempio, un'applicazione deve usare wcsrlen anziché wcslen se viene usata una chiamata successiva a wcsrtombs_s invece di wcstombs_s.

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.

Eccezioni

La funzione wcsrtombs_s è multithread-safe a condizione che nessuna funzione nel thread corrente chiami setlocale mentre questa funzione è in esecuzione e mbstate è Null.

Esempio

// crt_wcsrtombs_s.cpp
//
// This code example converts a wide
// character string into a multibyte
// character string.
//

#include <stdio.h>
#include <memory.h>
#include <wchar.h>
#include <errno.h>

#define MB_BUFFER_SIZE 100

int main()
{
    const wchar_t   wcString[] =
                    {L"Every good boy does fine."};
    const wchar_t   *wcsIndirectString = wcString;
    char            mbString[MB_BUFFER_SIZE];
    size_t          countConverted;
    errno_t         err;
    mbstate_t       mbstate;

    // Reset to initial shift state
    ::memset((void*)&mbstate, 0, sizeof(mbstate));

    err = wcsrtombs_s(&countConverted, mbString, MB_BUFFER_SIZE,
                      &wcsIndirectString, MB_BUFFER_SIZE, &mbstate);
    if (err == EILSEQ)
    {
        printf( "An encoding error was detected in the string.\n" );
    }
    else
    {
        printf( "The string was successfully converted.\n" );
    }
}

The string was successfully converted.

Requisiti

Ciclo	Intestazione obbligatoria
`wcsrtombs_s`	<wchar.h>

Vedi anche

Conversione dei dati
impostazioni locali
Interpretazione di sequenze di caratteri multibyte
wcrtomb
wcrtomb_s
wctomb, _wctomb_l
wcstombs, _wcstombs_l
mbsinit

Condividi tramite