wcstombs_s, _wcstombs_s_lwcstombs_s, _wcstombs_s_l

• 11/04/2016
• 6 minuti per la lettura
• Autori di contributi
  • 
  • 
  • 
  • 
  • 

Converte una sequenza di caratteri wide in una sequenza di caratteri multibyte corrispondente.Converts a sequence of wide characters to a corresponding sequence of multibyte characters. Questa è una versione di wcstombs, _wcstombs_l che include miglioramenti per la sicurezza, come descritto in Funzionalità di sicurezza in CRT.A version of wcstombs, _wcstombs_l with security enhancements as described in Security Features in the CRT.

SintassiSyntax

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

ParametriParameters

pReturnValuepReturnValue
Numero di caratteri convertiti.The number of characters converted.

mbstrmbstr
Indirizzo di un buffer per la stringa di caratteri multibyte convertita risultante.The address of a buffer for the resulting converted multibyte character string.

sizeInBytessizeInBytes
Le dimensioni in byte del mbstr buffer.The size in bytes of the mbstr buffer.

wcstrwcstr
Punta alla stringa di caratteri wide da convertire.Points to the wide character string to be converted.

countcount
Il numero massimo di byte da archiviare nel mbstr buffer, escluso il carattere di terminazione null o truncate.The maximum number of bytes to store in the mbstr buffer, not including the terminating null character, or _TRUNCATE.

localelocale
Impostazioni locali da usare.The locale to use.

Valore restituitoReturn Value

Zero in caso di esito positivo, un codice di errore in caso di esito negativo.Zero if successful, an error code on failure.

Se si verifica una di queste condizioni, viene richiamata l'eccezione di parametro non valido come descritto in Convalida dei parametri.If any of these conditions occurs, the invalid parameter exception is invoked as described in Parameter Validation . Se l'esecuzione può continuare, la funzione restituisce un codice di errore e imposta errno come indicato nella tabella.If execution is allowed to continue, the function returns an error code and sets errno as indicated in the table.

NoteRemarks

Il wcstombs_s funzione converte una stringa di caratteri "wide" a cui puntata wcstr in caratteri multibyte archiviati nel buffer a cui puntato mbstr.The wcstombs_s function converts a string of wide characters pointed to by wcstr into multibyte characters stored in the buffer pointed to by mbstr. La conversione continuerà per ogni carattere fino a quando non viene soddisfatta una delle seguenti condizioni:The conversion will continue for each character until one of these conditions is met:

• Viene rilevato un carattere Null wideA null wide character is encountered

• Viene rilevato un carattere wide che non può essere convertitoA wide character that cannot be converted is encountered

• Il numero di byte archiviato nel mbstr buffer equals conteggio.The number of bytes stored in the mbstr buffer equals count.

La stringa di destinazione termina sempre con Null, anche in caso di errore.The destination string is always null-terminated (even in the case of an error).

Se conteggio è il valore speciale truncate, quindi wcstombs_s Converte la gran parte della stringa come rientrano nel buffer di destinazione, lasciando comunque una chat room per un valore null carattere di terminazione.If count is the special value _TRUNCATE, then wcstombs_s converts as much of the string as will fit into the destination buffer, while still leaving room for a null terminator. Se la stringa viene troncata, il valore restituito è STRUNCATE, e la conversione viene considerata riuscita.If the string is truncated, the return value is STRUNCATE, and the conversion is considered successful.

Se wcstombs_s converte correttamente la stringa di origine, inserisce la dimensione in byte della stringa convertita, incluso il terminatore null, in *pReturnValue (fornito pReturnValue non è NULL).If wcstombs_s successfully converts the source string, it puts the size in bytes of the converted string, including the null terminator, into *pReturnValue (provided pReturnValue is not NULL). Questo errore si verifica anche se il mbstr argomento NULL e fornisce un modo per determinare le dimensioni del buffer richieste.This occurs even if the mbstr argument is NULL and provides a way to determine the required buffer size. Si noti che se mbstr viene NULL, conteggio viene ignorato.Note that if mbstr is NULL, count is ignored.

Se wcstombs_s rileva un carattere "wide" non è possibile convertire un carattere multibyte in tale client inserisce 0 *pReturnValue, imposta il buffer di destinazione in una stringa vuota, imposta errno al EILSEQe restituisce EILSEQ.If wcstombs_s encounters a wide character it cannot convert to a multibyte character, it puts 0 in *pReturnValue, sets the destination buffer to an empty string, sets errno to EILSEQ, and returns EILSEQ.

Se le sequenze a cui punta wcstr e mbstr si sovrappongono, il comportamento di wcstombs_s è definito.If the sequences pointed to by wcstr and mbstr overlap, the behavior of wcstombs_s is undefined.

wcstombs_s utilizza le impostazioni locali correnti per qualsiasi comportamento dipendente dalle impostazioni locali; wcstombs_s_l è identica alla wcstombs ad eccezione del fatto che usa le impostazioni locali passate.wcstombs_s uses the current locale for any locale-dependent behavior; _wcstombs_s_l is identical to wcstombs except that it uses the locale passed in instead. Per altre informazioni, vedere Locale.For more information, see 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.In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. Per altre informazioni, vedere Secure Template Overloads.For more information, see Secure Template Overloads.

RequisitiRequirements

Per altre informazioni sulla compatibilità, vedere Compatibilità.For additional compatibility information, see Compatibility.

EsempioExample

Questo programma viene illustrato il comportamento del wcstombs_s (funzione).This program illustrates the behavior of the wcstombs_s function.

// 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);
    }
}

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

Vedere ancheSee also

Conversione dei datiData Conversion
Impostazioni localiLocale
_mbclen, mblen, _mblen_l_mbclen, mblen, _mblen_l
mbstowcs, _mbstowcs_lmbstowcs, _mbstowcs_l
mbtowc, _mbtowc_lmbtowc, _mbtowc_l
wctomb_s, _wctomb_s_lwctomb_s, _wctomb_s_l
WideCharToMultiByteWideCharToMultiByte